@volter/supercode-teams 0.3.86 → 0.3.87

package/live-sessions.mjs

@@ -416,6 +416,22 @@ export class LiveSessions extends EventEmitter {
     return null;
   }
 
+  /**
+   * The live-runtime receipt named `receiptId`, read from its own file (`<live-runtimes>/<receiptId>.json`) and taken
+   * into the map: a runtime whose receipt the watch has not delivered yet (its event late or lost) is read by name, never
+   * waited on or listed for.
+   */
+  receiptNamed(receiptId) {
+    if (typeof receiptId !== 'string' || !/^[0-9a-f]+$/i.test(receiptId)) return null;
+    const receipt = readReceiptFile(join(this.receiptsDir, `${receiptId}.json`));
+    if (!receipt || receipt.receipt_id !== receiptId || typeof receipt.source?.harness !== 'string' || typeof receipt.source?.session_id !== 'string') return null;
+    if (!this.runtimes.has(receiptId)) {
+      this.runtimes.set(receiptId, { pid: receipt.pid, harness: receipt.source.harness, sessionId: receipt.source.session_id, runtimeSessionId: typeof receipt.runtime_session_id === 'string' ? receipt.runtime_session_id : null, cwd: typeof receipt.source.workspace === 'string' ? receipt.source.workspace : null });
+      this.#changed();
+    }
+    return receipt;
+  }
+
   /** A session the index holds that is not live: mail to it is stored until it is next active, never refused. */
   isIndexedNotLive(address) {
     const [, machine, harness, sessionId] = String(address).split(':');

package/machine.mjs

@@ -39,6 +39,7 @@ import { MailReads, panePrompt } from './mail/reads.mjs';
 import { Agents } from './mail/agents.mjs';
 import { Relays } from './mail/relay.mjs';
 import { MailSend } from './mail/send.mjs';
+import { AgentVerbs } from './mail/verbs.mjs';
 import { deliverToRuntime } from './mail/runtime.mjs';
 import { envelope as envelopeOf, linkOf, parseAddress, senderIdentity } from './mail/compose.mjs';
 import { codexQuestions } from './native-questions.mjs';
@@ -148,6 +149,19 @@ const LAUNCH_SETTLE_MS = 500;
 /** How long a send to another machine waits for its mail door's answer (its receiver's door there: a relay's receipt
  *  alone may take 90 s). An answer that does not come is unanswered, never refused or failed. */
 const MAIL_SEND_MS = 120_000;
+/**
+ * The doors whose work waits on a session, with the bound each answers within (the node door's own is 30 s): a send or
+ * a hand-over waits on its receiver's door (a relay's receipt, up to 90 s; another machine's door, MAIL_SEND_MS), a
+ * delegation or a declaration that starts a session waits for it to appear (up to a minute). Past its bound a call is
+ * answered 504, which its client reads as unanswered: the work may still finish.
+ */
+const DOOR_BOUNDS_MS = {
+  'harness.v1.mail.send': 170_000,
+  'harness.v1.mail.message': 170_000,
+  'harness.v1.mail.handover': 140_000,
+  'harness.v1.mail.delegate': 110_000,
+  'harness.v1.agent.declare': 110_000,
+};
 /** How many typed lines' keys a machine remembers; a server retries a line for minutes, not thousands of lines. */
 const TURN_KEYS_KEPT = 1000;
 /** How long a typed line's door gets to confirm it: a loaded machine's reader types it in seconds and answers late. */
@@ -628,11 +642,14 @@ export class TeamsMachine extends MachineCore {
       discover: (params) => this.#serveRequest('harness.v1.sessions.discover', params, 10_000),
       recordedConfig: (locator) => this.#serveRequest('harness.v1.sessions.recorded_config', { locator }, 15_000) });
     this.relays = new Relays({ mailRoot, machine, supercodeBin: this.supercodeBin, serve: (method, params, timeoutMs) => this.#serveRequest(method, params, timeoutMs),
-      runtimeOf: (harness, id) => live.runtimeReceipt(harness, id) });
+      runtimeOf: (harness, id) => live.runtimeReceipt(harness, id), runtimeNamed: (receiptId) => live.receiptNamed(receiptId) });
     this.mailSend = new MailSend({ machine, mailRoot, live, store: this.mailStore, agents: this.agents, relays: this.relays,
       // a send waits on its receiver's door there (a relay's receipt takes up to 90 s), never past MAIL_SEND_MS
       askMachine: (to, request) => this.#askMailDoor(to, request, MAIL_SEND_MS),
       deliverRuntime: deliverToRuntime, codexAnswer: (request) => codexQuestions(request) });
+    // an agent's verbs (3b-2): its threads, a delegation, its record
+    this.agentVerbs = new AgentVerbs({ machine, store: this.mailStore, agents: this.agents, live, supercodeBin: this.supercodeBin, env: this.env,
+      paneOf: (session) => this.mail.paneOf(session), mailRoot });
     // the names sessions ran under (`<mail>/names.json`): a name an agent was given reaches the same session after it
     // runs under another, kept from the map's changes (at most once a second)
     let naming = null;
@@ -2470,8 +2487,10 @@ export class TeamsMachine extends MachineCore {
         const reply = (envelope) => { if (stream.closed) return; try { stream.write(JSON.stringify(envelope) + '\n'); } catch { /* peer gone */ } };
         try {
           // Every door answers or fails within a bound; a hung substrate call becomes an error, never silence.
-          // The caller may shorten the bound, never lengthen it past the daemon's own 30 s.
-          const bound = Math.min(Number(request.params?.timeoutMs) || 30_000, 30_000);
+          // The caller may shorten the bound, never lengthen it past the daemon's own: 30 s, or the longer one a door
+          // that waits on a session states (DOOR_BOUNDS_MS), each above its own inner waits.
+          const own = DOOR_BOUNDS_MS[request.method] ?? 30_000;
+          const bound = Math.min(Number(request.params?.timeoutMs) || own, own);
           const result = await withTimeout(this.#dispatch(entry, request.method, request.params ?? {}), bound, request.method);
           reply({ id: request.id, result });
           this.emit('door', { method: request.method, ms: Date.now() - startedAt, outcome: 'ok' });
@@ -3242,6 +3261,33 @@ export class TeamsMachine extends MachineCore {
         act('mail.send', to, answer.code === 0 ? 'ok' : 'failed');
         return answer;
       }
+      // An agent's verbs (docs/architecture/overview.md, 3b-2): `message thread`, `threads`, `delegate`, and `supercode
+      // agent declare|show`, this machine's own processes only; a delegation and a thread list without --agent are the
+      // caller's, as its claim names it.
+      case 'harness.v1.mail.thread': case 'harness.v1.mail.threads': case 'harness.v1.mail.delegate': case 'harness.v1.agent.declare': case 'harness.v1.agent.show': {
+        if (entry.principal !== 'local' || entry.appDoor) throw Object.assign(new Error('an agent\'s verbs are answered here for this machine\'s own processes'), { code: 403 });
+        const text = (key) => (typeof params[key] === 'string' && params[key] ? params[key] : null);
+        if (method === 'harness.v1.mail.thread') {
+          if (!text('id')) throw Object.assign(new Error('thread names a message id'), { code: 400 });
+          return this.agentVerbs.thread(text('id'));
+        }
+        if (method === 'harness.v1.agent.show') return this.agentVerbs.show(text('name'));
+        if (method === 'harness.v1.agent.declare') {
+          if (!text('name')) throw Object.assign(new Error('declare names its agent'), { code: 400 });
+          const answer = await this.agentVerbs.declare({ name: text('name'), main: text('main'), open: text('open'), input: text('input'), folder: text('folder'), harness: text('harness'),
+            idle_minutes: Number.isInteger(params.idle_minutes) && params.idle_minutes >= 0 ? params.idle_minutes : null, owners_account_manager: params.owners_account_manager === true });
+          act('agent.declare', text('name'), answer.code === 0 ? 'ok' : 'failed');
+          return answer;
+        }
+        let caller = null;
+        try { caller = await this.#callerOf(entry, params); } catch (error) { if (method === 'harness.v1.mail.delegate') throw error; }
+        if (method === 'harness.v1.mail.threads') return this.agentVerbs.threads(text('agent'), typeof caller === 'string' ? caller : null);
+        if (typeof caller !== 'string' || !caller) return { code: 2, text: "Can't tell which session is running this command, so replies would have nowhere to go. Nothing was sent. Run it from your agent session's own shell tool." };
+        if (!text('root')) throw Object.assign(new Error('delegate names its root'), { code: 400 });
+        const answer = await this.agentVerbs.delegate(caller, text('root'), { folder: text('folder'), harness: text('harness') });
+        act('mail.delegate', caller, answer.code === 0 ? 'ok' : 'failed');
+        return answer;
+      }
       // A filed message handed to its session's door (the native watch's carrier and a relay's `message push`, until
       // step 4): once, by its id, recorded on its wake.
       case 'harness.v1.mail.handover': {

package/mail/agents.mjs

@@ -8,7 +8,7 @@ import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync,
 import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 import { blake3Hex } from './envelope.mjs';
-import { cameThroughLink, parseAddress } from './compose.mjs';
+import { cameThroughLink, parseAddress, threadOf } from './compose.mjs';
 
 /** The pseudo-harness of an agent address. */
 export const AGENT_HARNESS = 'agent';
@@ -64,10 +64,18 @@ export class Agents {
 
   /** Every thread, oldest first. */
   threads() {
+    // Read once and kept while the folder is unchanged: every writer (this daemon, and mail_agent.rs's in the native
+    // watch until step 4) renames a whole record into it, which moves the folder's time. One stat a call, not a read of
+    // every record: a send's plan asks this on every send, and an agent's threads grow with its history.
+    let changed;
+    try { changed = statSync(this.threadsDir).mtimeMs; } catch { return []; }
+    if (this.threadsCache?.changed === changed) return this.threadsCache.list.map((thread) => structuredClone(thread));
     let names = [];
     try { names = readdirSync(this.threadsDir); } catch { return []; }
-    return names.filter((name) => name.endsWith('.json')).map((name) => readJson(join(this.threadsDir, name))).filter((thread) => thread?.id)
+    const list = names.filter((name) => name.endsWith('.json')).map((name) => readJson(join(this.threadsDir, name))).filter((thread) => thread?.id)
       .sort((a, b) => (a.created_at_ms - b.created_at_ms) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    this.threadsCache = { changed, list };
+    return list.map((thread) => structuredClone(thread));
   }
 
   /** The thread `address` holds for an agent other than as its main session (mail_agent.rs `thread_held_by`). */
@@ -135,6 +143,63 @@ export class Agents {
     }
   }
 
+  /** Record `agent`, replacing an earlier record of the same name (mail_agent.rs `declare`): its fields in its order, an
+   *  empty optional left out. */
+  declare(agent) {
+    if (!validName(agent.name)) throw new Error(`\`${agent.name}\` is not an agent name: use letters, digits, \`-\`, \`_\` and \`.\``);
+    const out = { name: agent.name, main_session: agent.main_session };
+    if (agent.folder != null) out.folder = agent.folder;
+    if (agent.harness != null) out.harness = agent.harness;
+    if (agent.idle_minutes != null) out.idle_minutes = agent.idle_minutes;
+    writeAtomically(join(this.agentsDir, `${agent.name}.json`), JSON.stringify(out, null, 2));
+  }
+
+  /** Name `name` the owner's account manager: every line the owner writes to any agent is CC'd to its main session. */
+  setOwnersAccountManager(name) { writeAtomically(join(this.agentsDir, 'owners-account-manager'), `${name}\n`); }
+
+  /** The owner's account manager, when one is named and declared. */
+  ownersAccountManager() {
+    try { return this.load(readFileSync(join(this.agentsDir, 'owners-account-manager'), 'utf8').trim()); } catch { return null; }
+  }
+
+  /** The threads of the agent `name`, oldest first. */
+  threadsOf(name) { return this.threads().filter((thread) => thread.agent === name); }
+
+  /**
+   * A line that reached an agent's main session through its own input (its terminal, its DM) is a root of the agent:
+   * its thread, held by main, with its sender, opened when main first acts on it (mail_agent.rs `root_of_main`). Null
+   * when `main` is no agent's main session or the line is main's own.
+   */
+  async rootOfMain(main, envelope) {
+    const agent = this.agentOfSession(main);
+    if (!agent || agent.main_session !== main) return null;
+    if (envelope.from === main || threadOf(envelope) !== envelope.id) return null;
+    const participants = [{ address: main, role: 'to' }, ...(cameThroughLink(envelope) ? [] : [{ address: envelope.from, role: 'to' }])];
+    return this.update(envelope.id, () => ({ id: envelope.id, agent: agent.name, holder: main, participants, markers: {}, surface: null, created_at_ms: Date.now(), holder_launched: false, parent: null }), () => {});
+  }
+
+  /** Hand the thread `id` to `holder`: it becomes its `to`, and main `cc`; `launched` says the mailbox started the holder
+   *  itself (mail_agent.rs `delegate_to`). Handed back to main, a launched holder leaves the thread. */
+  async delegateTo(id, holder, launched) {
+    const current = this.thread(id);
+    const agent = current ? this.load(current.agent) : null;
+    if (!current || !agent) return null;
+    const join_ = (thread, address, role) => {
+      const found = thread.participants.find((p) => p.address === address);
+      if (found) found.role = role; else thread.participants.push({ address, role });
+    };
+    return this.update(id, () => null, (thread) => {
+      if (holder === agent.main_session && thread.holder_launched && thread.holder !== holder) {
+        const previous = thread.holder;
+        thread.participants = thread.participants.filter((p) => p.address !== previous);
+      }
+      thread.holder = holder;
+      thread.holder_launched = launched && holder !== agent.main_session;
+      join_(thread, holder, 'to');
+      if (holder !== agent.main_session) join_(thread, agent.main_session, 'cc');
+    });
+  }
+
   // ---- who receives one message ----------------------------------------------------------------------------------
 
   /**

package/mail/reads.mjs

@@ -136,6 +136,9 @@ export class MailReads {
     return prompt ? { prompt, source: 'screen' } : null;
   }
 
+  /** The daemon pane a live session runs in, or null. */
+  paneOf(session) { return this.#paneOf(session); }
+
   #paneOf(session) {
     const pane = typeof session.pane === 'string' ? session.pane.split(':')[0] : null;
     return pane && isDaemonPane(pane) ? pane : null;

package/mail/relay.mjs

@@ -18,8 +18,6 @@ const RELAY_MODEL = 'haiku';
 export const RELAY_NAME_PREFIX = 'sc-';
 /** How long a send waits for Claude's own receipt. */
 const SEND_TIMEOUT_MS = 90_000;
-/** How long a relay's new runtime may take to show in the live-session map. */
-const RECEIPT_WAIT_MS = 10_000;
 /** Largest message relayed into a Claude session: the relay copies it into a model turn byte for byte. */
 export const MAX_RELAYED_BYTES = 100_000;
 
@@ -55,10 +53,11 @@ export function readReceipt(value) {
 export class Relays {
   /**
    * `serve(method, params, timeoutMs)` is one `harness.v1` request to this daemon's harness serve; `runtimeOf(harness,
-   * id)` the live-runtime receipt the live-session map holds for a runtime id (its file read whole), or null.
+   * id)` the live-runtime receipt the live-session map holds for a runtime id (its file read whole), or null;
+   * `runtimeNamed(receiptId)` one receipt read by its own name.
    */
-  constructor({ mailRoot, machine, supercodeBin, serve, runtimeOf }) {
-    Object.assign(this, { mailRoot, machine, supercodeBin, serve, runtimeOf });
+  constructor({ mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed = () => null }) {
+    Object.assign(this, { mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed });
     this.sending = new Map(); // relay folder → the send in progress through it (one at a time per relay)
   }
 
@@ -141,15 +140,18 @@ export class Relays {
     const connection = typeof started.connection === 'string' ? started.connection : '';
     const pid = Number.isInteger(started?.handle?.endpoint?.pid) ? started.handle.endpoint.pid : null;
     writeFileSync(spec.record, JSON.stringify({ runtime_id: runtimeId, pid, endpoint, connection }));
-    // its receipt reaches the live-session map from the map's watch of the receipts folder, a moment after harness serve
-    // writes it: waited on (10 s at most), never taken as absent at once
-    const deadline = Date.now() + RECEIPT_WAIT_MS;
-    for (;;) {
-      const runtime = this.runtimeOf('claude-code', runtimeId);
-      if (runtime) return { runtime, connection };
-      if (Date.now() > deadline) throw new Error(`the relay started but registered no live runtime within ${RECEIPT_WAIT_MS / 1000} s`);
-      await new Promise((resolve) => setTimeout(resolve, 50));
-    }
+    // harness serve writes its receipt before it answers the start; the map learns it from its watch a moment later, so
+    // one it does not hold yet is read by its own name (the receipt the runtime's terminal launch opens), never waited on
+    const known = this.runtimeOf('claude-code', runtimeId);
+    if (known) return { runtime: known, connection };
+    let receiptId = null;
+    try {
+      const launch = (await this.serve('harness.v1.runtimes.terminal_instructions', { connection }, 5000))?.launch;
+      receiptId = (Array.isArray(launch?.arguments) ? launch.arguments : []).find((arg) => typeof arg === 'string' && arg.startsWith('supercode-live://'))?.slice('supercode-live://'.length) ?? null;
+    } catch { /* said below */ }
+    const runtime = receiptId ? this.runtimeNamed(receiptId) : null;
+    if (!runtime) throw new Error('the relay started but registered no live runtime');
+    return { runtime, connection };
   }
 
   /** Claude's receipt for the queued send, waited on by a watch of the relay's folder (and its process checked at least

package/mail/send.mjs

@@ -55,7 +55,26 @@ export class MailSend {
    * unique here): through Teams when `to` is on another machine, else through its door here. `link` is the link a request
    * came through (`{ principal, name }`), or null for this machine's own callers. Answers `{ code, text, receipt }`.
    */
-  async send(caller, to, body, { subject = null, in_reply_to = null, notify_when_idle = false, queue = false, id = null, notice = false, thread = null, message_id = null } = {}, { link = null } = {}) {
+  async send(caller, to, body, options = {}, context = {}) {
+    // A send under an --id is held while it runs: the sent marker is written only once it is done, so a second send
+    // under the same key meanwhile waits for the first and takes its outcome (sent once), never delivering it again; one
+    // after a first that was not sent sends.
+    const key = typeof options.id === 'string' ? `${caller.address}\0${options.id}` : null;
+    if (key) {
+      const running = (this.inFlight ??= new Map()).get(key);
+      if (running) {
+        const first = await running.catch(() => null);
+        if (first?.code === 0) return outcome(0, `Already sent with --id ${options.id}: ${first.text} Nothing was sent again.`, first.receipt ?? null);
+        return this.send(caller, to, body, options, context);
+      }
+    }
+    const sending = this.#send(caller, to, body, options, context);
+    if (!key) return sending;
+    this.inFlight.set(key, sending);
+    try { return await sending; } finally { if (this.inFlight.get(key) === sending) this.inFlight.delete(key); }
+  }
+
+  async #send(caller, to, body, { subject = null, in_reply_to = null, notify_when_idle = false, queue = false, id = null, notice = false, thread = null, message_id = null } = {}, { link = null } = {}) {
     // an id its client chose (so a lost answer can name it), never an idempotency key: it marks nothing sent
     const chosen = typeof message_id === 'string' && /^m-[0-9a-f]{24}$/.test(message_id) ? message_id : null;
     const machine = this.#remoteMachine(to);

package/mail/store.mjs

@@ -122,7 +122,10 @@ export class MailStore extends EventEmitter {
     let envelope = null; try { envelope = JSON.parse(text); } catch { /* unreadable */ }
     // an unreadable file is skipped, never fatal, and said: a mailbox that skipped one is partial
     if (!envelope || typeof envelope.id !== 'string') { box.skipped.add(`${part}/${file}`); return; }
-    box.files.set(`${part}/${file}`, { header: headerOf(envelope), state: STATES[part], path, part });
+    // its body's first line is kept beside the header (never in it): a listing of threads names each root by it with no
+    // body read
+    const firstLine = typeof envelope.body === 'string' ? envelope.body.slice(0, 400).split('\n')[0] : '';
+    box.files.set(`${part}/${file}`, { header: headerOf(envelope), state: STATES[part], path, part, firstLine });
   }
 
   // ---- what it holds --------------------------------------------------------------------------------------------
@@ -161,6 +164,19 @@ export class MailStore extends EventEmitter {
     return found;
   }
 
+  /** The first line of each message whose id is in `ids`, from the index in one pass (no file read): id → line. */
+  firstLines(ids) {
+    const wanted = new Set(ids);
+    const lines = new Map();
+    if (!wanted.size) return lines;
+    for (const box of this.boxes.values()) {
+      for (const entry of box.files.values()) {
+        if (wanted.has(entry.header.id) && !lines.has(entry.header.id)) lines.set(entry.header.id, entry.firstLine ?? '');
+      }
+    }
+    return lines;
+  }
+
   // ---- writes, as mailbox.rs makes them --------------------------------------------------------------------------
 
   /** The unread mail of `address` (not the user's own turns) moved into `claimed/` under its reader's pid (`pid`, the

package/mail/verbs.mjs

@@ -0,0 +1,232 @@
+// An agent's verbs (docs/architecture/overview.md, "The mail operations", 3b-2): reading a conversation (`message
+// thread`), listing an agent's threads (`message threads`), handing a root to a new session of the agent (`message
+// delegate`), and declaring or showing an agent (`supercode agent declare|show`), answered by the daemon as
+// crates/cli/src/message.rs answered them, their texts kept. Each read answers from the header index; a body is read from
+// its one file when its message is shown.
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { listed, messageRow, rfc3339, shortId } from './envelope.mjs';
+import { makeAddress, parseAddress, threadOf } from './compose.mjs';
+
+export const EXIT_REFUSED = 2;
+export const EXIT_UNKNOWN = 3;
+export const EXIT_FAILED = 5;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class AgentVerbs {
+  /** `machine` this machine's name; `store` the mail store; `agents` an agent's records; `live` the live-session map;
+   *  `supercodeBin` the native binary (`supercode open` starts a session in a pane); `paneOf(session)` the daemon pane a
+   *  live session runs in; `mailRoot` the mail folder. */
+  constructor({ machine, store, agents, live, supercodeBin, env = process.env, paneOf, mailRoot }) {
+    Object.assign(this, { machine, store, agents, live, supercodeBin, env, paneOf, mailRoot });
+  }
+
+  #whole(stored) { const envelope = this.store.body(stored); return envelope ? { ...stored, envelope } : null; }
+
+  // ---- message thread -------------------------------------------------------------------------------------------
+
+  /**
+   * The conversation a message belongs to, oldest first (message.rs `thread`): every message here is a node, a reply's
+   * `in_reply_to` its edge to what it answers, and a stored thread id joins a message whose parent is not filed here.
+   * Answers `{ code, rows, rendered }` or `{ code, text }`.
+   */
+  thread(id) {
+    const all = new Map(); // id → { address, stored }
+    for (const address of this.store.addresses()) {
+      for (const stored of this.store.inventory(address).stored) if (!all.has(stored.envelope.id)) all.set(stored.envelope.id, { address, stored });
+    }
+    const matches = [...all.keys()].filter((key) => key.startsWith(id));
+    if (matches.length !== 1) return { code: EXIT_UNKNOWN, text: `${id} names ${matches.length} messages here; give one message's id.` };
+    // up to the root: the oldest ancestor filed here
+    let root = matches[0];
+    const seen = new Set();
+    for (;;) {
+      const parent = all.get(root)?.stored.envelope.in_reply_to;
+      if (!parent || !all.has(parent) || seen.has(parent)) break;
+      seen.add(parent); root = parent;
+    }
+    const threadOfRoot = threadOf(all.get(root).stored.envelope);
+    // down from the root: every reply, and every message naming the same thread
+    const children = new Map();
+    for (const [key, { stored }] of all) {
+      const parent = stored.envelope.in_reply_to;
+      if (parent) children.set(parent, [...(children.get(parent) ?? []), key]);
+    }
+    const members = new Set();
+    const queue = [root, ...[...all].filter(([, { stored }]) => stored.envelope.thread === threadOfRoot).map(([key]) => key)];
+    while (queue.length) {
+      const next = queue.pop();
+      if (members.has(next)) continue;
+      members.add(next);
+      queue.push(...(children.get(next) ?? []));
+    }
+    const conversation = [...members].map((key) => all.get(key)).map(({ address, stored }) => ({ address, stored: this.#whole(stored) })).filter((item) => item.stored)
+      .sort((a, b) => a.stored.envelope.created_at_ms - b.stored.envelope.created_at_ms);
+    const deliveries = new Map();
+    return {
+      code: 0,
+      rows: conversation.map(({ address, stored }) => messageRow(address, stored, deliveries, this.mailRoot)),
+      rendered: conversation.map(({ address, stored }) => `To ${address}:\n${listed(stored.envelope, deliveries, this.mailRoot)}\n`),
+    };
+  }
+
+  // ---- message threads ------------------------------------------------------------------------------------------
+
+  /** An agent's threads, oldest first (message.rs `threads`): the agent named, else the caller's own agent. */
+  threads(agent, caller) {
+    let name = agent;
+    if (!name) {
+      name = caller ? this.agents.agentOfSession(caller)?.name : null;
+      if (!name) return { code: EXIT_REFUSED, text: 'Name the agent with --agent: this session is not one of an agent\'s.' };
+    }
+    const threads = this.agents.threadsOf(name);
+    // every root's first line from the index in one pass: no walk of the index per thread, no body read
+    const roots = this.store.firstLines(threads.map((thread) => thread.id));
+    const rows = threads.map((thread) => ({
+      id: thread.id, holder: thread.holder,
+      participants: thread.participants.map((p) => ({ address: p.address, role: p.role })),
+      surface: thread.surface ?? null, opened_at: rfc3339(thread.created_at_ms),
+      root: roots.has(thread.id) ? roots.get(thread.id) : null,
+    }));
+    const text = rows.length
+      ? rows.map((row) => `${shortId(row.id)}  opened ${row.opened_at}  held by ${row.holder}\n  ${row.participants.map((p) => `${p.address} (${p.role})`).join(', ')}\n  ${row.root ?? '(no root message)'}`).join('\n')
+      : `Agent ${name} has no threads.`;
+    return { code: 0, rows, text };
+  }
+
+  // ---- a new session of an agent ----------------------------------------------------------------------------------
+
+  /**
+   * Start `program` in a new pane in `directory`, typed `input` once ready, and answer the session it runs (message.rs
+   * `open_session`): a Claude session is given its id up front, so `ready(address)` runs before it starts; another is
+   * found in the live-session map by the pane it opened in, within a minute.
+   */
+  async openSession(program, directory, key, input, ready) {
+    const stem = String(program).split(/[\\/]/).pop().replace(/\.[^.]*$/, '');
+    const claude = stem === 'claude' || stem === 'claude-code';
+    let known = null;
+    const extra = [];
+    if (claude) {
+      const bytes = randomBytes(16);
+      bytes[6] = (bytes[6] & 0x0f) | 0x40; bytes[8] = (bytes[8] & 0x3f) | 0x80;
+      const hex = bytes.toString('hex');
+      const id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+      known = makeAddress(this.machine, 'claude-code', id);
+      extra.push('--', '--session-id', id);
+      await ready(known);
+    }
+    const run = await new Promise((resolve) => {
+      const child = spawn(this.supercodeBin, ['--cwd', directory, 'open', '--new', program, '--key', key, '--input', input, '--detach', ...extra], { stdio: ['ignore', 'pipe', 'pipe'], env: this.env });
+      let out = '', err = '';
+      child.stdout.on('data', (chunk) => { out += chunk; });
+      child.stderr.on('data', (chunk) => { err += chunk; });
+      child.on('error', (error) => resolve({ code: 1, out, err: error.message }));
+      child.on('close', (code) => resolve({ code, out, err }));
+    });
+    if (run.code !== 0) throw new Error(`the session did not start: ${run.err.trim()}`);
+    if (known) return known;
+    let pane = null;
+    try { pane = JSON.parse(run.out).pane; } catch { /* not reported */ }
+    if (typeof pane !== 'string') throw new Error('the new pane was not reported');
+    const started = Date.now();
+    while (Date.now() - started < 60_000) {
+      const session = this.live.sessions().find((row) => this.paneOf(row) === pane);
+      if (session) { await ready(session.address); return session.address; }
+      await sleep(500);
+    }
+    throw new Error(`${program} started in pane ${pane}, but no session appeared there within a minute`);
+  }
+
+  /**
+   * Hand a root the caller received as an agent's main session to a new session of the agent (message.rs `delegate`):
+   * it opens in a pane with the root, holds the thread (every reply wakes it), and main stays CC. Answers `{ code, text }`.
+   */
+  async delegate(caller, root, { folder = null, harness = null } = {}) {
+    const found = this.store.findPrefixIn(caller, root);
+    if (found.length !== 1) return { code: EXIT_REFUSED, text: `Not delegated: ${root} names ${found.length} messages in your mailbox. Name the root as your inbox shows it.` };
+    const stored = found[0].envelope;
+    const threadId = threadOf(stored);
+    // a line in main's own session (its terminal, its DM) is a root of the agent: main opens its thread to delegate it
+    const thread = this.agents.thread(threadId) ?? await this.agents.rootOfMain(caller, stored);
+    if (!thread) return { code: EXIT_REFUSED, text: `Not delegated: ${shortId(stored.id)} is not in a thread of an agent. Only a root an agent received can be delegated.` };
+    const agent = this.agents.load(thread.agent);
+    if (!agent) return { code: EXIT_REFUSED, text: `Not delegated: agent ${thread.agent} is no longer declared.` };
+    if (agent.main_session !== caller || thread.holder !== caller) return { code: EXIT_REFUSED, text: `Not delegated: only ${agent.name}'s main session delegates a thread it holds.` };
+    const program = harness ?? agent.harness ?? 'claude';
+    const directory = folder ?? agent.folder ?? null;
+    if (!directory) return { code: EXIT_FAILED, text: 'Not delegated: no directory to start the session in (give --folder, or declare the agent with one).' };
+    const shownRoot = shortId(thread.id);
+    const input = `You are a session of agent ${agent.name}, holding its thread ${shownRoot}. Read it: supercode message thread ${shownRoot}. Answer in it with supercode message reply <id>; what you send stays in this thread, and ${agent.name}'s main session is CC on it.`;
+    // the new session holds the thread and has its messages before it starts, so its first turn finds its root
+    const handOver = async (holder) => {
+      for (const line of this.store.inventory(caller).stored) {
+        if (threadOf(line.envelope) !== thread.id) continue;
+        const whole = this.#whole(line);
+        if (!whole) continue;
+        // a line typed into main's terminal reaches the holder as one typed in another session (`typed`, ADR 0008)
+        const envelope = whole.envelope.kind === 'user' ? { ...whole.envelope, kind: 'typed' } : whole.envelope;
+        this.store.deliverRead(holder, envelope);
+      }
+      await this.agents.delegateTo(thread.id, holder, true);
+    };
+    let holder;
+    try { holder = await this.openSession(program, directory, `delegate:${thread.id}`, input, handOver); }
+    catch (error) {
+      // the thread goes back to main, so nothing waits on a session that never started
+      await this.agents.delegateTo(thread.id, caller, false);
+      return { code: EXIT_FAILED, text: `Not delegated: ${error.message}` };
+    }
+    const sessionId = parseAddress(holder).session;
+    return { code: 0, text: `Delegated thread ${shownRoot} to a new session of ${agent.name} (${holder}) in ${directory}. You are CC on it. Continue there: supercode open ${sessionId}` };
+  }
+
+  // ---- supercode agent declare | show ---------------------------------------------------------------------------
+
+  /** Declare an agent, or replace its record (message.rs `run_agent` Declare): its main session an address, a name
+   *  running here, or one started (`open`) when the declared main is neither running nor resumable. */
+  async declare({ name, main = null, open = null, input = null, folder = null, harness = null, idle_minutes = null, owners_account_manager = false }) {
+    const directory = folder ? (() => { try { return realpathSync(folder); } catch { return null; } })() : null;
+    if (folder && !directory) return { code: 1, text: `${folder}: no such directory` };
+    let mainSession = main;
+    if (!mainSession) {
+      if (!open) return { code: EXIT_REFUSED, text: 'Name its main session with --main, or start one with --open.' };
+      const kept = this.agents.load(name)?.main_session ?? null;
+      const live = kept && this.live.sessions().some((row) => row.address === kept);
+      if (kept && (live || await this.agents.resumable(kept))) mainSession = kept;
+      else {
+        const first = input ?? `You are the main session of agent ${name}. Roots addressed to it reach you: answer each or delegate it (supercode message delegate).`;
+        try { mainSession = await this.openSession(open, directory ?? process.cwd(), `agent:${name}`, first, async () => {}); }
+        catch (error) { return { code: EXIT_FAILED, text: `Not declared: ${error.message}` }; }
+      }
+    }
+    if (!parseAddress(mainSession)) {
+      const sessions = this.live.sessions();
+      const wanted = mainSession.split('@')[0];
+      const matching = sessions.filter((row) => row.name.split('@')[0] === wanted);
+      if (matching.length !== 1) return { code: EXIT_UNKNOWN, text: matching.length ? `${mainSession} names ${matching.length} sessions here; give its address.` : `No session named "${mainSession}" is reachable. Run supercode message list. Nothing was sent.` };
+      mainSession = matching[0].address;
+    }
+    try {
+      this.agents.declare({ name, main_session: mainSession, folder: directory, harness, idle_minutes });
+      if (owners_account_manager) this.agents.setOwnersAccountManager(name);
+    } catch (error) { return { code: 1, text: error.message }; }
+    return { code: 0, text: `Declared agent ${name} (${makeAddress(this.machine, 'agent', name)}): roots go to ${mainSession}.${owners_account_manager ? ' It is the owner\'s account manager.' : ''}` };
+  }
+
+  /** One declared agent, or all of them (message.rs `run_agent` Show). */
+  show(name) {
+    let agents;
+    if (name) {
+      const agent = this.agents.load(name);
+      if (!agent) return { code: EXIT_UNKNOWN, text: `No agent named ${name} is declared on this machine.` };
+      agents = [agent];
+    } else agents = this.agents.all();
+    const manager = this.agents.ownersAccountManager()?.name ?? null;
+    const text = agents.length
+      ? agents.map((agent) => `${agent.name}  ${makeAddress(this.machine, 'agent', agent.name)}\n  main: ${agent.main_session}\n  folder: ${agent.folder ?? '(none)'}\n  threads: ${this.agents.threadsOf(agent.name).length}${manager === agent.name ? '\n  the owner\'s account manager' : ''}`).join('\n')
+      : 'No agents are declared on this machine.';
+    return { code: 0, agents, text };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-teams",
-  "version": "0.3.86",
+  "version": "0.3.87",
   "type": "module",
   "description": "A machine daemon serving this machine's doors, and a local or remote Teams server for shared session discovery, OpenTelemetry ingestion and access to enrolled machines.",
   "license": "MIT",