gateway: review fixes — refuse unresolvable projects, durable one-shot TTS, uuid Signal principals

P1: a queued task whose snapshotted project was disabled or deleted
before execution is now REFUSED with a durable reply — ResolveProject
failure no longer falls back to the gateway default root, closing the
contradiction with the 'never helpfully run elsewhere' claim. All
refusal paths share one helper; regression test added.

P2 (TTS): voice replies are synthesized exactly ONCE, at job completion,
and the spool ID is persisted on the replied row — a delivery retry or a
restart re-sends the same file instead of re-billing TTS ('always') or
losing the in_kind decision (attachments aren't loaded by the replay).

P2 (Signal): the principal is now the account UUID — Signal's stable
identity — with the phone number only as fallback; numbers change hands.
Pairing keeps uuids painless to allow-list.

P2/P3 (email): the From-address identity caveat is now stated in the
package doc and both docs (allow-list strength depends on the provider's
SPF/DKIM/DMARC filtering; dedicated mainstream account advised);
explicit Authentication-Results enforcement is a tracked follow-up.

Author: timothyerwin

docs/gateway/README.md

@@ -50,7 +50,10 @@ Webhook-driven surfaces (Teams, Google Chat, SMS, GitHub, WhatsApp) mount on
 the shared listener (`webhook.addr`, default `:8787`) at
 `/webhook/{teams,googlechat,sms,github,whatsapp}` — expose it over HTTPS.
 Email dedup is keyed on `<mailbox>/<UIDVALIDITY>/<UID>` (the provider-side ack
-identity); Message-ID serves threading only. Signal requires a signal-cli
+identity); Message-ID serves threading only. Email's sender identity is the
+RFC From address — weaker than the other channels' platform-verified ids, so
+its allow-list depends on your mailbox provider rejecting spoofed mail
+(SPF/DKIM/DMARC); use a mainstream provider and a dedicated account. Signal requires a signal-cli
 daemon in native HTTP mode; Matrix v1 is plain rooms only (E2EE is a known
 follow-up).
 

internal/channels/email/email.go

@@ -9,6 +9,14 @@
 // re-fetches it. The durable dedup key is <mailbox>/<UIDVALIDITY>/<UID> — the
 // provider-side identity, robust against malformed or duplicated Message-IDs
 // (which serve threading, not dedup).
+//
+// IDENTITY CAVEAT: the principal is the RFC From address — weaker than the
+// other channels' platform-authenticated ids, since From can be spoofed by
+// mail that evades the provider's SPF/DKIM/DMARC filtering. The mailbox
+// provider's authentication is the real gate (a mainstream provider rejects or
+// junks spoofed mail before we poll it), which is one more reason for the
+// dedicated-account model. Enforcing Authentication-Results=pass explicitly is
+// a tracked follow-up.
 package email
 
 import (

internal/channels/signal/signal.go

@@ -174,13 +174,15 @@ func parseEnvelope(raw []byte, account string) (channels.Inbound, []attachmentRe
 	if dm == nil {
 		return channels.Inbound{}, nil, false // receipt/typing/sync — not a message
 	}
-	// Principal: the E.164 number when known (the identity users recognize and
-	// allow-list), the uuid otherwise. Our own messages are skipped (loops).
-	principal := env.SourceNumber
+	// Principal: the account UUID — Signal's STABLE identity. A phone number can
+	// change hands or be re-registered, so it is only the fallback when the
+	// daemon didn't surface a uuid. The pairing flow makes uuids painless to
+	// allow-list (nobody has to type one). Our own messages are skipped (loops).
+	principal := env.SourceUUID
 	if principal == "" {
-		principal = env.SourceUUID
+		principal = env.SourceNumber
 	}
-	if principal == "" || principal == account {
+	if principal == "" || env.SourceNumber == account || principal == account {
 		return channels.Inbound{}, nil, false
 	}
 	var refs []attachmentRef

internal/channels/signal/signal_test.go

@@ -19,13 +19,14 @@ func TestParseEnvelopeDM(t *testing.T) {
 	if !ok {
 		t.Fatal("parse failed")
 	}
-	if inb.Channel != "signal" || inb.Principal != "+15551230000" || inb.Conversation != "+15551230000" {
+	// Principal is the STABLE uuid; the phone number is only a fallback.
+	if inb.Channel != "signal" || inb.Principal != "uuid-1" || inb.Conversation != "uuid-1" {
 		t.Errorf("inbound = %+v", inb)
 	}
 	if !inb.IsDirect || inb.Mentioned {
 		t.Errorf("gating = %+v", inb)
 	}
-	if inb.MessageID != "+15551230000:1700000000001" {
+	if inb.MessageID != "uuid-1:1700000000001" {
 		t.Errorf("MessageID = %q (dedup key is sender:timestamp)", inb.MessageID)
 	}
 	if len(refs) != 0 {

internal/gateway/server/media.go

@@ -52,9 +52,11 @@ func newSpeaker() speaker {
 }
 
 // maybeSpeak synthesizes a voice rendition of a reply when the channel's
-// voice_replies policy asks for one, returning the spool path ("" = text
-// only). Policy: "always", or "in_kind" when the task arrived with a voice
-// note. Failures degrade silently to text — a reply is never lost to TTS.
+// voice_replies policy asks for one, returning the SPOOL ID ("" = text only) —
+// the durable handle that rides the replied row, so retries and restarts
+// re-send the same file instead of re-billing TTS. Policy: "always", or
+// "in_kind" when the task arrived with a voice note. Failures degrade silently
+// to text — a reply is never lost to TTS.
 func (r *runtime) maybeSpeak(ctx context.Context, it state.Item, reply string) string {
 	if r.tts == nil {
 		return ""
@@ -87,7 +89,7 @@ func (r *runtime) maybeSpeak(ctx context.Context, it state.Item, reply string) s
 	if err != nil {
 		return ""
 	}
-	return att.Path
+	return att.ID()
 }
 
 // spokenSummary renders a reply as speakable text: code blocks dropped (nobody

internal/gateway/server/media_test.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/memcode-ai/memcode/internal/channels"
 	gwconfig "github.com/memcode-ai/memcode/internal/gateway/config"
 	"github.com/memcode-ai/memcode/internal/gateway/state"
 )
@@ -79,7 +80,10 @@ func TestMaybeSpeakPolicy(t *testing.T) {
 	if p == "" || tts.called != 1 {
 		t.Fatalf("in_kind with voice note: %q %d", p, tts.called)
 	}
-	if _, err := os.Stat(p); err != nil {
+	// The return is a durable spool ID, not a path — it must resolve in the spool.
+	if resolved, err := channels.ResolveSpoolID(dir, p); err != nil {
+		t.Errorf("voice id %q must resolve in the spool: %v", p, err)
+	} else if _, err := os.Stat(resolved); err != nil {
 		t.Errorf("voice file missing: %v", err)
 	}
 	rt.settings = gwconfig.Settings{Channels: map[string]gwconfig.Channel{"telegram": {VoiceReplies: "always"}}}

internal/gateway/server/reply_test.go

@@ -35,7 +35,7 @@ func TestDeliverReplySurvivesSendFailure(t *testing.T) {
 
 	it := state.Item{Channel: "telegram", MessageID: "m1", Conversation: "42", Principal: "p", Text: "hi"}
 	gw.Accept(ctx, it, time.Unix(1000, 0))
-	if err := gw.SetReplied(ctx, "telegram", "m1", "the answer"); err != nil {
+	if err := gw.SetReplied(ctx, "telegram", "m1", "the answer", ""); err != nil {
 		t.Fatal(err)
 	}
 

internal/gateway/server/selection_test.go

@@ -3,7 +3,9 @@ package server
 import (
 	"context"
 	"io"
+	"strings"
 	"testing"
+	"time"
 
 	"github.com/memcode-ai/memcode/internal/channels"
 	gwconfig "github.com/memcode-ai/memcode/internal/gateway/config"
@@ -112,3 +114,41 @@ func TestChannelProjectPolicy(t *testing.T) {
 		t.Errorf("resolveSelection default = %q, want www (channel policy)", p)
 	}
 }
+
+// A queued task whose snapshotted project is disabled or deleted before
+// execution is REFUSED — never run in the gateway default root (P1 from the
+// channels-baseline review).
+func TestRunJobRefusesUnresolvableProject(t *testing.T) {
+	ctx := context.Background()
+	gw, err := state.Open(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer gw.Close()
+
+	sender := &capturingSender{}
+	rt := &runtime{
+		root: t.TempDir(),
+		gw:   gw,
+		settings: gwconfig.Settings{
+			// The id is allowed on the channel, but the project itself is disabled.
+			Projects: map[string]gwconfig.Project{"www": {Path: t.TempDir(), Enabled: false}},
+		},
+		mediaDir: t.TempDir(),
+		byName:   map[string]replySender{"telegram": sender},
+		out:      io.Discard,
+		notify:   make(chan struct{}, 1),
+	}
+	it := state.Item{Channel: "telegram", MessageID: "m1", Conversation: "1", Principal: "me", Text: "do it", Project: "www"}
+	if _, err := gw.Accept(ctx, it, time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	rt.runJob(ctx, it)
+	if !strings.Contains(sender.last, "no longer available") {
+		t.Fatalf("want refusal reply, got %q", sender.last)
+	}
+	// The refusal is durable: the item moved past pending without spawning.
+	if p, _ := gw.Pending(ctx); len(p) != 0 {
+		t.Errorf("item still pending: %+v", p)
+	}
+}

internal/gateway/server/server.go

@@ -419,28 +419,22 @@ func (r *runtime) runJob(ctx context.Context, it state.Item) {
 	cfg := settings.Get(it.Channel)
 	session := conversationSession(it.Channel, it.Conversation, it.Agent)
 	// Resolve the snapshotted project id to its canonical root. The registry plus
-	// the channel's project policy is the authorization boundary: an id that no
-	// longer resolves — or that the channel is no longer allowed to use — falls
-	// back to the gateway default rather than executing somewhere unauthorized.
+	// the channel's project policy is the authorization boundary, re-checked at
+	// EXECUTION, not only at snapshot: a task whose project was disallowed,
+	// disabled, or deleted while queued is REFUSED — never "helpfully" run in the
+	// gateway default root instead.
 	root := r.root
 	if it.Project != "" {
-		// The channel's project policy is re-checked at execution, not only at
-		// snapshot: if it tightened while this task was queued, refuse — never
-		// "helpfully" run the task somewhere the channel wasn't pointed.
 		if !settings.ProjectAllowed(it.Channel, it.Project) {
-			msg := fmt.Sprintf("Project %q is not allowed on this channel anymore; nothing was run.", it.Project)
-			if serr := r.gw.SetReplied(ctx, it.Channel, it.MessageID, msg); serr != nil {
-				fmt.Fprintf(r.out, "gateway: recording policy refusal for %s: %v\n", it.Channel, serr)
-				return
-			}
-			r.deliverReply(ctx, it, msg)
+			r.refuse(ctx, it, fmt.Sprintf("Project %q is not allowed on this channel anymore; nothing was run.", it.Project))
 			return
 		}
-		if resolved, rerr := settings.ResolveProject(it.Project); rerr == nil {
-			root = resolved
-		} else {
-			fmt.Fprintf(r.out, "gateway: project %q for %s no longer resolves (%v); using default\n", it.Project, it.Channel, rerr)
+		resolved, rerr := settings.ResolveProject(it.Project)
+		if rerr != nil {
+			r.refuse(ctx, it, fmt.Sprintf("Project %q is no longer available (%v); nothing was run.", it.Project, rerr))
+			return
 		}
+		root = resolved
 	}
 	// Voice notes are transcribed HERE — after the durable record, before the
 	// spawn — so the transcript becomes task text and audio never reaches the
@@ -449,12 +443,7 @@ func (r *runtime) runJob(ctx context.Context, it state.Item) {
 	// an empty task.
 	task, rest, sttMissing := r.transcribeAudio(ctx, it.Text, it.Attachments)
 	if strings.TrimSpace(task) == "" && sttMissing {
-		msg := "Voice note received, but no transcription provider is configured. Set OPENAI_API_KEY or GEMINI_API_KEY on the gateway machine, or send text."
-		if serr := r.gw.SetReplied(ctx, it.Channel, it.MessageID, msg); serr != nil {
-			fmt.Fprintf(r.out, "gateway: recording voice-note refusal for %s: %v\n", it.Channel, serr)
-			return
-		}
-		r.deliverReply(ctx, it, msg)
+		r.refuse(ctx, it, "Voice note received, but no transcription provider is configured. Set OPENAI_API_KEY or GEMINI_API_KEY on the gateway machine, or send text.")
 		return
 	}
 	it.Text = task
@@ -471,12 +460,7 @@ func (r *runtime) runJob(ctx context.Context, it state.Item) {
 	if err != nil {
 		// A spawn failure won't succeed on replay; record the error as the reply so
 		// it rides the same durable delivery path instead of being lost.
-		msg := "Couldn't start that: " + err.Error()
-		if serr := r.gw.SetReplied(ctx, it.Channel, it.MessageID, msg); serr != nil {
-			fmt.Fprintf(r.out, "gateway: recording spawn failure for %s: %v\n", it.Channel, serr)
-			return
-		}
-		r.deliverReply(ctx, it, msg)
+		r.refuse(ctx, it, "Couldn't start that: "+err.Error())
 		return
 	}
 	r.event(ctx, events.KindGatewayJobSpawned, eventPayload{Channel: it.Channel, Conversation: it.Conversation, PrincipalID: it.Principal, MessageID: it.MessageID, JobID: job.ID})
@@ -486,16 +470,33 @@ func (r *runtime) runJob(ctx context.Context, it state.Item) {
 	if strings.TrimSpace(reply) == "" {
 		reply = "Done."
 	}
+	// Synthesize any voice rendition ONCE, here — before the durable handoff — so
+	// a delivery retry or a restart re-sends the same spool file instead of
+	// re-billing TTS or losing the in_kind decision (the pending-replies replay
+	// carries the voice spool ID, not the attachment list).
+	voice := r.maybeSpeak(ctx, it, reply)
 	// Durable handoff: the job is finished and must never re-run, even if delivery
 	// below fails or the process crashes. From here the reply is the worker's to
 	// deliver. A rare DB write failure leaves the item pending and re-runs it.
-	if err := r.gw.SetReplied(ctx, it.Channel, it.MessageID, reply); err != nil {
+	if err := r.gw.SetReplied(ctx, it.Channel, it.MessageID, reply, voice); err != nil {
 		fmt.Fprintf(r.out, "gateway: recording reply for %s failed: %v\n", it.Channel, err)
 		return
 	}
+	it.Voice = voice
 	r.deliverReply(ctx, it, reply)
 }
 
+// refuse records msg as the task's durable reply (no job runs, no voice is
+// synthesized) and delivers it — the one shape every policy/config refusal uses.
+func (r *runtime) refuse(ctx context.Context, it state.Item, msg string) {
+	it.Voice = ""
+	if serr := r.gw.SetReplied(ctx, it.Channel, it.MessageID, msg, ""); serr != nil {
+		fmt.Fprintf(r.out, "gateway: recording refusal for %s: %v\n", it.Channel, serr)
+		return
+	}
+	r.deliverReply(ctx, it, msg)
+}
+
 // deliverReply sends a finished job's reply and, on success, marks the item done.
 // A transient send failure is retried in-process a few times; if it still fails
 // the item stays 'replied' and the worker retries it on a later tick and after a
@@ -509,7 +510,14 @@ func (r *runtime) deliverReply(ctx context.Context, it state.Item, reply string)
 	if strings.TrimSpace(reply) == "" {
 		reply = "Done."
 	}
-	out := channels.Outbound{Text: reply, VoicePath: r.maybeSpeak(ctx, it, reply)}
+	out := channels.Outbound{Text: reply}
+	// The voice rendition was synthesized once at job completion; delivery only
+	// resolves its spool ID (missing/pruned file → text only, never an error).
+	if it.Voice != "" {
+		if p, err := channels.ResolveSpoolID(r.mediaDir, it.Voice); err == nil {
+			out.VoicePath = p
+		}
+	}
 	var sendErr error
 	for attempt := 0; attempt < 3; attempt++ {
 		if attempt > 0 {

internal/gateway/state/state.go

@@ -36,6 +36,7 @@ CREATE TABLE IF NOT EXISTS inbox (
     agent        TEXT NOT NULL DEFAULT '', -- persona snapshot at receipt (immutable for this task)
     project      TEXT NOT NULL DEFAULT '', -- project id snapshot at receipt (immutable for this task)
     attachments  TEXT NOT NULL DEFAULT '', -- JSON array of media spool IDs riding this message
+    voice        TEXT NOT NULL DEFAULT '', -- spool ID of the synthesized voice reply (synthesized ONCE, at job completion)
     received_at  TEXT NOT NULL,
     PRIMARY KEY (channel, message_id)
 );
@@ -111,6 +112,7 @@ type Item struct {
 	Agent        string   // persona snapshot at receipt
 	Project      string   // project id snapshot at receipt
 	Attachments  []string // media spool IDs (bare filenames; resolved only inside the spool)
+	Voice        string   // spool ID of the synthesized voice reply ("" = text only)
 }
 
 // Store is the gateway's durable state.
@@ -162,6 +164,7 @@ func Open(ctx context.Context, dir string) (*Store, error) {
 		`ALTER TABLE inbox ADD COLUMN agent TEXT NOT NULL DEFAULT ''`,
 		`ALTER TABLE inbox ADD COLUMN project TEXT NOT NULL DEFAULT ''`,
 		`ALTER TABLE inbox ADD COLUMN attachments TEXT NOT NULL DEFAULT ''`,
+		`ALTER TABLE inbox ADD COLUMN voice TEXT NOT NULL DEFAULT ''`,
 	} {
 		if _, err := db.ExecContext(ctx, col); err != nil && !strings.Contains(err.Error(), "duplicate column") {
 			_ = db.Close()
@@ -258,14 +261,16 @@ func (s *Store) Pending(ctx context.Context) ([]Item, error) {
 	return out, rows.Err()
 }
 
-// SetReplied durably records a finished job's reply and moves the item to
-// 'replied'. From here the job is never re-run; only the reply's delivery is
-// retried, so a send failure or a crash after the job completes cannot lose the
-// result or repeat the work.
-func (s *Store) SetReplied(ctx context.Context, channel, messageID, reply string) error {
+// SetReplied durably records a finished job's reply — and, when one was
+// synthesized, the spool ID of its voice rendition — and moves the item to
+// 'replied'. From here the job is never re-run and the voice is never
+// re-synthesized; only the reply's delivery is retried, so a send failure, a
+// crash, or a down channel cannot lose the result, repeat the work, or bill
+// TTS twice.
+func (s *Store) SetReplied(ctx context.Context, channel, messageID, reply, voice string) error {
 	_, err := s.db.ExecContext(ctx,
-		`UPDATE inbox SET status = 'replied', reply = ? WHERE channel = ? AND message_id = ?`,
-		reply, channel, messageID)
+		`UPDATE inbox SET status = 'replied', reply = ?, voice = ? WHERE channel = ? AND message_id = ?`,
+		reply, voice, channel, messageID)
 	return err
 }
 
@@ -274,7 +279,7 @@ func (s *Store) SetReplied(ctx context.Context, channel, messageID, reply string
 // and replayed after a restart.
 func (s *Store) PendingReplies(ctx context.Context) ([]Item, error) {
 	rows, err := s.db.QueryContext(ctx,
-		`SELECT channel, message_id, conversation, principal, text, trusted, reply
+		`SELECT channel, message_id, conversation, principal, text, trusted, reply, voice
 		   FROM inbox WHERE status = 'replied' ORDER BY received_at`)
 	if err != nil {
 		return nil, fmt.Errorf("pending replies: %w", err)
@@ -284,7 +289,7 @@ func (s *Store) PendingReplies(ctx context.Context) ([]Item, error) {
 	for rows.Next() {
 		var it Item
 		var trusted int
-		if err := rows.Scan(&it.Channel, &it.MessageID, &it.Conversation, &it.Principal, &it.Text, &trusted, &it.Reply); err != nil {
+		if err := rows.Scan(&it.Channel, &it.MessageID, &it.Conversation, &it.Principal, &it.Text, &trusted, &it.Reply, &it.Voice); err != nil {
 			return nil, err
 		}
 		it.Trusted = trusted != 0