[sonichi]

Why

The two voice surfaces that don't go through task-bridge.ts (the discord-voice and phone services) have only a per-task existsSync poll: each can pick up results for tasks IT delegated, but there's no native path to claim a result for a task it didn't delegate (e.g. a context handoff from another surface).

This PR gives them a narrow native pull path: a scoped filename namespace results/<channel-key>.task-{id}.txt. Existing consumers are not modified.

Design (the 7 locked points)

1. New filename namespace. results/<channel-key>.task-{id}.txt, used only when a task-result needs to reach a non-delegating consumer. Regular task results keep results/task-{id}.txt.
2. Channel key per surface.
   • discord-voice → the voice channel id (CHANNEL_ID)
   • phone → the Twilio call SID (per-call unique)
3. discord-voice-server.ts — readdirSync scan filtered by <CHANNEL_ID>.task- prefix; on match, injects body into the voice session via transport.sendContent (same path the work-tool resultQueue drain uses), then unlinkSync to prevent re-delivery. 3s cadence.
4. conversation-server.ts — same scan but scoped per active call's SID. State and interval live on CallSession and are torn down in cleanupCall.
5. Core write convention. Documented in CLAUDE.md's task-bridge section: when a task-result needs cross-consumer pickup, write results/<channel-key>.task-{id}.txt; otherwise the existing results/task-{id}.txt is the default.
6. Existing consumers (discord-bridge.py, telegram-bridge.py, slack-bridge.py, task-bridge.ts, agent-api.py) — NOT modified. Their globs/specific-id lookups already exclude <key>.-prefixed files.
7. Shared helper src/result-channel-key.ts (+ Python twin src/result_channel_key.py) — sanitizeKey / resultFilename / parseResultFilename / resultBelongsTo. Cribbed from the parked branch refactor/per-channel-task-result-scoping, stripped of legacy-form compatibility (the parked design's wrong-direction transition window).

Per-consumer verification

Each existing consumer's pattern, quoted from the source, against the sample scoped filename 1485653767402553457.task-discord-voice-1700000000.txt:

src/discord-bridge.py:2796-2797 — pending_replies lookup

for task_id in list(pending_replies.keys()):
    result_file = RESULTS_DIR / f"{task_id}.txt"

task_id is one of the bridge's own tracked ids (task-...). For the scoped file to match, some ${tracked}.txt would have to equal the full scoped filename — impossible, because tracked ids are bare task-... strings and don't have a <channel-id>. prefix.

src/telegram-bridge.py:576-577 — same shape

for task_id in list(pending_replies.keys()):
    result_file = RESULTS_DIR / f"{task_id}.txt"

Same logic.

src/slack-bridge.py:565-566 — same shape

pending_ids = list(pending_replies.keys())
for task_id in pending_ids:
    result_file = RESULTS_DIR / f"{task_id}.txt"

Same logic.

src/agent-api.py:356 and :452 — task-* glob

for f in sorted(RESULT_DIR.glob("task-*.txt"), ...):

<key>.task-*.txt does not match task-*.txt — the scoped filename starts with the channel key, not task-.

src/task-bridge.ts:608, 624, 649, 668 — startsWith guards

if (file.startsWith('voice-')) { ... }
if (file.startsWith('task-') && /^\s*\[deduped:\s*task-/i.test(result)) { ... }
if (file.startsWith('task-') && _isVoiceTask(taskId)) { ... }
if (taskId.startsWith('task-chat-')) { ... }

All four guards key off the file (or task id) starting with task- / voice- / task-chat-. The scoped filename starts with the channel key — none match.

Known trade-off — task-bridge.ts fallthrough

task-bridge.ts:682 has an unconditional if (result) fallthrough that fires for any non-empty .txt file when the voice client is connected. If voice-agent is the active surface AND the scoped file lingers across one 2s poll, voice-agent's onResult(result) callback would also fire. Per the narrow design, this is accepted:

• voice-agent and discord-voice / phone are separate processes/surfaces — in practice the active scan reads-and-deletes the scoped file within its 3s cadence, narrower than voice-agent's 2s poll only in adversarial timing.
• The fix for this is out of scope (would require modifying task-bridge, which point 6 forbids).
• The convention documented in CLAUDE.md tells writers to use the scoped form only when discord-voice / phone is the intended consumer — not as a general broadcast channel.

What changed (2 service files + helper + docs + tests)

• src/result-channel-key.ts (new) — TS helper
• src/result_channel_key.py (new) — Python twin
• skills/discord-voice/scripts/discord-voice-server.ts — channel scan loop + interval cleanup
• skills/phone-conversation/scripts/conversation-server.ts — per-call channel scan loop + cleanup
• CLAUDE.md — convention documented under Task bridge section
• tests/result-channel-key.test.ts + tests/result-channel-key.test.py — unit coverage + load-bearing invariant tests that lock in non-match against each existing consumer's pattern

What intentionally didn't change

• All five existing consumers (point 6).
• results/proactive-*.txt and results/voice-*.txt routes — out of scope.
• The default task-{id}.txt filename for regular results.

Verification commands

npm run typecheck         # passes
npm test                  # 260+ TS tests + python suite pass
python3 tests/result-channel-key.test.py   # 16 tests pass
npx tsx --test tests/result-channel-key.test.ts   # 16 tests pass

🤖 Generated with Claude Code

[sonichi]

Folded both review findings into this branch.

Fix 1 — .txt guard (MacBook's would-block):

• Added explicit name.endsWith('.txt') guard at the top of both scan loops (skills/discord-voice/scripts/discord-voice-server.ts and skills/phone-conversation/scripts/conversation-server.ts), BEFORE resultBelongsTo().
• Tightened resultBelongsTo() (both TS and Python) to require an exact .txt ending — belt-and-suspenders with the loop guard.
• New test cases in tests/result-channel-key.test.{ts,py} reject .txt.tmp, .txt.partial, .txt.sending, .txt.swp, .txt.lock, .txt~, bare .tmp/.sending/.partial, and dotfile-prefixed temps. Plus a positive canonical-.txt sanity check.

Fix 2 — channelScanSeen unbounded growth (Maddy):
Picked path (b) — keep as safety net, prune at 60s. The unlinkSync(full) calls in both loops are wrapped in try {} catch {} and fail silently on the unhappy path (permissions, file vanished mid-tick, FS race). If unlink fails AND the Set is dropped, the same body re-injects every 3s. Converted Set<string> → Map<string, number> (name → first-seen ms) and added a TTL-prune pass at the top of each tick so memory stays bounded across long calls / multi-day voice sessions.

Tracking:
task-bridge.ts:682 belt-suspenders is tracked as follow-up issue #1035 (narrow-scope-followup tag) — this PR keeps existing consumers unmodified per design point 6.

Verify:

• npm run typecheck: clean
• npx tsx --test tests/result-channel-key.test.ts: 18/18 pass (+2 new)
• python3 tests/result-channel-key.test.py: 18/18 pass (+2 new)
• npm test: 262/262 TS pass, no regressions

[qingyun-wu]

Read the helper + both scans, and traced the "slides past existing consumers" claim against the actual consumer code. The helper is well-built (safe-alphabet collapse kills path/regex injection; the . separator cleanly excludes legacy task-*.txt) and the discord-voice scan is careful (TTL-pruned seen-map, .txt guard, cleanup handle). But the core safety claim doesn't hold for one consumer — and it's a data-loss / mis-delivery race.

⚠️ task-bridge.ts does NOT slide past — its catch-all grabs scoped files

The PR states all existing consumers (incl. task-bridge.ts) "key off the legacy task-{id}.txt shape." True for the dedup and voice-offline-forward branches (both gated on file.startsWith('task-')), but the final delivery branch is an unguarded catch-all.

src/task-bridge.ts:590 reads every .txt:

const files = readdirSync(RESULT_DIR).filter(f => f.endsWith('.txt')).sort();

and when the voice client is connected, the final block (~682) has no task- guard:

if (result) {                       // any non-empty .txt that fell through
  _sendTaskStatus?.(taskId, 'done', ...);
  onResult(result);                 // delivered to the web voice client
  ... setTimeout(() => archiveFile(path, ...), 10_000)   // and deleted
}

So with the voice web client connected, a <CHANNEL_ID>.task-{id}.txt file is (a) mis-delivered to the web voice agent via onResult, and (b) archived/deleted ~10s later — racing the discord-voice/phone channel scan (3s) that's supposed to own it. Net: the scoped result reaches the wrong surface and/or vanishes. When the client is offline, the continue at ~680 leaves it alone — so the bug only bites when voice-agent's client is connected (intermittent, hard to debug).

Fix: guard the catch-all to legacy files only — e.g. if (!file.startsWith('task-')) continue; before the final delivery block (or reuse parseResultFilename and skip when key !== null). Then scoped files are genuinely invisible to task-bridge.ts and owned solely by the channel scans. A test that drops <key>.task-x.txt into results/ and asserts the task-bridge poll leaves it untouched would lock it.

(Confirmed the others are fine: agent-api.py globs task-*.txt, discord-bridge.py gates on _task_id.startswith("task-") — both miss the <key>. prefix. It's specifically task-bridge.ts's catch-all.)

Minor

• Phone key = Twilio call SID (ephemeral, per-call). How does a deliverer learn the live call's SID to address results/<SID>.task-x.txt? discord-voice's CHANNEL_ID is stable/knowable; the SID isn't obviously discoverable by the core agent — worth documenting how a producer obtains the key, or the phone half is unreachable in practice.
• Producer? This PR adds the scan + resultFilename helper but I don't see a writer emitting the scoped file. If it's intentional scaffolding ahead of the producer, fine — just confirm it's not dead code until then.

Net: helper + scans are good; the one fix that matters is guarding task-bridge.ts's catch-all, since the PR's safety hinges on a claim that isn't currently true for that consumer.