@brimveyn/aimux 1.20.1 → 1.20.3

package/src/cli/commands/worker/run.ts

@@ -14,22 +14,39 @@ import {
 } from './shared'
 
 export const workerRun: CliCommand = {
-  args: [{ name: 'text' }],
+  args: [{ complete: { kind: 'none' }, name: 'text' }],
   flags: [
     ...SHARED_FLAGS,
-    { description: 'unique workspace-scoped worker name', kind: 'string', name: 'name' },
     {
+      complete: { kind: 'none' },
+      description: 'unique workspace-scoped worker name',
+      kind: 'string',
+      name: 'name',
+    },
+    {
+      complete: { kind: 'dynamic', source: 'assistant' },
       description: 'assistant id (claude, codex, opencode, ...)',
       kind: 'string',
       name: 'assistant',
     },
-    { description: 'model passed through to the assistant', kind: 'string', name: 'model' },
     {
+      complete: { kind: 'none' },
+      description: 'model passed through to the assistant',
+      kind: 'string',
+      name: 'model',
+    },
+    {
+      complete: { kind: 'none' },
       description: 'reasoning effort passed through to the assistant',
       kind: 'string',
       name: 'effort',
     },
-    { description: 'read the prompt from this file', kind: 'string', name: 'prompt-file' },
+    {
+      complete: { kind: 'file' },
+      description: 'read the prompt from this file',
+      kind: 'string',
+      name: 'prompt-file',
+    },
     { description: 'read the prompt from stdin', kind: 'boolean', name: 'stdin' },
     {
       description: 'return after prompt uptake instead of turn completion',
@@ -37,14 +54,31 @@ export const workerRun: CliCommand = {
       name: 'detach',
     },
     { description: 'overall turn cap in milliseconds', kind: 'number', name: 'timeout' },
-    { description: 'co-locate in an existing worktree id', kind: 'string', name: 'worktree' },
+    {
+      description:
+        'milliseconds to wait for the detached submit→working confirmation (default 15000)',
+      kind: 'number',
+      name: 'uptake-timeout',
+    },
+    {
+      complete: { kind: 'dynamic', source: 'worktree' },
+      description: 'co-locate in an existing worktree id',
+      kind: 'string',
+      name: 'worktree',
+    },
     {
       description: 'run in the workspace active worktree instead of creating one',
       kind: 'boolean',
       name: 'no-worktree',
     },
-    { description: 'base ref for the fresh worktree (default HEAD)', kind: 'string', name: 'base' },
     {
+      complete: { kind: 'dynamic', source: 'git-ref' },
+      description: 'base ref for the fresh worktree (default HEAD)',
+      kind: 'string',
+      name: 'base',
+    },
+    {
+      complete: { kind: 'none' },
       description: 'branch for the fresh worktree (default aimux/<name>)',
       kind: 'string',
       name: 'branch',
@@ -69,6 +103,11 @@ export const workerRun: CliCommand = {
       ctx.args.flags.stdin === true,
       ctx.args.positionals[0]
     )
+    // Resolve the target workspace ONCE, up front, and use that record for
+    // every later step. The repo a worktree is cut from comes from this record,
+    // so an orchestrator that omits --workspace at least gets the resolved
+    // identity echoed back in the response instead of having to infer it.
+    const workspace = ctx.getWorkspace()
     const result = await createCliTab(ctx, {
       assistantId: assistant,
       base: typeof ctx.args.flags.base === 'string' ? ctx.args.flags.base : undefined,
@@ -80,16 +119,23 @@ export const workerRun: CliCommand = {
       workerName: name,
       worktreeId: worktree,
     })
-    const tabs = await (await ctx.getDaemon()).listTabs(ctx.getWorkspace().id)
+    const tabs = await (await ctx.getDaemon()).listTabs(workspace.id)
     const tab = tabs.tabs.find((entry) => entry.id === result.tabId)
     if (!tab) throw new Error(`created worker disappeared: ${result.tabId}`)
-    const worker = workerView(ctx, tab)
-    const outcome = await dispatchWorkerPrompt(ctx, result.tabId, text, {
+    const worker = workerView(workspace, tab)
+    const outcome = await dispatchWorkerPrompt(ctx, workspace, result.tabId, text, {
+      // The tab was spawned microseconds ago: its assistant is still booting, so
+      // the prompt must not be written until the TUI is reading keystrokes.
+      awaitFirstPaint: true,
       detach: ctx.args.flags.detach === true,
       timeoutMs:
         typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_TIMEOUT_MS,
+      uptakeTimeoutMs:
+        typeof ctx.args.flags['uptake-timeout'] === 'number'
+          ? ctx.args.flags['uptake-timeout']
+          : undefined,
     })
-    writeJson(workerEnvelope(worker, outcome))
+    writeJson(workerEnvelope(workspace, worker, outcome))
     return workerOutcomeExitCode(outcome)
   },
   summary: 'Create a named worker, dispatch a prompt, and await its outcome',

package/src/cli/commands/worker/shared.ts

@@ -1,4 +1,4 @@
-import type { WorktreeRecord } from '../../../state/types'
+import type { SessionRecord, TerminalSnapshot, WorktreeRecord } from '../../../state/types'
 import type { CliContext } from '../../context'
 
 import {
@@ -9,16 +9,50 @@ import {
   IPC_CAPABILITY_WORKER_METADATA,
   type TabSessionSummary,
 } from '../../../ipc/protocol'
+import {
+  listWorkspaces,
+  workspaceIdentity,
+  workspaceRepoRoot,
+} from '../../client/workspace-resolver'
 import { CliUsageError } from '../../flags'
-import { EXIT_OK, EXIT_QUESTION, EXIT_RUNTIME, EXIT_TIMEOUT } from '../../output'
-import { snapshotTailLines } from '../../snapshot-render'
+import {
+  EXIT_OK,
+  EXIT_PENDING_SUBMIT,
+  EXIT_QUESTION,
+  EXIT_RUNTIME,
+  EXIT_TIMEOUT,
+} from '../../output'
+import { snapshotTailLines, snapshotToLines } from '../../snapshot-render'
 import { awaitTurn, type TurnOutcome } from '../tab/await-turn'
 import { buildPromptPayload, writePromptPayload } from '../tab/prompt-io'
 
 export const WORKER_SCHEMA_VERSION = 1
 export const WORKER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
 const QUESTION_TAIL_LINES = 25
-const DETACH_UPTAKE_TIMEOUT_MS = 15_000
+
+/**
+ * Default window for the `--detach` submit→`working` confirmation. Overridable
+ * per call with `--uptake-timeout`: a cold assistant on a loaded machine can
+ * take longer than this to accept its first keystroke, and the old hard ceiling
+ * (min(--timeout, 15s)) made that unfixable from the outside.
+ */
+export const DETACH_UPTAKE_TIMEOUT_MS = 15_000
+/** Second, shorter window used after the idempotent submit retry. */
+const UPTAKE_RESUBMIT_WINDOW_MS = 5_000
+/** One retry is enough: the payload is already in the composer either way. */
+const MAX_UPTAKE_RESUBMITS = 1
+/**
+ * How long to wait for a freshly spawned assistant to paint anything before
+ * writing its prompt. A booting TUI has a pty that buffers the payload (which
+ * is why the text shows up intact) but is not yet reading keystrokes, so the
+ * submitting `\r` is consumed before the composer exists. First paint is a
+ * generic, assistant-agnostic "it is reading input now" signal.
+ */
+const TAB_FIRST_PAINT_TIMEOUT_MS = 10_000
+/** Settle after a *just observed* first paint, before writing. */
+const TAB_FIRST_PAINT_SETTLE_MS = 250
+/** Chord that clears the composer line (readline kill-line). */
+const CLEAR_COMPOSER_CHORD = '<C-u>'
 
 export interface WorkerView {
   activity?: TabSessionSummary['activity']
@@ -28,6 +62,8 @@ export interface WorkerView {
   lastLine?: string
   name: string
   path: string | null
+  /** Repository the worker's worktree was cut from — see `workspaceRepoRoot`. */
+  repoRoot: string | null
   status: TabSessionSummary['status']
   tabId: string
   title: string
@@ -40,8 +76,19 @@ export interface WorkerOutcome {
   kind?: string
   options?: string[]
   question?: string
-  status: 'completed' | 'dispatched' | 'question' | 'timeout' | 'error'
-  uptake?: { confirmed: boolean; ms?: number }
+  status: 'completed' | 'dispatched' | 'pending-submit' | 'question' | 'timeout' | 'error'
+  uptake?: {
+    confirmed: boolean
+    activity?: TabSessionSummary['activity']
+    ms?: number
+    resubmits?: number
+  }
+}
+
+/** A worker plus the workspace it is actually bound to. */
+export interface WorkerTarget {
+  tab: TabSessionSummary
+  workspace: SessionRecord
 }
 
 export function validateWorkerName(name: string): void {
@@ -52,16 +99,19 @@ export function validateWorkerName(name: string): void {
   }
 }
 
-function worktreeFor(ctx: CliContext, worktreeId: string | undefined): WorktreeRecord | undefined {
+function worktreeFor(
+  workspace: SessionRecord,
+  worktreeId: string | undefined
+): WorktreeRecord | undefined {
   if (worktreeId === undefined) return undefined
-  return ctx.getWorkspace().worktrees?.find((worktree) => worktree.id === worktreeId)
+  return workspace.worktrees?.find((worktree) => worktree.id === worktreeId)
 }
 
-export function workerView(ctx: CliContext, tab: TabSessionSummary): WorkerView {
+export function workerView(workspace: SessionRecord, tab: TabSessionSummary): WorkerView {
   if (tab.workerName === undefined) {
     throw new Error(`tab is not a named worker: ${tab.id}`)
   }
-  const worktree = worktreeFor(ctx, tab.worktreeId)
+  const worktree = worktreeFor(workspace, tab.worktreeId)
   return {
     activity: tab.activity,
     assistant: tab.assistant,
@@ -70,6 +120,7 @@ export function workerView(ctx: CliContext, tab: TabSessionSummary): WorkerView
     lastLine: tab.lastLine,
     name: tab.workerName,
     path: worktree?.path ?? null,
+    repoRoot: worktree?.repoRoot ?? workspaceRepoRoot(workspace),
     status: tab.status,
     tabId: tab.id,
     title: tab.title,
@@ -77,7 +128,9 @@ export function workerView(ctx: CliContext, tab: TabSessionSummary): WorkerView
   }
 }
 
-export async function listNamedWorkerTabs(ctx: CliContext): Promise<TabSessionSummary[]> {
+async function requireWorkerCapabilities(
+  ctx: CliContext
+): Promise<Awaited<ReturnType<CliContext['getDaemon']>>> {
   const daemon = await ctx.getDaemon()
   if (
     !daemon.hasCapability(IPC_CAPABILITY_LIST_TABS) ||
@@ -85,26 +138,76 @@ export async function listNamedWorkerTabs(ctx: CliContext): Promise<TabSessionSu
   ) {
     throw new Error('daemon predates worker commands — restart aimux')
   }
-  return (await daemon.listTabs(ctx.getWorkspace().id)).tabs.filter(
-    (tab) => tab.workerName !== undefined
-  )
+  return daemon
 }
 
-export async function resolveWorkerTab(
+export async function listNamedWorkerTabs(
+  ctx: CliContext,
+  workspace: SessionRecord = ctx.getWorkspace()
+): Promise<TabSessionSummary[]> {
+  const daemon = await requireWorkerCapabilities(ctx)
+  return (await daemon.listTabs(workspace.id)).tabs.filter((tab) => tab.workerName !== undefined)
+}
+
+/** Every named worker the daemon knows about, across every catalogued workspace. */
+export async function listWorkerTargets(ctx: CliContext): Promise<WorkerTarget[]> {
+  const daemon = await requireWorkerCapabilities(ctx)
+  const targets: WorkerTarget[] = []
+  for (const workspace of ctx.getWorkspaces?.() ?? listWorkspaces()) {
+    const { tabs } = await daemon.listTabs(workspace.id)
+    for (const tab of tabs) {
+      if (tab.workerName !== undefined) targets.push({ tab, workspace })
+    }
+  }
+  return targets
+}
+
+function matches(tab: TabSessionSummary, selector: string): boolean {
+  return tab.id === selector || tab.workerName === selector
+}
+
+/**
+ * Resolve a worker selector to the tab AND the workspace that owns it.
+ *
+ * A worker is addressed for its whole lifetime, but the *active* workspace can
+ * change under it (the UI switching projects is enough). Resolving only against
+ * the active workspace is what made a live fleet look dead — `worker list`
+ * returning `[]` and `worker await` saying "worker not found" while all twelve
+ * workers were healthy. So when the workspace was merely inferred, fall back to
+ * a catalog-wide search and bind to wherever the worker actually lives; when it
+ * was pinned (`--workspace` / `AIMUX_WORKSPACE`), keep the boundary but name the
+ * workspace that does hold it instead of a bare "not found".
+ */
+export async function resolveWorkerTarget(
   ctx: CliContext,
   selector: string
-): Promise<TabSessionSummary> {
-  const workers = await listNamedWorkerTabs(ctx)
-  const byId = workers.find((tab) => tab.id === selector)
-  if (byId) return byId
-  const matches = workers.filter((tab) => tab.workerName === selector)
-  if (matches.length === 1 && matches[0]) return matches[0]
-  if (matches.length > 1) {
+): Promise<WorkerTarget> {
+  const workspace = ctx.getWorkspace()
+  const local = (await listNamedWorkerTabs(ctx, workspace)).filter((tab) => matches(tab, selector))
+  if (local.length > 1) {
     throw new Error(
-      `worker selector is ambiguous: ${selector} (${matches.map((tab) => tab.id).join(', ')})`
+      `worker selector is ambiguous in workspace "${workspace.name}": ${selector} (${local
+        .map((tab) => tab.id)
+        .join(', ')})`
     )
   }
-  throw new Error(`worker not found: ${selector}`)
+  const only = local[0]
+  if (only) return { tab: only, workspace }
+
+  const elsewhere = (await listWorkerTargets(ctx)).filter(
+    (target) => target.workspace.id !== workspace.id && matches(target.tab, selector)
+  )
+  const pinned = (ctx.getWorkspaceOrigin?.() ?? 'active') !== 'active'
+  if (elsewhere.length === 1 && elsewhere[0] && !pinned) return elsewhere[0]
+  if (elsewhere.length > 0) {
+    const where = elsewhere
+      .map((target) => `${target.workspace.name} (${target.tab.id})`)
+      .join(', ')
+    throw new Error(
+      `worker not found in workspace "${workspace.name}": ${selector} — it lives in ${where}; re-run with --workspace`
+    )
+  }
+  throw new Error(`worker not found in workspace "${workspace.name}": ${selector}`)
 }
 
 export function normalizeTurnOutcome(outcome: TurnOutcome): WorkerOutcome {
@@ -133,6 +236,8 @@ export function workerOutcomeExitCode(outcome: WorkerOutcome): number {
       return EXIT_OK
     case 'question':
       return EXIT_QUESTION
+    case 'pending-submit':
+      return EXIT_PENDING_SUBMIT
     case 'timeout':
       return EXIT_TIMEOUT
     case 'error':
@@ -154,25 +259,130 @@ async function requireTurnCapabilities(ctx: CliContext): Promise<{
   return { daemon }
 }
 
+function hasPaintedContent(viewport: TerminalSnapshot | undefined): boolean {
+  if (!viewport) return false
+  return snapshotToLines(viewport).some((line) => line.trim() !== '')
+}
+
+/**
+ * Resolve once the tab has painted something, i.e. the assistant is up far
+ * enough to be reading keystrokes. Returns immediately for a tab that already
+ * painted, and gives up (rather than blocking the dispatch) if nothing paints
+ * within the window.
+ */
+async function waitForFirstPaint(
+  daemon: Awaited<ReturnType<CliContext['getDaemon']>>,
+  tabId: string,
+  seed: TerminalSnapshot | undefined
+): Promise<void> {
+  if (hasPaintedContent(seed)) return
+  const painted = await new Promise<boolean>((resolve) => {
+    const off = daemon.on('tabRender', (event) => {
+      if (event.tabId !== tabId || !hasPaintedContent(event.viewport)) return
+      off()
+      clearTimeout(timer)
+      resolve(true)
+    })
+    const timer = setTimeout(() => {
+      off()
+      resolve(false)
+    }, TAB_FIRST_PAINT_TIMEOUT_MS)
+  })
+  // Even a painted TUI needs a beat between "first frame" and "composer is
+  // interactive". Skip the settle when first paint never arrived — waiting
+  // longer on a tab that produced nothing buys nothing.
+  if (painted) await Bun.sleep(TAB_FIRST_PAINT_SETTLE_MS)
+}
+
+interface UptakeResult {
+  activity?: TabSessionSummary['activity']
+  confirmed: boolean
+  ms?: number
+}
+
+// `async` only to satisfy promise-function-async; the body has no `await`, so
+// the executor below still runs synchronously and the `tabStatus` subscription
+// is armed before this returns — callers write to the tab right after calling.
+async function armUptake(
+  daemon: Awaited<ReturnType<CliContext['getDaemon']>>,
+  tabId: string,
+  windowMs: number,
+  startedAt: number
+): Promise<UptakeResult> {
+  return new Promise<UptakeResult>((resolve) => {
+    const off = daemon.on('tabStatus', (event) => {
+      if (event.tabId !== tabId || event.status !== 'working') return
+      off()
+      clearTimeout(timer)
+      resolve({ activity: 'working', confirmed: true, ms: Date.now() - startedAt })
+    })
+    const timer = setTimeout(() => {
+      off()
+      resolve({ confirmed: false })
+    }, windowMs)
+  })
+}
+
+/**
+ * Uptake read from the tab's *current* activity rather than from a transition.
+ * `tabStatus` is edge-triggered, so a transition can be missed; and a worker that
+ * answered with a question never emitted `working` at all. Both mean the prompt
+ * was taken up. Returns undefined when the tab is genuinely idle.
+ */
+async function liveUptake(
+  daemon: Awaited<ReturnType<CliContext['getDaemon']>>,
+  sessionId: string,
+  tabId: string,
+  startedAt: number
+): Promise<UptakeResult | undefined> {
+  const live = (await daemon.listTabs(sessionId)).tabs.find((tab) => tab.id === tabId)
+  if (live?.activity !== 'working' && live?.activity !== 'waiting-input') return undefined
+  return { activity: live.activity, confirmed: true, ms: Date.now() - startedAt }
+}
+
+export interface DispatchOptions {
+  /**
+   * Gate the first write on the tab painting. Set only for a tab this call just
+   * spawned: an already-running worker has painted long ago, so waiting on a
+   * fresh render event would just stall on a quiet screen.
+   */
+  awaitFirstPaint?: boolean
+  detach: boolean
+  /** Clear the composer (`<C-u>`) before writing, so stray text can't merge in. */
+  replace?: boolean
+  timeoutMs: number
+  /** Window for the detached submit→`working` confirmation. */
+  uptakeTimeoutMs?: number
+}
+
 export async function dispatchWorkerPrompt(
   ctx: CliContext,
+  workspace: SessionRecord,
   tabId: string,
   text: string,
-  options: { detach: boolean; timeoutMs: number }
+  options: DispatchOptions
 ): Promise<WorkerOutcome> {
   const { daemon } = await requireTurnCapabilities(ctx)
-  const workspace = ctx.getWorkspace()
   const attach = await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
-  if (!attach.tabs.some((tab) => tab.id === tabId)) throw new Error(`tab not found: ${tabId}`)
+  const attached = attach.tabs.find((tab) => tab.id === tabId)
+  if (!attached) throw new Error(`tab not found: ${tabId}`)
   const payload = buildPromptPayload(text, false)
+  const write = async (): Promise<void> => {
+    if (options.replace === true) {
+      await writePromptPayload(daemon, tabId, buildPromptPayload(CLEAR_COMPOSER_CHORD, true), false)
+    }
+    await writePromptPayload(daemon, tabId, payload, true)
+  }
+
+  if (options.awaitFirstPaint === true) {
+    await waitForFirstPaint(daemon, tabId, attached.viewport)
+  }
 
   if (!options.detach) {
     const outcome = await awaitTurn({
       assumeWorking: false,
       daemon,
-      onArmed: async () => {
-        await writePromptPayload(daemon, tabId, payload, true)
-      },
+      onArmed: write,
       tabId,
       timeoutMs: options.timeoutMs,
     })
@@ -180,40 +390,83 @@ export async function dispatchWorkerPrompt(
   }
 
   const startedAt = Date.now()
-  const uptake = new Promise<{ confirmed: true; ms: number } | { confirmed: false }>((resolve) => {
-    const off = daemon.on('tabStatus', (event) => {
-      if (event.tabId !== tabId || event.status !== 'working') return
-      off()
-      clearTimeout(timer)
-      resolve({ confirmed: true, ms: Date.now() - startedAt })
-    })
-    const timer = setTimeout(
-      () => {
-        off()
-        resolve({ confirmed: false })
-      },
-      Math.min(options.timeoutMs, DETACH_UPTAKE_TIMEOUT_MS)
-    )
-  })
-  await writePromptPayload(daemon, tabId, payload, true)
-  const result = await uptake
+  const window = options.uptakeTimeoutMs ?? DETACH_UPTAKE_TIMEOUT_MS
+  const first = armUptake(daemon, tabId, window, startedAt)
+  await write()
+  let result = await first
+  let resubmits = 0
+
+  while (!result.confirmed && resubmits < MAX_UPTAKE_RESUBMITS) {
+    const live = await liveUptake(daemon, workspace.id, tabId, startedAt)
+    if (live) {
+      result = live
+      break
+    }
+    // The payload is already in the composer; a bare `\r` just submits what is
+    // sitting there. Idempotent, and it is exactly the manual recovery this
+    // used to force on the caller.
+    resubmits++
+    const retry = armUptake(daemon, tabId, UPTAKE_RESUBMIT_WINDOW_MS, startedAt)
+    await daemon.expectOk('write', { data: '\r', tabId })
+    result = await retry
+  }
+  // Last look before declaring failure: never report a healthy, working worker
+  // as pending just because an edge-triggered event was missed.
+  if (!result.confirmed) {
+    result = (await liveUptake(daemon, workspace.id, tabId, startedAt)) ?? result
+  }
+
   if (!result.confirmed) {
     return {
       durationMs: Date.now() - startedAt,
-      error: 'prompt was written but worker uptake was not confirmed',
-      status: 'error',
-      uptake: result,
+      error: `prompt is in the composer but no turn started after ${resubmits + 1} submit attempt(s); recover with \`aimux worker submit\``,
+      status: 'pending-submit',
+      uptake: { ...result, resubmits },
     }
   }
   return {
     durationMs: Date.now() - startedAt,
     status: 'dispatched',
-    uptake: result,
+    uptake: { ...result, resubmits },
+  }
+}
+
+/**
+ * Submit whatever is already sitting in a worker's composer and confirm uptake.
+ * The recovery verb for a `pending-submit` outcome — awaitable, unlike the
+ * `tab send <tab> "<CR>" --keys` dance it replaces.
+ */
+export async function submitWorkerPrompt(
+  ctx: CliContext,
+  workspace: SessionRecord,
+  tabId: string,
+  uptakeTimeoutMs: number
+): Promise<WorkerOutcome> {
+  const { daemon } = await requireTurnCapabilities(ctx)
+  const attach = await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+  if (!attach.tabs.some((tab) => tab.id === tabId)) throw new Error(`tab not found: ${tabId}`)
+  const startedAt = Date.now()
+  const uptake = armUptake(daemon, tabId, uptakeTimeoutMs, startedAt)
+  await daemon.expectOk('write', { data: '\r', tabId })
+  const result = await uptake
+  if (!result.confirmed) {
+    const live = await liveUptake(daemon, workspace.id, tabId, startedAt)
+    if (live) {
+      return { durationMs: Date.now() - startedAt, status: 'dispatched', uptake: live }
+    }
+    return {
+      durationMs: Date.now() - startedAt,
+      error: 'submitted but no turn started — the composer may be empty',
+      status: 'pending-submit',
+      uptake: result,
+    }
   }
+  return { durationMs: Date.now() - startedAt, status: 'dispatched', uptake: result }
 }
 
 export async function awaitExistingWorker(
   ctx: CliContext,
+  workspace: SessionRecord,
   tabId: string,
   timeoutMs: number
 ): Promise<WorkerOutcome> {
@@ -221,7 +474,7 @@ export async function awaitExistingWorker(
   const attach = await daemon.attach({
     cols: 0,
     rows: 0,
-    sessionId: ctx.getWorkspace().id,
+    sessionId: workspace.id,
     thin: true,
   })
   const tab = attach.tabs.find((entry) => entry.id === tabId)
@@ -243,13 +496,20 @@ export async function awaitExistingWorker(
   )
 }
 
+/**
+ * Versioned envelope. `workspace` is not decoration: without it a caller cannot
+ * tell which project a worker belongs to, which is how a whole orchestration
+ * can run against the wrong repository unnoticed.
+ */
 export function workerEnvelope(
+  workspace: SessionRecord,
   worker: WorkerView,
   outcome?: WorkerOutcome
 ): Record<string, unknown> {
   return {
     schemaVersion: WORKER_SCHEMA_VERSION,
     worker,
+    workspace: workspaceIdentity(workspace),
     ...(outcome === undefined ? {} : { outcome }),
   }
 }