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

package/package.json

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

@@ -443,13 +443,19 @@ export class ProgrammaticBackend implements AgentBackend {
     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.

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;
 }
 
@@ -437,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
@@ -480,14 +504,18 @@ 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
@@ -507,10 +535,17 @@ 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.
@@ -552,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);
@@ -584,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
@@ -617,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);
     }
@@ -740,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
@@ -804,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;
   }
@@ -833,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.
@@ -860,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 }
@@ -897,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
@@ -953,6 +1083,11 @@ export class ProgrammaticAgentRegistry {
           // 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
@@ -1245,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

@@ -252,6 +252,14 @@ export interface AgentBackend {
    * 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,
@@ -261,6 +269,7 @@ export interface AgentBackend {
     attachments?: InboundAttachment[],
     runContext?: RunContext,
     subjectDossier?: string,
+    subject?: string,
   ): Promise<DeliverResult>;
 
   /**

package/src/daemon.ts

@@ -838,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);
   };
 }
 
@@ -856,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);
   };
 }
 
@@ -1076,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"`.

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`
@@ -820,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.
    *
-   * 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.
+   * 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 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}`;
   }
 
   /**
@@ -865,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;
@@ -898,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);
@@ -932,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;
@@ -944,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.
@@ -969,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
@@ -1088,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",