@openparachute/agent 0.2.3-rc.10 → 0.2.3-rc.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.2.3-rc.10",
+  "version": "0.2.3-rc.12",
   "description": "Vault-native agents for Claude Code — a #agent/definition note + an inbound message becomes a sandboxed claude turn; the reply is written back as a note. Messaging gateway on :1941.",
   "license": "AGPL-3.0",
   "type": "module",

package/src/backends/programmatic.ts

@@ -85,6 +85,7 @@ import type {
   DeliverResult,
   DeliverUsage,
   InterimSink,
+  RunContext,
   TurnSession,
 } from "./types.ts";
 
@@ -327,6 +328,32 @@ export function buildProgrammaticClaudeArgs(opts: {
   return argv;
 }
 
+/**
+ * Render the {@link RunContext} as a concise, clearly-LABELED preamble to PREPEND to a turn's
+ * message (agent#162). A headless `claude -p` turn has no clock + no notion of which run it is,
+ * so the daemon hands it these facts (the real wall-clock, new-vs-resumed, why it fired, the
+ * prior turn count) — the agent then stamps ACCURATE times instead of fabricating them.
+ *
+ * It is a single fenced block clearly marked as daemon-injected runtime context (NOT the
+ * agent's own system prompt — that's untouched), then a blank line, then the real message. The
+ * `now` is always present; the rest are appended only when known. Returns the message UNCHANGED
+ * when `rc` is absent (additive — no behavior change for a caller that doesn't pass one).
+ */
+export function renderRunContext(message: string, rc: RunContext | undefined): string {
+  if (!rc) return message;
+  const parts: string[] = [`now=${rc.now}`, `session=${rc.session}`];
+  if (typeof rc.priorTurnCount === "number" && rc.priorTurnCount >= 0) {
+    // The NUMBER of this turn (1-based) = completed turns + 1 — what an agent stamps as "turn N".
+    parts.push(`turn=${rc.priorTurnCount + 1}`);
+  }
+  if (rc.firedBy) parts.push(`fired-by=${rc.firedBy}`);
+  const preamble =
+    `[Run context — injected by the agent daemon (this is the real runtime state, NOT your ` +
+    `system prompt). Use these for any timestamp/clock or "which run is this" reasoning instead ` +
+    `of guessing: ${parts.join(", ")}]`;
+  return `${preamble}\n\n${message}`;
+}
+
 /** Read the full text of a (possibly null) byte stream; null/error → "". */
 async function drainStream(stream: ReadableStream<Uint8Array> | null): Promise<string> {
   if (!stream) return "";
@@ -414,6 +441,8 @@ export class ProgrammaticBackend implements AgentBackend {
     session: TurnSession,
     onInterim?: InterimSink,
     attachments?: InboundAttachment[],
+    runContext?: RunContext,
+    subjectDossier?: string,
   ): Promise<DeliverResult> {
     const spec = handle.spec;
     if (!spec) {
@@ -537,13 +566,18 @@ export class ProgrammaticBackend implements AgentBackend {
     // per-agent even when the working dir is shared. Best-effort + isolated: a single
     // attachment's fetch/stage failure logs + is SKIPPED (the turn still runs with the rest
     // + the text). Absent/empty → no staging, no prompt change (today's behavior exactly).
-    let turnMessage = message;
+    // RUN CONTEXT (agent#162): prepend the daemon-injected runtime preamble (the real
+    // wall-clock + new/resumed + why-it-fired) so the headless turn reads ACCURATE facts
+    // instead of fabricating a clock. Done FIRST so the preamble sits at the very top of the
+    // prompt; attachments append after the (already-prefixed) message. Absent runContext →
+    // the message is unchanged (additive).
+    let turnMessage = renderRunContext(message, runContext);
     if (attachments && attachments.length > 0) {
       const staged = await this.stageAttachments(workspace, attachments, vaultArg);
       if (staged.length > 0) {
         const lines = staged.map((s) => `- ${s.absPath} (${s.mimeType})`);
         turnMessage =
-          `${message}\n\n[Attached files — read them as needed:\n${lines.join("\n")}\n]`;
+          `${turnMessage}\n\n[Attached files — read them as needed:\n${lines.join("\n")}\n]`;
       }
     }
 
@@ -554,10 +588,22 @@ export class ProgrammaticBackend implements AgentBackend {
     // Unset → no flag, no file (today's behavior unchanged). The `-file` form is
     // robust to long/multiline prompts and keeps the prompt visible-on-disk. Its
     // lifecycle is tied to the workspace (like .mcp.json) — it disappears with it.
+    //
+    // COMPOSED PROMPT (roles×threads NOW slice): when a `subjectDossier` is handed in,
+    // the agent's stable ROLE (the spec's systemPrompt) is composed with the per-thread
+    // subject context as `roleBody + "\n\n---\n\n" + dossier`. The role stays constant
+    // across a role's threads; the subject-specific dossier layers on top. Absent/empty
+    // dossier → the role body is written VERBATIM (byte-identical to HEAD — the
+    // null-subject invariant; the run-context preamble stays on the MESSAGE, not here).
     let systemPromptFile: string | undefined;
     if (typeof spec.systemPrompt === "string" && spec.systemPrompt.length > 0) {
+      const roleBody = spec.systemPrompt;
+      const composed =
+        typeof subjectDossier === "string" && subjectDossier.length > 0
+          ? `${roleBody}\n\n---\n\n${subjectDossier}`
+          : roleBody;
       systemPromptFile = join(workspace, "system-prompt.txt");
-      writeFileSync(systemPromptFile, spec.systemPrompt, { mode: 0o600 });
+      writeFileSync(systemPromptFile, composed, { mode: 0o600 });
     }
 
     // The agent's WORKING dir (design 2026-06-16-agent-filesystem-and-sharing.md):

package/src/backends/registry.ts

@@ -44,7 +44,7 @@
 
 import type { AgentSpec, AgentMode } from "../sandbox/types.ts";
 import { normalizeChannel } from "../sandbox/types.ts";
-import type { AgentBackend, AgentHandle, InterimTurnEvent, TurnSession } from "./types.ts";
+import type { AgentBackend, AgentHandle, InterimTurnEvent, RunContext, TurnSession } from "./types.ts";
 import type { InboundAttachment } from "../transport.ts";
 
 /**
@@ -90,12 +90,15 @@ export type WriteOutbound = (
   reply: string,
   inReplyTo?: string,
   /**
-   * The per-turn thread id this reply belongs to — the explicit definition→thread→message
-   * link the outbound note carries (stamped into `metadata.thread`). For multi-threaded it
-   * IS the per-fire thread note's leaf (an exact link); for single-threaded it's a per-turn
-   * correlation id (the note's stable deterministic leaf is the def name — single-threaded
-   * outbound→note linkage by the stable path is a follow-up). INBOUND-note stamping is
-   * deferred (those notes are externally written; see the PR notes).
+   * The RESOLVABLE, MODE-CORRECT thread id this reply belongs to — the explicit
+   * definition→thread→message link the outbound note carries (stamped into `metadata.thread`),
+   * mirroring the callback `source_thread` fix (agent#124/#163). For multi-threaded it IS the
+   * per-fire thread note's leaf (`Threads/<channel>/<id>`); for single-threaded it is the
+   * DETERMINISTIC thread-NOTE id (`Threads/<channel>/<name>`), STABLE across turns — so an
+   * observer reading the outbound note's `metadata.thread` resolves the agent's ONE thread
+   * with `query-notes { id }`, instead of the per-turn correlation UUID that changed every
+   * run (the pre-#163 bug that looked like a fresh session each time). INBOUND-note stamping
+   * is deferred (those notes are externally written; see the PR notes).
    */
   threadId?: string,
 ) => Promise<{ id?: string } | void>;
@@ -302,6 +305,46 @@ function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * The thread id to stamp into an OUTBOUND note's `metadata.thread` (agent#163) — the
+ * MODE-CORRECT, RESOLVABLE definition→thread→message link, mirroring the callback
+ * `source_thread` fix (agent#124):
+ *
+ *  - SINGLE-THREADED — the resolvable thread-NOTE id (the deterministic
+ *    `Threads/<safeChannel>/<safeName>` note), so an observer reading the outbound note's
+ *    `metadata.thread` resolves the agent's ONE stable thread with `query-notes { id }`.
+ *    The pre-#163 bug stamped the per-turn correlation UUID here, which changed every turn
+ *    and resolved to nothing — misleading an observer into "a fresh session each run" when
+ *    the single-threaded session is actually stable + resumed across turns.
+ *  - MULTI-THREADED — the per-fire id (`turnThreadId`), which IS that fire's thread-note leaf
+ *    (`Threads/<safeChannel>/<turnThreadId>`) — correct as-is: each fire is its own thread.
+ *
+ * Falls back to `turnThreadId` when no resolvable note id surfaced (no durable thread store
+ * wired, or the thread-note write failed) — never undefined, so the link is always stamped.
+ */
+export function outboundThreadId(
+  multiThreaded: boolean,
+  turnThreadId: string,
+  threadNoteId: string | undefined,
+): string {
+  if (multiThreaded) return turnThreadId;
+  return threadNoteId ?? turnThreadId;
+}
+
+/**
+ * Derive the run-context `fired-by` provenance (agent#162) from an inbound message's
+ * `sender` (the note's `metadata.sender`). A SCHEDULED job fire stamps `runner:<jobId>`
+ * (the runner's sender provenance) → reported as the job id so the agent knows it's a cron
+ * fire; anything else (a human / a delegated agent message) → `interactive`. Absent sender →
+ * undefined (the run context omits `fired-by`).
+ */
+export function runFiredBy(sender: string | undefined): string | undefined {
+  if (!sender) return undefined;
+  const m = /^runner:(.+)$/.exec(sender);
+  if (m) return `scheduled-job:${m[1]}`;
+  return "interactive";
+}
+
 /** A queued inbound message awaiting its serial turn. */
 export interface QueuedMessage {
   /** The inbound text handed to the `claude -p` turn as the prompt. */
@@ -343,6 +386,23 @@ export interface QueuedMessage {
    * `Read` it. Absent/empty → no attachments (today's behavior unchanged).
    */
   attachments?: InboundAttachment[];
+  /**
+   * WHO/WHAT sent this inbound (the note's `metadata.sender`) — used ONLY to derive the
+   * run-context `fired-by` provenance the daemon injects into the turn (agent#162): a
+   * SCHEDULED job fire stamps `runner:<jobId>`, an interactive/delegated message stamps
+   * something else. Absent → the run context omits `fired-by`. Carries no routing meaning.
+   */
+  sender?: string;
+  /**
+   * The THREAD SUBJECT (roles×threads NOW slice) — rides from the inbound note's
+   * `metadata.subject`, through `contextFor.emit` (daemon.ts), onto this queue item.
+   * In the NOW slice it carries NO routing meaning — the drain stays per-CHANNEL serial,
+   * NOT per-subject — but it is threaded through so the composed prompt can fold in a
+   * subject dossier and the NEXT slice (#120 thread routing + per-thread session
+   * continuity) can key off it without re-plumbing. Absent → no subject (today's behavior;
+   * the weave path is untouched). Carries no routing meaning in NOW.
+   */
+  subject?: string;
 }
 
 /** A registered programmatic agent's live status (surfaced in /health + the list). */
@@ -428,6 +488,16 @@ export class ProgrammaticAgentRegistry {
    * Unwired → reset is a clean no-op beyond returning that the agent exists.
    */
   private readonly clearSession?: (channel: string, name: string) => Promise<void>;
+  /**
+   * Optional pre-turn SUBJECT-DOSSIER read (roles×threads NOW slice) — per-thread
+   * context for the current subject, folded into the composed system prompt (the
+   * programmatic backend's `roleBody + "\n\n---\n\n" + dossier`). Read in {@link drain}
+   * keyed on the inbound message's subject. UNWIRED in the NOW slice (the default registry
+   * does NOT set it — there's no dossier-note convention yet), so every turn composes the
+   * role body verbatim and the null-subject path is byte-identical to HEAD. The seam is
+   * here so a future dossier source threads in without re-plumbing `deliver`.
+   */
+  private readonly readSubjectDossier?: (channel: string, subject: string) => Promise<string | undefined>;
   /** Base backoff (ms) between outbound retries (FIX 1). Injectable so tests run fast. */
   private readonly outboundRetryBaseMs: number;
 
@@ -441,6 +511,11 @@ export class ProgrammaticAgentRegistry {
     readSession?: (channel: string, name: string) => Promise<string | undefined>;
     /** Clear the persisted thread-note session (the per-agent restart / reset). */
     clearSession?: (channel: string, name: string) => Promise<void>;
+    /**
+     * Read the per-thread subject dossier (roles×threads NOW slice). Optional + UNWIRED
+     * by default — the composed prompt is the role body verbatim until a dossier source exists.
+     */
+    readSubjectDossier?: (channel: string, subject: string) => Promise<string | undefined>;
     /** Override the outbound-retry backoff base (ms). Default {@link OUTBOUND_RETRY_BASE_MS}. */
     outboundRetryBaseMs?: number;
   }) {
@@ -451,6 +526,7 @@ export class ProgrammaticAgentRegistry {
     if (deps.onTurnEvent) this.onTurnEvent = deps.onTurnEvent;
     if (deps.readSession) this.readSession = deps.readSession;
     if (deps.clearSession) this.clearSession = deps.clearSession;
+    if (deps.readSubjectDossier) this.readSubjectDossier = deps.readSubjectDossier;
     this.outboundRetryBaseMs = deps.outboundRetryBaseMs ?? OUTBOUND_RETRY_BASE_MS;
   }
 
@@ -806,7 +882,11 @@ export class ProgrammaticAgentRegistry {
       // start+end never double-count. Best-effort: a start-ensure write failure is logged
       // (inside recordThread) and the turn STILL runs — a missing/stale working note must
       // never strand the queue or skip the turn.
-      await this.recordThread(handle, msg, "working", "", startedAt, undefined, {
+      // Capture the start-ensure's WRITTEN thread-note id. For single-threaded this is the
+      // DETERMINISTIC `Threads/<safeChannel>/<safeName>` note (the same every turn) — so a
+      // resolvable thread id is available BEFORE the turn runs, for the failure-note +
+      // outbound `metadata.thread` stamping (agent#163), even on a turn that fails early.
+      const startThreadNoteId = await this.recordThread(handle, msg, "working", "", startedAt, undefined, {
         threadId: turnThreadId,
         phase: "start",
         // NO session on the start-ensure: it runs BEFORE claude, so claude may never
@@ -816,6 +896,44 @@ export class ProgrammaticAgentRegistry {
         // the `end` record, and ONLY the id claude actually echoed (FIX 2). For a
         // single-threaded resume turn the prior session is preserved by writeThread anyway.
       });
+      // The MODE-CORRECT, RESOLVABLE thread id stamped into outbound + failure notes
+      // (agent#163): single-threaded → the deterministic thread-NOTE id (stable across turns);
+      // multi-threaded → the per-fire `turnThreadId`. Computed once from the start-ensure id so
+      // every path (early failure, ok, outbound-failure) stamps the same resolvable link.
+      const outThreadId = outboundThreadId(multiThreaded, turnThreadId, startThreadNoteId);
+
+      // RUN CONTEXT (agent#162): assemble the runtime facts a headless `claude -p` turn can't
+      // know — the REAL wall-clock (`startedAt`), whether this run CONTINUES a prior session
+      // (`turnSession.resume`) or starts fresh, and WHY it fired (a scheduled job vs an
+      // interactive/delegated message, from the inbound sender). The backend prepends these as
+      // a labeled preamble so the agent stamps ACCURATE times instead of fabricating them.
+      // (DEFERRED: `priorTurnCount` — the rolling turn_count lives in the transport's thread
+      // note and isn't surfaced back to the drain; wiring it is a follow-up. Until then the
+      // preamble omits the `turn=N` line — the `now`/session/fired-by trio is the floor.)
+      const firedBy = runFiredBy(msg.sender);
+      const runContext: RunContext = {
+        now: startedAt,
+        session: turnSession.resume ? "resumed" : "new",
+        ...(firedBy ? { firedBy } : {}),
+      };
+
+      // SUBJECT DOSSIER (roles×threads NOW slice): when the inbound carries a subject AND a
+      // dossier source is wired, resolve the per-thread context the backend folds into the
+      // composed system prompt. UNWIRED by default (no dossier-note convention yet) and
+      // no-subject always → `undefined`, so the system prompt is the role body verbatim and
+      // the null-subject path is byte-identical to HEAD. Best-effort: a dossier read failure
+      // logs + the turn still runs (role-only), never strands the queue.
+      let subjectDossier: string | undefined;
+      if (msg.subject && this.readSubjectDossier) {
+        try {
+          subjectDossier = await this.readSubjectDossier(handle.channel, msg.subject);
+        } catch (err) {
+          console.error(
+            `parachute-agent: subject-dossier read for channel "${channel}" ` +
+              `subject "${msg.subject}" failed (turn runs role-only): ${(err as Error).message}`,
+          );
+        }
+      }
 
       let result;
       try {
@@ -830,6 +948,11 @@ export class ProgrammaticAgentRegistry {
           // Phase 1: inbound attachments → the programmatic backend stages them into the
           // agent's private workspace so the turn can Read them. Absent/empty → no staging.
           msg.attachments,
+          // agent#162: the daemon-known runtime context (real clock, new/resumed, fired-by).
+          runContext,
+          // roles×threads NOW slice: the per-thread subject dossier, folded into the composed
+          // system prompt. Undefined (no subject / unwired source) → role body verbatim.
+          subjectDossier,
         );
       } catch (err) {
         // The backend contract is failure-as-VALUE, never a throw — but defend so a
@@ -854,8 +977,8 @@ export class ProgrammaticAgentRegistry {
         });
         this.emitTurnEvent(channel, { kind: "error", error: reason });
         // Post a user-facing failure note so the channel shows SOMETHING (not a silent
-        // no-reply) — best-effort.
-        await this.postFailureNote(channel, msg.inReplyTo, turnThreadId, reason);
+        // no-reply) — best-effort. Stamp the MODE-CORRECT resolvable thread id (agent#163).
+        await this.postFailureNote(channel, msg.inReplyTo, outThreadId, reason);
         // CALLBACK on the failure too — an orchestrator MUST learn its sub-task failed, not
         // hang waiting forever. No outbound note was produced, so no `source_message`; the
         // RESOLVABLE thread-note id (written above) is `source_thread` so the orchestrator can
@@ -886,8 +1009,8 @@ export class ProgrammaticAgentRegistry {
         });
         this.emitTurnEvent(channel, { kind: "error", error: result.error });
         // Post a user-facing failure note so the channel shows SOMETHING (not a silent
-        // no-reply) — best-effort.
-        await this.postFailureNote(channel, msg.inReplyTo, turnThreadId, result.error);
+        // no-reply) — best-effort. Stamp the MODE-CORRECT resolvable thread id (agent#163).
+        await this.postFailureNote(channel, msg.inReplyTo, outThreadId, result.error);
         // CALLBACK on the failure-as-value too (status:error) — the orchestrator learns the
         // sub-task failed and can react. No delivered reply, so no `source_message`; the
         // RESOLVABLE thread-note id (written above) is `source_thread` (agent#124).
@@ -931,7 +1054,12 @@ export class ProgrammaticAgentRegistry {
           channel,
           result.reply,
           msg.inReplyTo,
-          turnThreadId,
+          // agent#163: stamp the MODE-CORRECT, RESOLVABLE thread id into the outbound note's
+          // `metadata.thread` — single-threaded → the deterministic thread-NOTE id (stable
+          // across turns; an observer resolves the ONE thread), multi-threaded → the per-fire
+          // id. NOT the per-turn correlation UUID (the pre-#163 bug that looked like a fresh
+          // session every run).
+          outThreadId,
         );
         if (delivered.ok) sourceMessage = delivered.noteId;
         if (!delivered.ok) {

package/src/backends/types.ts

@@ -84,6 +84,43 @@ export interface TurnSession {
   resume: boolean;
 }
 
+/**
+ * RUN CONTEXT for one turn (agent#162) — the runtime facts a programmatic `claude -p` turn
+ * otherwise has NO way to know, so an agent stops FABRICATING them. A headless `-p` turn has
+ * no clock and no notion of "which run this is": uni-weaver was openly inventing report
+ * timestamps (a fixed `10:05` slot, the date "derived from context") because it couldn't read
+ * a real clock mid-run. The daemon KNOWS these facts at dispatch time, so it injects them into
+ * the turn (a concise, clearly-labeled preamble the agent reads) rather than letting the agent
+ * guess. Cheap, and it removes a whole class of fabricated-time confusion.
+ *
+ * The backend renders this as a SHORT preamble prepended to the turn message — it never
+ * mangles the agent's own system-prompt semantics. ADDITIVE: a caller that omits it leaves the
+ * turn message exactly as before.
+ */
+export interface RunContext {
+  /** The REAL wall-clock at dispatch (ISO 8601) — the authoritative clock the turn lacks. */
+  now: string;
+  /**
+   * Whether this turn CONTINUES a prior conversation (`resumed`, single-threaded turn 2+) or
+   * STARTS a fresh one (`new`, the first turn / every multi-threaded fire) — the cheap "which
+   * run is this" signal the daemon already resolved (`TurnSession.resume`).
+   */
+  session: "new" | "resumed";
+  /**
+   * WHY this turn is running (provenance): a SCHEDULED job fire stamps `runner:<jobId>` (the
+   * runner's sender provenance) → reported as the job id; anything else is an interactive /
+   * delegated message → `interactive`. Lets a scheduled agent know it's a cron fire vs a live
+   * reply. Absent when the inbound carried no sender.
+   */
+  firedBy?: string;
+  /**
+   * The thread's COMPLETED turn count BEFORE this turn (single-threaded's rolling counter;
+   * 0 on the first turn). Best-effort — omitted when the daemon can't cheaply resolve it
+   * (no durable thread store). So the agent can stamp "turn N" accurately.
+   */
+  priorTurnCount?: number;
+}
+
 /**
  * An opaque handle to a started agent, returned by {@link AgentBackend.start} and
  * passed back to `deliver`/`stop`/`status`. The only field the seam itself depends
@@ -201,6 +238,20 @@ export interface AgentBackend {
    * a safe basename) before the turn and appends a workspace-relative pointer to the
    * prompt, so the `claude -p` turn can `Read` them. ADDITIVE — absent/empty → no
    * staging, the turn behaves exactly as before.
+   *
+   * `runContext` (optional, agent#162) is the runtime context the daemon knows but a headless
+   * `-p` turn can't (the real wall-clock, whether this run is new vs resumed, why it fired).
+   * The programmatic backend prepends it as a concise, clearly-labeled preamble to the turn
+   * message so the agent stamps ACCURATE times instead of fabricating them. ADDITIVE — omitted
+   * → the turn message is exactly as before.
+   *
+   * `subjectDossier` (optional, roles×threads NOW slice) is per-THREAD context for the
+   * agent's CURRENT subject — folded into the SYSTEM prompt (NOT the message): the programmatic
+   * backend writes `roleBody + "\n\n---\n\n" + dossier` to the per-turn `system-prompt.txt` when
+   * present, so the agent's ROLE (the spec's systemPrompt) stays stable across threads while the
+   * subject-specific context layers on top. The run-context preamble is unaffected (it stays on
+   * the MESSAGE). ADDITIVE — omitted/empty → the system prompt is the role body verbatim
+   * (byte-identical to HEAD; the null-subject invariant).
    */
   deliver(
     handle: AgentHandle,
@@ -208,6 +259,8 @@ export interface AgentBackend {
     session: TurnSession,
     onInterim?: InterimSink,
     attachments?: InboundAttachment[],
+    runContext?: RunContext,
+    subjectDossier?: string,
   ): Promise<DeliverResult>;
 
   /**

package/src/daemon.ts

@@ -342,6 +342,13 @@ export function contextFor(
           // Phase 1: carry inbound file attachments through to the turn (the programmatic
           // backend stages them into the agent's private workspace so the turn can Read them).
           ...(msg.attachments && msg.attachments.length > 0 ? { attachments: msg.attachments } : {}),
+          // agent#162: carry the inbound sender so the drain can derive the run-context
+          // `fired-by` (a scheduled `runner:<jobId>` fire vs an interactive/delegated message).
+          ...(msg.meta?.sender ? { sender: msg.meta.sender } : {}),
+          // roles×threads NOW slice: carry the thread subject through to the drain so the
+          // composed prompt can fold in a subject dossier (and the NEXT slice can route by
+          // it). No routing meaning yet. Absent → unchanged (the weave path is untouched).
+          ...(msg.meta?.subject ? { subject: msg.meta.subject } : {}),
         });
         return;
       }
@@ -366,6 +373,13 @@ export function contextFor(
           // Phase 1: carry inbound attachments through the pending buffer too, so a turn
           // that runs on register() still stages them.
           ...(msg.attachments && msg.attachments.length > 0 ? { attachments: msg.attachments } : {}),
+          // agent#162: carry the sender through the pending buffer too, so a turn that runs on
+          // register() still derives the right run-context `fired-by`.
+          ...(msg.meta?.sender ? { sender: msg.meta.sender } : {}),
+          // roles×threads NOW slice: carry the thread subject through the pending buffer too,
+          // so a turn that runs on register() still folds in its subject dossier. No routing
+          // meaning yet. Absent → unchanged.
+          ...(msg.meta?.subject ? { subject: msg.meta.subject } : {}),
         });
         if (outcome === "queued") return;
         // outcome === "unknown" — not an expected programmatic channel. It may still be a
@@ -1809,7 +1823,12 @@ export function createFetchHandler(
           if (!transport) {
             return json({ error: `job "${id}" targets a non-vault channel "${job.channel}"` }, 400);
           }
-          await transport.injectInbound({ content: job.message, sender: `runner:${job.id}` });
+          // roles×threads NOW slice: thread the job's subject (absent → no subject).
+          await transport.injectInbound({
+            content: job.message,
+            sender: `runner:${job.id}`,
+            ...(job.subject ? { subject: job.subject } : {}),
+          });
           return json({ ok: true, id, status: "ok" });
         } catch (err) {
           return json({ error: `failed to run job: ${(err as Error).message}` }, 502);
@@ -3375,7 +3394,14 @@ function main(): void {
       if (!transport) {
         throw new Error(`channel "${job.channel}" is not a live vault channel`);
       }
-      await transport.injectInbound({ content: job.message, sender: `runner:${job.id}` });
+      // roles×threads NOW slice: thread the job's subject onto the inbound note so the
+      // turn's composed prompt can fold in its dossier. Absent → no subject (the weave
+      // job carries none → byte-identical to HEAD).
+      await transport.injectInbound({
+        content: job.message,
+        sender: `runner:${job.id}`,
+        ...(job.subject ? { subject: job.subject } : {}),
+      });
     },
     // Persist bookkeeping (lastRunAt/lastStatus) back onto the job note (addressed
     // by its vault note id). A job loaded from the store always carries `noteId`.

package/src/jobs.ts

@@ -65,6 +65,13 @@ export interface Job {
   lastStatus?: string;
   /** ISO timestamp of the next scheduled fire — COMPUTED IN MEMORY, never persisted. */
   nextRunAt?: string;
+  /**
+   * The THREAD SUBJECT a fire of this job carries (roles×threads NOW slice). When set,
+   * the runner stamps it onto the inbound note (`metadata.subject`) so the turn's composed
+   * prompt + (NEXT) thread routing can read it. Optional; absent → today's behavior (the
+   * weave job carries none — its fire is byte-identical to HEAD).
+   */
+  subject?: string;
 }
 
 /** A slug: alphanumeric, dash, underscore (same shape as channel names). */
@@ -202,6 +209,7 @@ export class VaultJobStore {
           createdAt: n.createdAt ?? "",
           ...(n.lastRunAt ? { lastRunAt: n.lastRunAt } : {}),
           ...(n.lastStatus ? { lastStatus: n.lastStatus } : {}),
+          ...(n.subject ? { subject: n.subject } : {}),
         });
       }
     }
@@ -229,6 +237,7 @@ export class VaultJobStore {
       createdAt: job.createdAt,
       ...(job.lastRunAt ? { lastRunAt: job.lastRunAt } : {}),
       ...(job.lastStatus ? { lastStatus: job.lastStatus } : {}),
+      ...(job.subject ? { subject: job.subject } : {}),
     });
     return { ...job, noteId }; // id stays the slug; noteId addresses the persisted note.
   }

package/src/sandbox/types.ts

@@ -380,3 +380,41 @@ export function normalizeChannel(ch: AgentChannel): { name: string; access: "rea
   if (typeof ch === "string") return { name: ch, access: "write" };
   return { name: ch.name, access: ch.access ?? "write" };
 }
+
+/**
+ * Collapse a string to a flat, path-safe slug — every char outside
+ * `[a-zA-Z0-9_-]` becomes `-`. This MIRRORS the channel/name sanitizer used on
+ * the vault note paths (`vault.ts:746`, `:822-823`) so a value sanitized here
+ * can be used as a path leaf or a `--session-id` segment without re-escaping.
+ * Pure + idempotent. Exported so the NEXT slice (per-thread workspace paths,
+ * spec §G) reuses this exact sanitizer rather than re-implementing it (drift risk).
+ */
+export function slug(raw: string): string {
+  return raw.replace(/[^a-zA-Z0-9_-]/g, "-");
+}
+
+/**
+ * The THREAD identity key for one (agent, subject) pair — the roles×threads NOW
+ * slice (design team-vault `Strategy/2026-06-29-agents-roles-threads`).
+ *
+ *  - No subject (absent / empty / whitespace-only) → the BARE `specName`. This is
+ *    the back-compat path: every agent today (incl. the weave) carries no subject,
+ *    so `threadKey` returns exactly the spec name and every downstream
+ *    path/key/workspace is byte-identical to HEAD.
+ *  - A non-empty subject → `${specName}--${slug(subject)}`. The `--` separator and
+ *    the `slug()` sanitize make the key safe to use as a vault path leaf or a
+ *    Claude `--session-id` segment.
+ *
+ * SECURITY: `subject` is UNTRUSTED input that later becomes a path leaf, so it is
+ * run through {@link slug} here — `../`, spaces, slashes, and other path-dangerous
+ * chars collapse to `-`, so a subject can never traverse the path hierarchy.
+ * `specName` is NOT sanitized here (it's already a sanitized agent/channel name
+ * upstream); only the untrusted subject is.
+ *
+ * NOTE: subject is PER-THREAD — it rides on the inbound message, NOT on the
+ * {@link AgentSpec} (which is per-AGENT). Keep it off the spec.
+ */
+export function threadKey(specName: string, subject?: string): string {
+  const trimmed = subject?.trim();
+  return trimmed ? `${specName}--${slug(trimmed)}` : specName;
+}

package/src/transports/vault.ts

@@ -161,6 +161,11 @@ export interface JobNote {
   lastRunAt?: string;
   /** "ok" / "error: …" from the most recent fire. */
   lastStatus?: string;
+  /**
+   * The THREAD SUBJECT a fire carries (roles×threads NOW slice) — read back from
+   * `metadata.subject`. Optional; absent → today's behavior (no subject).
+   */
+  subject?: string;
 }
 
 /** The metadata payload written for a job note (all string-typed, per the vault). */
@@ -176,6 +181,13 @@ export interface JobNoteMetadata {
   createdAt: string;
   lastRunAt?: string;
   lastStatus?: string;
+  /**
+   * The THREAD SUBJECT a fire of this job carries (roles×threads NOW slice) — stamped
+   * onto the inbound note the runner injects, so the turn's composed prompt + (NEXT)
+   * thread routing can read it. Optional; absent → today's behavior (the weave job
+   * carries none).
+   */
+  subject?: string;
 }
 
 /**
@@ -761,11 +773,14 @@ export class VaultTransport implements Transport {
     // Thread the reply to the inbound note id when the bridge passes it through.
     const inReplyTo = args.meta?.in_reply_to;
     if (inReplyTo) metadata.in_reply_to = inReplyTo;
-    // The explicit definition→thread→message link: stamp the outbound note with its thread
-    // id (the programmatic worker passes the per-turn thread id through `meta.thread`). For a
-    // multi-threaded turn this IS the per-fire `#agent/thread` note's leaf; for a
-    // single-threaded turn it's a per-turn correlation id. INBOUND-note stamping is deferred
-    // (those notes are written externally, before the turn knows its thread).
+    // The explicit definition→thread→message link: stamp the outbound note with its
+    // RESOLVABLE, mode-correct thread id (the programmatic worker passes it through
+    // `meta.thread`, agent#163). For a multi-threaded turn this IS the per-fire `#agent/thread`
+    // note's leaf; for a single-threaded turn it's the DETERMINISTIC thread-NOTE id
+    // (`Threads/<channel>/<name>`), STABLE across turns — so an observer resolves the agent's
+    // ONE thread from `metadata.thread`, not a per-turn UUID that changed every run.
+    // INBOUND-note stamping is deferred (those notes are written externally, before the turn
+    // knows its thread).
     const threadId = args.meta?.thread;
     if (threadId) metadata.thread = threadId;
 
@@ -1316,8 +1331,21 @@ export class VaultTransport implements Transport {
    * thin wrapper over `writeInbound` so the inbound write path has ONE
    * implementation; only the default sender differs.
    */
-  async injectInbound(opts: { content: string; sender?: string }): Promise<{ id: string }> {
-    return this.writeInbound(opts.content, opts.sender ?? "runner");
+  async injectInbound(opts: {
+    content: string;
+    sender?: string;
+    /**
+     * SUBJECT (roles×threads NOW slice) — the thread axis for a runner-fired turn.
+     * When a job carries a subject, the runner threads it here; it's stamped onto the
+     * inbound note's `metadata.subject` (via {@link writeInbound}'s `extraMeta`) so the
+     * turn's composed prompt + (NEXT) thread routing can read it. Absent/empty → NO
+     * `subject` field on the note (today's behavior exactly — the weave job is unaffected).
+     */
+    subject?: string;
+  }): Promise<{ id: string }> {
+    const subject = opts.subject?.trim();
+    const extraMeta = subject ? { subject } : undefined;
+    return this.writeInbound(opts.content, opts.sender ?? "runner", extraMeta);
   }
 
   /**
@@ -1576,6 +1604,10 @@ export class VaultTransport implements Transport {
       if (typeof m.createdAt === "string") job.createdAt = m.createdAt;
       if (typeof m.lastRunAt === "string") job.lastRunAt = m.lastRunAt;
       if (typeof m.lastStatus === "string") job.lastStatus = m.lastStatus;
+      // roles×threads NOW slice: read the thread subject back (absent/blank → undefined).
+      // Trim-guarded symmetrically with the write side (upsertJobNote) so a whitespace-only
+      // value that somehow landed in the vault can't propagate downstream as a "subject".
+      if (typeof m.subject === "string" && m.subject.trim()) job.subject = m.subject.trim();
       jobs.push(job);
     }
     return jobs;
@@ -1597,6 +1629,8 @@ export class VaultTransport implements Transport {
     createdAt: string;
     lastRunAt?: string;
     lastStatus?: string;
+    /** The thread subject a fire carries (roles×threads NOW slice); absent → no field. */
+    subject?: string;
   }): Promise<{ id: string }> {
     const safeId = job.id.replace(/[^a-zA-Z0-9_-]/g, "-");
     const safeChannel = job.channel.replace(/[^a-zA-Z0-9_-]/g, "-");
@@ -1612,6 +1646,11 @@ export class VaultTransport implements Transport {
     if (job.tz) metadata.tz = job.tz;
     if (job.lastRunAt) metadata.lastRunAt = job.lastRunAt;
     if (job.lastStatus) metadata.lastStatus = job.lastStatus;
+    // roles×threads NOW slice: persist a non-empty subject; absent → no field (the weave
+    // job writes none, so its note is byte-identical to HEAD).
+    if (typeof job.subject === "string" && job.subject.trim().length > 0) {
+      metadata.subject = job.subject.trim();
+    }
 
     const res = await fetch(`${this.vaultUrl}/vault/${this.vault}/api/notes`, {
       method: "POST",
@@ -1769,9 +1808,13 @@ export class VaultTransport implements Transport {
     }
     // Flatten the note's metadata into the inbound meta (string-valued), then
     // stamp our own provenance fields. `source`/`note_id`/`direction` are set
-    // explicitly so they win over anything in the note's metadata.
+    // explicitly so they win over anything in the note's metadata. `subject` is
+    // SKIPPED here and handled explicitly below (normalized to non-empty-or-absent),
+    // so a blank `subject: "   "` can't slip through the raw spread — absent and
+    // whitespace-only must be indistinguishable downstream (the null-subject invariant).
     const flatMeta: Record<string, string> = {};
     for (const [k, v] of Object.entries(meta)) {
+      if (k === "subject") continue;
       flatMeta[k] = typeof v === "string" ? v : String(v);
     }
 
@@ -1786,6 +1829,18 @@ export class VaultTransport implements Transport {
       attachments = await this.fetchInboundAttachments(note.id);
     }
 
+    // SUBJECT (roles×threads NOW slice). The thread axis: when the inbound note
+    // carries a non-empty string `metadata.subject`, surface it onto the emitted
+    // event meta so it can flow through the queue → composed prompt → (NEXT) thread
+    // routing. ABSENT/empty → no `subject` field on the emitted meta, so the emit is
+    // BYTE-IDENTICAL to HEAD (the null-subject invariant — the weave path is untouched).
+    // `subject` is deliberately SKIPPED in the `flatMeta` spread above and re-added here
+    // ONLY when non-empty, so an empty/whitespace-only value can never leak through —
+    // absent and blank are indistinguishable downstream.
+    const rawSubject = meta.subject;
+    const subject =
+      typeof rawSubject === "string" && rawSubject.trim().length > 0 ? rawSubject : undefined;
+
     this.ctx.emit({
       // `channel` here is the in-memory InboundMessage.channel TS field (NOT serialized
       // note metadata) — left as the channel name. The routing key rides in `meta.agent`.
@@ -1800,6 +1855,7 @@ export class VaultTransport implements Transport {
         note_id: note.id,
         sender: typeof meta.sender === "string" ? meta.sender : "",
         direction: "inbound",
+        ...(subject ? { subject } : {}),
       },
       source: "vault",
       ...(attachments.length > 0 ? { attachments } : {}),