@openparachute/agent 0.2.3-rc.11 → 0.2.3-rc.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.2.3-rc.11",
+  "version": "0.2.3-rc.13",
   "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

@@ -442,13 +442,20 @@ export class ProgrammaticBackend implements AgentBackend {
     onInterim?: InterimSink,
     attachments?: InboundAttachment[],
     runContext?: RunContext,
+    subjectDossier?: string,
+    subject?: string,
   ): Promise<DeliverResult> {
     const spec = handle.spec;
     if (!spec) {
       return { ok: false, error: `ProgrammaticBackend.deliver: handle for "${handle.name}" carries no spec` };
     }
     const channel = handle.channel;
-    const workspace = sessionWorkspace(this.deps.sessionsDir, spec.name);
+    // roles×threads NEXT slice (#120, G): the PER-THREAD private workspace. A subject keys
+    // a distinct `sessions/<name>--<slug(subject)>/` dir (its own `.mcp.json` /
+    // `system-prompt.txt` / HOME / attachment staging — see stageAttachments below, which
+    // takes THIS workspace), so concurrent subjects of one multi-threaded agent never clobber
+    // each other's per-turn files. NO subject → `sessions/<name>/` (HEAD, byte-identical).
+    const workspace = sessionWorkspace(this.deps.sessionsDir, spec.name, subject);
 
     // Resolve the Claude OAuth credential keyed on the wake channel. A missing
     // credential throws (CredentialNotConfigured) BEFORE any mint/spawn side effect.
@@ -587,10 +594,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

@@ -43,7 +43,7 @@
  */
 
 import type { AgentSpec, AgentMode } from "../sandbox/types.ts";
-import { normalizeChannel } from "../sandbox/types.ts";
+import { normalizeChannel, threadKey } from "../sandbox/types.ts";
 import type { AgentBackend, AgentHandle, InterimTurnEvent, RunContext, TurnSession } from "./types.ts";
 import type { InboundAttachment } from "../transport.ts";
 
@@ -118,6 +118,14 @@ export interface ThreadNote {
    * transport sanitizes it into the deterministic upsert path). Falls back to the channel.
    */
   name?: string;
+  /**
+   * The thread SUBJECT (roles×threads NEXT slice, #120) — when present, a MULTI-threaded
+   * thread becomes a DETERMINISTIC, upserting note at `threadKey(name, subject)`
+   * (`Threads/<ch>/<name>--<subject>`) carrying a session across fires (per-thread
+   * continuity), instead of a per-fire uuid note. Absent/empty → today's identity
+   * (single-threaded deterministic note / multi-threaded per-fire note), byte-identical to HEAD.
+   */
+  subject?: string;
   /** The `#agent/definition` note id (provenance; plain id string). */
   definition?: string;
   /** The mode the turn ran under — governs thread identity + whether the note upserts. */
@@ -308,26 +316,26 @@ function delay(ms: number): Promise<void> {
 /**
  * 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):
+ * `source_thread` fix (agent#124). Keyed on `perFire`:
  *
- *  - 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.
+ *  - DETERMINISTIC thread (`perFire: false`) — single-threaded, OR a multi-threaded SUBJECT
+ *    thread (roles×threads NEXT slice, #120). The note is the resolvable, deterministic
+ *    `Threads/<safeChannel>/<name[--subject]>` note, so an observer reading the outbound's
+ *    `metadata.thread` resolves the agent's stable thread with `query-notes { id }`. Stamp
+ *    the resolvable `threadNoteId`. The pre-#163 bug stamped the per-turn correlation UUID
+ *    here, which changed every turn and resolved to nothing.
+ *  - PER-FIRE thread (`perFire: true`) — a multi-threaded thread with NO subject: each fire is
+ *    its own note at `Threads/<safeChannel>/<turnThreadId>`, so the per-fire id IS the leaf.
  *
  * 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,
+  perFire: boolean,
   turnThreadId: string,
   threadNoteId: string | undefined,
 ): string {
-  if (multiThreaded) return turnThreadId;
+  if (perFire) return turnThreadId;
   return threadNoteId ?? turnThreadId;
 }
 
@@ -393,6 +401,16 @@ export interface QueuedMessage {
    * 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). */
@@ -427,9 +445,25 @@ export class ProgrammaticAgentRegistry {
   private readonly byChannel = new Map<string, ProgrammaticAgentHandle>();
   /** name → channel (the lifecycle index; an agent has exactly one wake channel). */
   private readonly nameToChannel = new Map<string, string>();
-  /** channel → FIFO queue of pending messages. */
+  /**
+   * DRAIN-KEY → FIFO queue of pending messages — the PER-THREAD serial queue
+   * (roles×threads NEXT slice, #120). The drain key is {@link drainKeyFor}:
+   *  - a single-threaded agent, OR a message with NO subject → the bare CHANNEL
+   *    (byte-identical to HEAD — every current agent incl. the weave routes here).
+   *  - a multi-threaded agent WITH a subject → `threadKey(spec.name, subject)`
+   *    (`<name>--<subject>`), so distinct subjects of one agent get distinct queues.
+   * Keying queues + {@link draining} by the SAME drain key is what makes two messages
+   * of the SAME (name, subject) strictly serial while letting two DIFFERENT subjects
+   * of one agent run concurrently — the per-thread serial guarantee (class doc lines 13-20).
+   */
   private readonly queues = new Map<string, QueuedMessage[]>();
-  /** channel → the in-flight drain promise (its presence == a worker is running). */
+  /**
+   * DRAIN-KEY → the in-flight drain promise (its presence == a worker is running for that
+   * thread). One promise per drain key is the structural lock: a second message for the
+   * SAME drain key never starts a second worker (it appends + the running worker picks it
+   * up), so a given (name, subject) thread is NEVER processed by two concurrent `claude -p`.
+   * A DIFFERENT subject is a DIFFERENT key → its own promise → may run concurrently.
+   */
   private readonly draining = new Map<string, Promise<void>>();
   /**
    * channel → FIFO queue of PENDING-INBOUND messages that arrived BEFORE a live
@@ -470,14 +504,28 @@ export class ProgrammaticAgentRegistry {
    * 2+ `--resume`s its prior conversation. Unwired (or no prior) → every turn creates a
    * fresh session. Multi-threaded NEVER consults it (each fire is a fresh thread).
    */
-  private readonly readSession?: (channel: string, name: string) => Promise<string | undefined>;
+  private readonly readSession?: (
+    channel: string,
+    name: string,
+    subject?: string,
+  ) => Promise<string | undefined>;
   /**
    * Optional session CLEAR — wipe a single-threaded agent's persisted thread-note session
    * so its next turn starts a FRESH claude conversation (the per-agent restart). The daemon
    * wires this to the channel transport's `clearThreadSession`. Called by {@link resetSession}.
    * Unwired → reset is a clean no-op beyond returning that the agent exists.
    */
-  private readonly clearSession?: (channel: string, name: string) => Promise<void>;
+  private readonly clearSession?: (channel: string, name: string, subject?: 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;
 
@@ -487,10 +535,22 @@ export class ProgrammaticAgentRegistry {
     writeThread?: WriteThread;
     writeCallback?: WriteCallback;
     onTurnEvent?: TurnEventSink;
-    /** Read the persisted thread-note session UUID (single-threaded resume). */
-    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 persisted thread-note session UUID. `subject` (roles×threads NEXT slice, #120)
+     * resolves the SUBJECT-scoped thread note for a multi-threaded subject thread; omitted →
+     * the deterministic def-named note (single-threaded resume, HEAD).
+     */
+    readSession?: (channel: string, name: string, subject?: string) => Promise<string | undefined>;
+    /**
+     * Clear the persisted thread-note session (the per-agent restart / reset). `subject`
+     * resolves the subject-scoped thread note; omitted → the def-named note (HEAD).
+     */
+    clearSession?: (channel: string, name: string, subject?: 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;
   }) {
@@ -501,6 +561,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;
   }
 
@@ -526,6 +587,59 @@ export class ProgrammaticAgentRegistry {
     return normalizeChannel(spec.channels[0]!).name;
   }
 
+  /**
+   * The PER-THREAD serial DRAIN KEY for an inbound message (roles×threads NEXT slice, #120)
+   * — what {@link queues} + {@link draining} are keyed by:
+   *  - SINGLE-threaded agent, OR a message with NO subject → the bare CHANNEL. This is the
+   *    back-compat path: every agent today (incl. the weave) carries no subject, so the key
+   *    is exactly the channel and the queue/drain behavior is byte-identical to HEAD.
+   *  - MULTI-threaded agent WITH a subject → `threadKey(spec.name, subject)` (`<name>--<sub>`),
+   *    so two subjects of one agent get DISTINCT queues + DISTINCT drain promises (concurrent),
+   *    while two messages of the SAME subject share one queue + one promise (strictly serial).
+   *
+   * NOTE: a message can only carry a subject route when a LIVE handle exists for the channel
+   * (enqueue requires byChannel), so we read the mode off that handle. A missing handle (the
+   * caller already returns false) defaults to the channel key.
+   */
+  private drainKeyFor(channel: string, msg: QueuedMessage): string {
+    const handle = this.byChannel.get(channel);
+    if (!handle) return channel;
+    const multiThreaded = (handle.spec.mode ?? "single-threaded") === "multi-threaded";
+    if (!multiThreaded) return channel;
+    // threadKey returns the bare name for no/empty subject — but the channel (not the name)
+    // is the back-compat single-thread key, so only re-key when a subject actually narrows it.
+    const subject = msg.subject?.trim();
+    if (!subject) return channel;
+    return threadKey(handle.spec.name, subject);
+  }
+
+  /**
+   * Drop EVERY per-thread queue + drain promise belonging to a channel — used on
+   * teardown/re-key (deregister, a name moving channels). Because {@link queues} +
+   * {@link draining} are now keyed by the per-thread DRAIN KEY (`<channel>` or
+   * `<channel-name>--<subject>`), deleting only the bare-channel key would orphan a
+   * multi-threaded agent's subject queues. We clear the channel key AND every
+   * `<channel-name>--*` subject key whose threadKey is prefixed by the channel's agent name.
+   * An in-flight subject drain self-terminates on its next loop (it re-reads byChannel,
+   * now empty for that channel); dropping the `draining` entry just stops the map leaking.
+   */
+  private clearChannelQueues(channel: string): void {
+    // The bare-channel key (single-threaded / no-subject path).
+    this.queues.delete(channel);
+    this.draining.delete(channel);
+    // Subject keys are `${spec.name}--${slug(subject)}`. Resolve the agent name for this
+    // channel if a handle is still present; else fall back to the channel as the name prefix
+    // (covers the common case name===channel). Match any key with that `--`-prefixed form.
+    const handle = this.byChannel.get(channel);
+    const namePrefix = `${handle?.spec.name ?? channel}--`;
+    for (const key of [...this.queues.keys()]) {
+      if (key.startsWith(namePrefix)) this.queues.delete(key);
+    }
+    for (const key of [...this.draining.keys()]) {
+      if (key.startsWith(namePrefix)) this.draining.delete(key);
+    }
+  }
+
   /** Is a programmatic agent registered for this channel? (the inbound-routing check) */
   hasChannel(channel: string): boolean {
     return this.byChannel.has(channel);
@@ -558,6 +672,10 @@ export class ProgrammaticAgentRegistry {
    * /health + the agents list to render `programmatic · idle|working|queued:N`.
    */
   statusOf(channel: string): { state: ProgrammaticAgentState; queued: number } {
+    // NOTE (roles×threads NEXT slice): this reads only the BARE-channel drain key, so a
+    // multi-threaded agent whose active work is on subject keys (`name--subject`) reports
+    // `idle` here. Acceptable while multi-threaded agents aren't in production; tracked for
+    // a /health upgrade before they are (the drain key, not the channel, is the unit of work).
     const queued = this.queues.get(channel)?.length ?? 0;
     if (this.draining.has(channel)) {
       // A worker is in flight. If there are messages waiting BEHIND the in-flight
@@ -591,9 +709,13 @@ export class ProgrammaticAgentRegistry {
       // channel's EXPECTED mark + any stranded pending buffer — nothing routes there now,
       // so a residual mark/buffer would leak (reviewer nit; defense-in-depth — the normal
       // flow only ever expects the NEW channel before this register).
+      // Clear EVERY per-thread queue/drain for the old channel (bare + subject keys), not
+      // just the bare-channel key — a multi-threaded agent's subject queues would otherwise
+      // leak (roles×threads NEXT slice). clearChannelQueues reads the handle for the subject-key
+      // name prefix, so run it BEFORE byChannel.delete while the handle is still present — that
+      // resolves the REAL agent name even if name !== channel in a future split (reviewer nit).
+      this.clearChannelQueues(priorChannel);
       this.byChannel.delete(priorChannel);
-      this.queues.delete(priorChannel);
-      this.draining.delete(priorChannel);
       this.expectedChannels.delete(priorChannel);
       this.pending.delete(priorChannel);
     }
@@ -714,9 +836,13 @@ export class ProgrammaticAgentRegistry {
     const channel = this.nameToChannel.get(name);
     if (channel === undefined) return false;
     const handle = this.byChannel.get(channel);
+    // Clear every per-thread queue/drain for this channel (bare + subject keys) BEFORE
+    // dropping byChannel, so the handle is still present to resolve the agent-name prefix
+    // for the subject keys (roles×threads NEXT slice). An in-flight subject drain
+    // self-terminates on its next loop (it re-reads byChannel, now empty for the channel).
+    this.clearChannelQueues(channel);
     this.byChannel.delete(channel);
     this.nameToChannel.delete(name);
-    this.queues.delete(channel);
     // Clear the EXPECTED mark + any buffered pending inbound for this channel too —
     // the agent is gone, so a pending message has nothing to drain into and would
     // strand forever (and the next register would replay stale messages). The daemon's
@@ -778,17 +904,26 @@ export class ProgrammaticAgentRegistry {
    */
   enqueue(channel: string, msg: QueuedMessage): boolean {
     if (!this.byChannel.has(channel)) return false;
-    const queue = this.queues.get(channel) ?? [];
+    // PER-THREAD ROUTING (roles×threads NEXT slice, #120): resolve the drain key. A
+    // single-threaded / no-subject message keys by the bare CHANNEL (byte-identical to
+    // HEAD); a multi-threaded agent WITH a subject keys by `threadKey(name, subject)`, so
+    // distinct subjects get distinct queues + distinct drain promises (concurrent), while
+    // the SAME subject shares one queue + one promise (strictly serial). The serial
+    // guarantee is per DRAIN KEY, not per channel.
+    const drainKey = this.drainKeyFor(channel, msg);
+    const queue = this.queues.get(drainKey) ?? [];
     queue.push(msg);
-    this.queues.set(channel, queue);
-    // Start the worker if it isn't already running. The drain promise's PRESENCE in
-    // `draining` is the "a worker is running" flag — set it synchronously before any
-    // await so a second enqueue in the same tick can't start a second worker.
-    if (!this.draining.has(channel)) {
-      const p = this.drain(channel).finally(() => {
-        this.draining.delete(channel);
+    this.queues.set(drainKey, queue);
+    // Start the worker if it isn't already running FOR THIS DRAIN KEY. The drain promise's
+    // PRESENCE in `draining` (keyed by drain key) is the "a worker is running for this
+    // thread" flag — set it synchronously before any await so a second enqueue for the same
+    // drain key in the same tick can't start a second worker (the per-thread serial lock).
+    // A DIFFERENT drain key has its own entry → its own worker → may run concurrently.
+    if (!this.draining.has(drainKey)) {
+      const p = this.drain(drainKey, channel).finally(() => {
+        this.draining.delete(drainKey);
       });
-      this.draining.set(channel, p);
+      this.draining.set(drainKey, p);
     }
     return true;
   }
@@ -807,9 +942,13 @@ export class ProgrammaticAgentRegistry {
    * failure is logged; the turn still counts as drained (the reply is durable-or-not
    * at the transport's discretion; we don't re-run the turn, which would fork).
    */
-  private async drain(channel: string): Promise<void> {
+  private async drain(drainKey: string, channel: string): Promise<void> {
     for (;;) {
-      const queue = this.queues.get(channel);
+      // The FIFO for THIS thread — keyed by the per-thread drain key, NOT the channel. A
+      // single-threaded / no-subject thread's drain key IS the channel (back-compat); a
+      // subject thread's is `threadKey(name, subject)`. Reading the queue by drain key is
+      // what keeps two subjects of one agent independently serial.
+      const queue = this.queues.get(drainKey);
       if (!queue || queue.length === 0) return;
       const handle = this.byChannel.get(channel);
       if (!handle) return; // deregistered mid-drain — stop.
@@ -834,9 +973,23 @@ export class ProgrammaticAgentRegistry {
       // CREATE a fresh session with a new uuid (`--session-id`). The backend just runs the
       // turn with this {@link TurnSession}; it reads no session store.
       const multiThreaded = (handle.spec.mode ?? "single-threaded") === "multi-threaded";
+      // The thread SUBJECT (roles×threads NEXT slice, #120) — trimmed; empty → none.
+      const turnSubject = msg.subject?.trim() ? msg.subject : undefined;
+      // A multi-threaded agent WITH a subject is a NAMED thread: a deterministic note at
+      // `Threads/<ch>/<name>--<subject>` that upserts + carries a session across fires
+      // (turning "fresh thread per fire" into "resume the named thread"). A multi-threaded
+      // agent with NO subject stays fresh-per-fire (HEAD); a single-threaded agent is the
+      // HEAD deterministic def-named note.
+      const hasSubjectThread = multiThreaded && !!turnSubject;
+      // RESUME the persisted session when one exists for this thread note:
+      //  - single-threaded → its deterministic def-named note (HEAD behavior, unchanged).
+      //  - multi-threaded WITH a subject → the subject-scoped note (NEW: per-thread continuity).
+      //  - multi-threaded with NO subject → NEVER resume (each fire is a fresh thread; HEAD).
+      // The leaf is resolved transport-side via `singleThreadedPath(channel, name, subject)`,
+      // so write + read + clear all agree on the path (no leaf math duplicated here).
       let resumeId: string | undefined;
-      if (!multiThreaded && this.readSession) {
-        resumeId = await this.readSession(handle.channel, handle.spec.name);
+      if (this.readSession && (!multiThreaded || hasSubjectThread)) {
+        resumeId = await this.readSession(handle.channel, handle.spec.name, turnSubject);
       }
       const turnSession: TurnSession = resumeId
         ? { id: resumeId, resume: true }
@@ -871,10 +1024,13 @@ export class ProgrammaticAgentRegistry {
         // 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);
+      // (agent#163): a DETERMINISTIC thread (single-threaded OR a multi-threaded subject
+      // thread) → the deterministic thread-NOTE id (stable across turns); a PER-FIRE thread
+      // (multi-threaded, NO subject) → the per-fire `turnThreadId`. `perFire` is multi-threaded
+      // AND no subject. Computed once from the start-ensure id so every path (early failure, ok,
+      // outbound-failure) stamps the same resolvable link.
+      const perFire = multiThreaded && !hasSubjectThread;
+      const outThreadId = outboundThreadId(perFire, 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
@@ -891,6 +1047,24 @@ export class ProgrammaticAgentRegistry {
         ...(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 {
         // Forward each interim event to the streaming-view sink (keyed by channel)
@@ -906,6 +1080,14 @@ export class ProgrammaticAgentRegistry {
           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,
+          // roles×threads NEXT slice (#120, G): the thread SUBJECT — the backend keys the
+          // PER-THREAD private workspace off it (`sessions/<name>--<subject>/`), so concurrent
+          // subjects of one agent never clobber each other's per-turn `.mcp.json` /
+          // `system-prompt.txt` / HOME. Undefined → `sessions/<name>/` (HEAD, unchanged).
+          turnSubject,
         );
       } catch (err) {
         // The backend contract is failure-as-VALUE, never a throw — but defend so a
@@ -1198,6 +1380,12 @@ export class ProgrammaticAgentRegistry {
     const thread: ThreadNote = {
       channel: handle.channel,
       name: handle.spec.name,
+      // roles×threads NEXT slice (#120): carry the thread SUBJECT so the transport can
+      // resolve a subject-scoped deterministic thread note (`Threads/<ch>/<name>--<subject>`)
+      // that UPSERTS + carries a session across fires (per-thread continuity) instead of a
+      // per-fire uuid note. Absent/empty → no subject → today's identity (single-threaded
+      // deterministic note, or multi-threaded per-fire note) is byte-identical to HEAD.
+      ...(msg.subject?.trim() ? { subject: msg.subject } : {}),
       ...(handle.spec.definition ? { definition: handle.spec.definition } : {}),
       mode: handle.spec.mode ?? "single-threaded",
       status,

package/src/backends/types.ts

@@ -244,6 +244,22 @@ export interface AgentBackend {
    * 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).
+   *
+   * `subject` (optional, roles×threads NEXT slice #120) is the thread SUBJECT — the programmatic
+   * backend keys the agent's PER-THREAD private session workspace off it
+   * (`sessions/<name>--<slug(subject)>/`), so concurrent subjects of one multi-threaded agent get
+   * ISOLATED per-turn files (`.mcp.json`, `system-prompt.txt`, HOME, attachment staging) and never
+   * clobber each other. ADDITIVE — omitted/empty → `sessions/<name>/` (byte-identical to HEAD;
+   * the null-subject invariant). Distinct from `subjectDossier` (which is prompt CONTENT); this is
+   * the workspace IDENTITY.
    */
   deliver(
     handle: AgentHandle,
@@ -252,6 +268,8 @@ export interface AgentBackend {
     onInterim?: InterimSink,
     attachments?: InboundAttachment[],
     runContext?: RunContext,
+    subjectDossier?: string,
+    subject?: string,
   ): Promise<DeliverResult>;
 
   /**

package/src/daemon.ts

@@ -345,6 +345,10 @@ export function contextFor(
           // 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;
       }
@@ -372,6 +376,10 @@ export function contextFor(
           // 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
@@ -830,11 +838,14 @@ export function buildWriteCallback(channels: Map<string, Channel>): WriteCallbac
  */
 export function buildReadSession(
   channels: Map<string, Channel>,
-): (channel: string, name: string) => Promise<string | undefined> {
-  return async (channel, name) => {
+): (channel: string, name: string, subject?: string) => Promise<string | undefined> {
+  return async (channel, name, subject) => {
     const ch = channels.get(channel);
     if (!ch?.transport.readThreadSession) return undefined;
-    return ch.transport.readThreadSession(channel, name);
+    // roles×threads NEXT slice (#120): pass the subject so a multi-threaded SUBJECT thread
+    // resumes its own subject-scoped note (`Threads/<ch>/<name>--<subject>`). Omitted → the
+    // deterministic def-named note (single-threaded resume, HEAD).
+    return ch.transport.readThreadSession(channel, name, subject);
   };
 }
 
@@ -848,11 +859,12 @@ export function buildReadSession(
  */
 export function buildClearSession(
   channels: Map<string, Channel>,
-): (channel: string, name: string) => Promise<void> {
-  return async (channel, name) => {
+): (channel: string, name: string, subject?: string) => Promise<void> {
+  return async (channel, name, subject) => {
     const ch = channels.get(channel);
     if (!ch?.transport.clearThreadSession) return;
-    await ch.transport.clearThreadSession(channel, name);
+    // roles×threads NEXT slice (#120): a subject clears its own subject-scoped note.
+    await ch.transport.clearThreadSession(channel, name, subject);
   };
 }
 
@@ -1068,6 +1080,15 @@ export async function reregisterProgrammaticAgents(
   }
   let count = 0;
   for (const name of entries) {
+    // PER-THREAD WORKSPACE GUARD (roles×threads NEXT slice #120, G). A subject thread's
+    // workspace dir is `<name>--<slug(subject)>` (the `--` separator). Those are PER-TURN
+    // scratch dirs for a multi-threaded agent's subject threads, NOT agent specs — they hold
+    // no authoritative spec.json (the spec is per-AGENT, persisted only at the name-only
+    // `<name>/` dir). Re-registering one would resurrect a phantom agent keyed on a
+    // subject-leaf name. So a dir name containing `--` is INERT on boot: skip it. The
+    // canonical per-agent spec dir (no `--`) is re-registered as before — byte-identical to
+    // HEAD for every current agent (no current agent's name contains `--`).
+    if (name.includes("--")) continue;
     const workspace = sessionWorkspace(sessionsDirPath, name);
     const spec = readPersistedSpec(workspace);
     // Re-register ONLY specs that explicitly persisted `backend: "programmatic"`.
@@ -1815,7 +1836,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);
@@ -3381,7 +3407,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/spawn-agent.ts

@@ -27,6 +27,7 @@ import { writeFileSync, mkdirSync, chmodSync, existsSync, readFileSync } from "n
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { AgentSpec, BaseBinds } from "./sandbox/types.ts";
+import { threadKey } from "./sandbox/types.ts";
 import { Sandbox, type SandboxEngine, type WrappedCommand } from "./sandbox/index.ts";
 import type { EgressBaseInput } from "./sandbox/egress.ts";
 import { DENYLISTED_ENV } from "./credentials.ts";
@@ -181,9 +182,18 @@ export interface SpawnAgentBaseDeps {
   ripgrep?: { command: string; args?: string[] };
 }
 
-/** Per-session workspace dir under the sessions base. */
-export function sessionWorkspace(sessionsDir: string, specName: string): string {
-  return join(sessionsDir, specName);
+/**
+ * Per-session workspace dir under the sessions base. The leaf is {@link threadKey}`(specName,
+ * subject)` (roles×threads NEXT slice, #120):
+ *  - NO subject → `<sessionsDir>/<specName>` — byte-identical to HEAD (every current agent,
+ *    incl. the weave, and the per-AGENT spec.json / persist callsites which never pass a subject).
+ *  - A subject → `<sessionsDir>/<specName>--<slug(subject)>` — a PER-THREAD private workspace
+ *    (its own `.mcp.json` / `system-prompt.txt` / HOME / staging), so concurrent subjects of one
+ *    multi-threaded agent never clobber each other's per-turn files. `slug` (inside threadKey)
+ *    strips the untrusted subject to a path-safe leaf — no traversal.
+ */
+export function sessionWorkspace(sessionsDir: string, specName: string, subject?: string): string {
+  return join(sessionsDir, threadKey(specName, subject));
 }
 
 /**

package/src/transport.ts

@@ -80,6 +80,15 @@ export interface ThreadRecord {
    * Omitted falls back to the channel (the 1:1 default, where channel == name).
    */
   name?: string;
+  /**
+   * The thread SUBJECT (roles×threads NEXT slice, #120). When present on a MULTI-threaded
+   * thread, the note becomes a DETERMINISTIC, upserting record at `threadKey(name, subject)`
+   * (`Threads/<safeChannel>/<safeName>--<safeSubject>`) — rolling turn_count + cumulative
+   * usage + a preserved session across fires (per-thread continuity), exactly like the
+   * single-threaded deterministic path but at the subject-scoped leaf. Absent/empty → the
+   * HEAD identity (single-threaded deterministic note / multi-threaded per-fire uuid note).
+   */
+  subject?: string;
   /** The `#agent/definition` note id this thread came from (provenance; plain id string). */
   definition?: string;
   /** The mode the turn ran under — governs thread identity + whether the note upserts. */
@@ -235,20 +244,23 @@ export interface Transport {
    */
   writeThread?(thread: ThreadRecord): Promise<{ sent: string[] }>;
   /**
-   * Optional: read the persisted Claude session UUID for a single-threaded agent's
-   * deterministic `#agent/thread` note (the thread≡session record), or undefined when
-   * none yet (the first turn). The daemon reads this BEFORE a turn so it can `--resume`
-   * the prior conversation. Only a durable transport (the VaultTransport) implements it;
-   * transports without a durable thread store (telegram) omit it.
+   * Optional: read the persisted Claude session UUID for a thread's deterministic
+   * `#agent/thread` note (the thread≡session record), or undefined when none yet (the
+   * first turn). The daemon reads this BEFORE a turn so it can `--resume` the prior
+   * conversation. `subject` (roles×threads NEXT slice, #120) resolves the SUBJECT-scoped
+   * note (`Threads/<ch>/<name>--<subject>`) for a multi-threaded subject thread; omitted →
+   * the def-named note (single-threaded resume, HEAD). Only a durable transport (the
+   * VaultTransport) implements it; transports without a durable thread store (telegram) omit it.
    */
-  readThreadSession?(channel: string, name: string): Promise<string | undefined>;
+  readThreadSession?(channel: string, name: string, subject?: string): Promise<string | undefined>;
   /**
-   * Optional: CLEAR the persisted session on a single-threaded agent's `#agent/thread`
-   * note so its next turn starts a fresh Claude conversation (the per-agent restart /
-   * reset). Only a durable transport (the VaultTransport) implements it; transports
-   * without a durable thread store (telegram) omit it.
+   * Optional: CLEAR the persisted session on a thread's `#agent/thread` note so its next
+   * turn starts a fresh Claude conversation (the per-agent restart / reset). `subject`
+   * resolves the subject-scoped note; omitted → the def-named note (HEAD). Only a durable
+   * transport (the VaultTransport) implements it; transports without a durable thread store
+   * (telegram) omit it.
    */
-  clearThreadSession?(channel: string, name: string): Promise<void>;
+  clearThreadSession?(channel: string, name: string, subject?: string): Promise<void>;
   /**
    * Optional: write an agent-to-agent CALLBACK as an INBOUND note on THIS channel (the
    * "reply_to" substrate). A recipient agent's drain, on turn completion, calls this on the

package/src/transports/vault.ts

@@ -66,6 +66,10 @@ import type {
   CallbackMetadata,
   InboundAttachment,
 } from "../transport.ts";
+// roles×threads NEXT slice (#120): the shared thread-key sanitizer — REUSED here for the
+// subject-scoped deterministic thread-note leaf (`<name>--<slug(subject)>`) so the path
+// math matches the registry's drain key exactly (no drift).
+import { threadKey } from "../sandbox/types.ts";
 
 /** The safe basename of a (possibly path-ful, possibly untrusted) string — the LAST
  *  path segment, with traversal markers stripped. Used to derive a display `filename`
@@ -161,6 +165,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 +185,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;
 }
 
 /**
@@ -808,20 +824,33 @@ export class VaultTransport implements Transport {
   }
 
   /**
-   * The DETERMINISTIC path of a single-threaded agent's ONE thread note —
-   * `Threads/<safeChannel>/<safeName>` (named after the def). The single shared
-   * source of truth for that path so {@link writeThread} (the upsert) and
-   * {@link readThreadSession} (the pre-turn session read) can never disagree on
-   * where the note lives. Sanitizes both segments to a flat, predictable slug.
+   * The DETERMINISTIC path of a thread note that UPSERTS in place —
+   * `Threads/<safeChannel>/<leaf>`. The single shared source of truth for that path so
+   * {@link writeThread} (the upsert), {@link readThreadSession} (the pre-turn session read),
+   * and {@link clearThreadSession} (the reset) can never disagree on where the note lives.
+   * Sanitizes the channel segment to a flat, predictable slug.
+   *
+   * The LEAF is {@link threadKey}`(name, subject)` (roles×threads NEXT slice, #120):
+   *  - NO subject → the bare def name (`<safeName>`) — the HEAD single-threaded path,
+   *    byte-identical. `threadKey` returns the bare name AND `slug`s it the same way the
+   *    prior inline `replace(/[^a-zA-Z0-9_-]/g, "-")` did, so the path is unchanged.
+   *  - A subject → `<safeName>--<safeSubject>` (the subject thread's deterministic note),
+   *    so a multi-threaded SUBJECT upserts + carries a session across fires.
    *
-   * COLLISION NOTE: two single-threaded agents whose names collapse to the SAME safeName
-   * on the same channel would share this note. Acceptable because the registry enforces
-   * ONE agent per channel (byChannel index), so the collision can't arise in practice.
+   * COLLISION NOTE: two agents whose (name, subject) collapse to the SAME leaf on the same
+   * channel would share this note. Acceptable: the registry enforces ONE agent per channel
+   * (byChannel index), and distinct subjects produce distinct leaves.
    */
-  private singleThreadedPath(channel: string, name: string): string {
+  private singleThreadedPath(channel: string, name: string, subject?: string): string {
     const safeChannel = channel.replace(/[^a-zA-Z0-9_-]/g, "-");
+    // Slug the NAME segment exactly as HEAD did (the prior inline `replace`), then let
+    // threadKey append `--<slug(subject)>` when a subject narrows the thread. With no
+    // subject threadKey returns the (already-slugged) name verbatim → the leaf is
+    // byte-identical to the HEAD single-threaded path. With a subject the leaf becomes
+    // `<safeName>--<safeSubject>` (both slugged → path-safe, no traversal).
     const safeName = (name ?? channel).replace(/[^a-zA-Z0-9_-]/g, "-");
-    return `${THREAD_PATH_PREFIX}/${safeChannel}/${safeName}`;
+    const leaf = threadKey(safeName, subject);
+    return `${THREAD_PATH_PREFIX}/${safeChannel}/${leaf}`;
   }
 
   /**
@@ -853,32 +882,36 @@ export class VaultTransport implements Transport {
   async writeThread(thread: ThreadRecord): Promise<{ sent: string[] }> {
     const safeChannel = thread.channel.replace(/[^a-zA-Z0-9_-]/g, "-");
     const singleThreaded = thread.mode === "single-threaded";
-
-    // IDENTITY by mode (HARD CONSTRAINT 3 — the path leaf IS the thread's identity; no
-    // ambiguous `thread_id` metadata field). single-threaded: a DETERMINISTIC leaf named
-    // after the def (the agent/spec name, sanitized) so the SAME note upserts across turns.
-    // multi-threaded: a fresh uuid per fire (one fire = one thread = one note today).
-    // COLLISION NOTE: two single-threaded agents whose names collapse to the SAME safeName
-    // on the same channel would upsert each other's thread note. Acceptable because the
-    // registry enforces ONE agent per channel (byChannel index), so the collision can't
-    // arise in practice.
-    // Multi-threaded leaf: a per-FIRE id. Reuse the caller's `threadId` when given (a
-    // re-record of the same turn — e.g. the outbound-failure status flip — targets the
-    // SAME per-fire note instead of minting a duplicate); else mint a fresh one. Single-
-    // threaded uses the DETERMINISTIC path (named after the def) so the one-per-channel
-    // note upserts — computed via {@link singleThreadedPath} so writeThread and
-    // readThreadSession agree on exactly where the note lives.
-    const path = singleThreaded
-      ? this.singleThreadedPath(thread.channel, thread.name ?? thread.channel)
+    // roles×threads NEXT slice (#120): a thread is DETERMINISTIC (a named, upserting note
+    // that rolls turn_count/usage + carries a session across fires) when it's single-threaded
+    // (HEAD) OR it's a multi-threaded thread that carries a SUBJECT. A subject-scoped
+    // multi-threaded thread turns "fresh note per fire" into "resume the named thread" — its
+    // leaf is `<name>--<subject>`. A multi-threaded thread with NO subject stays a per-fire
+    // uuid note (HEAD), byte-identical for the weave + every current agent.
+    const subject = thread.subject?.trim();
+    const deterministic = singleThreaded || (!singleThreaded && !!subject);
+
+    // IDENTITY (HARD CONSTRAINT 3 — the path leaf IS the thread's identity; no ambiguous
+    // `thread_id` metadata field). A DETERMINISTIC thread upserts at a stable leaf named after
+    // the def (+ subject when present), via {@link singleThreadedPath} so writeThread,
+    // readThreadSession + clearThreadSession all agree on exactly where the note lives. A
+    // non-deterministic (multi-threaded, no-subject) thread is a per-FIRE uuid note — reuse
+    // the caller's `threadId` when given (a re-record of the same turn — the outbound-failure
+    // status flip — targets the SAME per-fire note instead of minting a duplicate); else mint.
+    // COLLISION NOTE: two threads whose (name[, subject]) collapse to the SAME leaf on the
+    // same channel would upsert each other's note. Acceptable: the registry enforces ONE agent
+    // per channel (byChannel index), and distinct subjects produce distinct leaves.
+    const path = deterministic
+      ? this.singleThreadedPath(thread.channel, thread.name ?? thread.channel, subject)
       : `${THREAD_PATH_PREFIX}/${safeChannel}/${thread.threadId ?? crypto.randomUUID()}`;
 
-    // For single-threaded UPSERT, read the existing thread note (by its deterministic
-    // path) to roll up the aggregates. SAFE because the drain is serial per channel and
-    // single-threaded is one-thread-per-channel today (see the method doc) — there's no
-    // concurrent writer to lose an update against.
-    //   WHEN CONTINUATION brings concurrent threads per channel, switch to re-deriving
-    //   aggregates from the #agent/message children or a vault atomic-merge, to avoid
-    //   lost-update.
+    // For a DETERMINISTIC UPSERT (single-threaded OR a multi-threaded subject thread), read
+    // the existing thread note (by its deterministic path) to roll up the aggregates. SAFE
+    // because the drain is serial PER THREAD KEY (registry per-thread serial guarantee) — a
+    // given (name, subject) thread has no concurrent writer to lose an update against.
+    //   WHEN per-channel concurrency across DIFFERENT subjects lands they each have their OWN
+    //   deterministic note (distinct leaf), so no cross-subject lost-update; only same-subject
+    //   would race, and that's serialized by the per-thread drain.
     let priorTurnCount = 0;
     let priorInputTokens = 0;
     let priorOutputTokens = 0;
@@ -886,7 +919,7 @@ export class VaultTransport implements Transport {
     let priorStartedAt: string | undefined;
     let priorLastTurnAt: string | undefined;
     let priorSession: string | undefined;
-    if (singleThreaded) {
+    if (deterministic) {
       const prior = await this.readThreadNote(path);
       if (prior) {
         priorTurnCount = numFromMeta(prior.metadata?.turn_count);
@@ -920,8 +953,8 @@ export class VaultTransport implements Transport {
     const isStart = thread.phase === "start";
     let turnCount: number;
     if (isStart) {
-      turnCount = singleThreaded ? priorTurnCount : 0;
-    } else if (singleThreaded) {
+      turnCount = deterministic ? priorTurnCount : 0;
+    } else if (deterministic) {
       turnCount = thread.sameTurn ? priorTurnCount : priorTurnCount + 1;
     } else {
       turnCount = 1;
@@ -932,13 +965,13 @@ export class VaultTransport implements Transport {
     const startedAt = priorStartedAt ?? thread.started_at;
     const lastTurnAt = isStart ? (priorLastTurnAt ?? "") : thread.ended_at;
 
-    // Cumulative usage: single-threaded SUMS this turn into the prior totals; multi-threaded
-    // carries just this turn's (one fire = one thread).
+    // Cumulative usage: a DETERMINISTIC thread SUMS this turn into the prior totals; a
+    // per-fire (multi-threaded, no-subject) note carries just this turn's (one fire = one thread).
     const inputTokens =
-      (singleThreaded ? priorInputTokens : 0) + (thread.usage?.inputTokens ?? 0);
+      (deterministic ? priorInputTokens : 0) + (thread.usage?.inputTokens ?? 0);
     const outputTokens =
-      (singleThreaded ? priorOutputTokens : 0) + (thread.usage?.outputTokens ?? 0);
-    const costUsd = (singleThreaded ? priorCostUsd : 0) + (thread.usage?.totalCostUsd ?? 0);
+      (deterministic ? priorOutputTokens : 0) + (thread.usage?.outputTokens ?? 0);
+    const costUsd = (deterministic ? priorCostUsd : 0) + (thread.usage?.totalCostUsd ?? 0);
 
     // Indexed string fields (queryable) + the thread-state observability fields. The
     // vault stores metadata as strings; numbers are stringified.
@@ -957,14 +990,14 @@ export class VaultTransport implements Transport {
     if (thread.definition) metadata.definition = thread.definition;
     // The thread≡session record: persist the Claude session UUID onto the note so the
     // NEXT turn can `--resume` it. Prefer the session this write carries; else (a write
-    // with no session, e.g. a start-phase working-ensure) PRESERVE the prior single-
-    // threaded note's session so an upsert never drops continuity. Multi-threaded carries
-    // its own per-fire session each write (no preserve — each fire is a fresh thread).
-    const session = thread.session ?? (singleThreaded ? priorSession : undefined);
+    // with no session, e.g. a start-phase working-ensure) PRESERVE the prior DETERMINISTIC
+    // note's session so an upsert never drops continuity. A per-fire (no-subject multi)
+    // note carries its own per-fire session each write (no preserve — each fire is fresh).
+    const session = thread.session ?? (deterministic ? priorSession : undefined);
     if (session) metadata.session = session;
     // Usage is always present once a turn carried it OR we accumulated any — emit the
     // running totals so a query sees cumulative cost for the thread.
-    if (singleThreaded || thread.usage) {
+    if (deterministic || thread.usage) {
       if (inputTokens) metadata.input_tokens = String(inputTokens);
       if (outputTokens) metadata.output_tokens = String(outputTokens);
       // Round the accumulated cost to 9 decimals before serializing — summing floats
@@ -1076,19 +1109,22 @@ export class VaultTransport implements Transport {
     }
   }
 
-  /** The persisted Claude session UUID for a single-threaded agent's deterministic
-   *  thread note, or undefined if none yet (first turn). Read before a turn so the
-   *  daemon can --resume it. */
-  async readThreadSession(channel: string, name: string): Promise<string | undefined> {
-    const prior = await this.readThreadNote(this.singleThreadedPath(channel, name));
+  /** The persisted Claude session UUID for a thread's deterministic note, or undefined if
+   *  none yet (first turn). Read before a turn so the daemon can --resume it. `subject`
+   *  (roles×threads NEXT slice, #120) resolves the subject-scoped note
+   *  (`Threads/<ch>/<name>--<subject>`) for a multi-threaded subject thread; omitted → the
+   *  def-named note (HEAD). Uses {@link singleThreadedPath} so the path math matches writeThread. */
+  async readThreadSession(channel: string, name: string, subject?: string): Promise<string | undefined> {
+    const prior = await this.readThreadNote(this.singleThreadedPath(channel, name, subject));
     const s = prior?.metadata?.session;
     return typeof s === "string" && s ? s : undefined;
   }
 
-  /** Clear a single-threaded agent's persisted session so its next turn starts a
-   *  fresh Claude conversation (the per-agent restart). No-op if no thread note yet. */
-  async clearThreadSession(channel: string, name: string): Promise<void> {
-    const path = this.singleThreadedPath(channel, name);
+  /** Clear a thread's persisted session so its next turn starts a fresh Claude conversation
+   *  (the per-agent restart). `subject` resolves the subject-scoped note; omitted → the
+   *  def-named note (HEAD). No-op if no thread note yet. */
+  async clearThreadSession(channel: string, name: string, subject?: string): Promise<void> {
+    const path = this.singleThreadedPath(channel, name, subject);
     const url = `${this.vaultUrl}/vault/${this.vault}/api/notes/${encodeURIComponent(path)}`;
     const res = await fetch(url, {
       method: "PATCH",
@@ -1319,8 +1355,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);
   }
 
   /**
@@ -1579,6 +1628,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;
@@ -1600,6 +1653,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, "-");
@@ -1615,6 +1670,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",
@@ -1772,9 +1832,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);
     }
 
@@ -1789,6 +1853,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`.
@@ -1803,6 +1879,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 } : {}),