cyberlegion 0.0.0

package/dist/index.d.mts

@@ -0,0 +1,656 @@
+//#region src/store/store.d.ts
+interface Message {
+  id: string;
+  from: string;
+  fromHandle: string;
+  to: string;
+  subject?: string;
+  body: string;
+  thread?: string;
+  replyTo?: string;
+  ts: number;
+  sentAt: string;
+}
+type Harness = 'claude' | 'cursor' | 'codex';
+type AgentStatus = 'spawning' | 'active' | 'idle' | 'stale' | 'exited' | 'paused';
+interface AgentRecord {
+  id: string;
+  handle: string;
+  harness: Harness;
+  cwd: string;
+  worktree?: {
+    root: string;
+    branch?: string;
+  } | null;
+  tmux?: {
+    pane: string;
+    window?: string;
+    session?: string;
+  } | null;
+  pid?: number;
+  status: AgentStatus;
+  createdAt: string;
+  lastSeen: string;
+  brief?: string;
+  spawnedBy?: string;
+}
+interface InboxSnapshot {
+  unread: Message[];
+  read: Message[];
+}
+/** The seam all mailbox + registry + brief/result access goes through. */
+interface Store {
+  /** This store's root (for path-relative concerns the Store itself doesn't cover, e.g. spawning
+   * a worktree under a project-local root distinct from this hub). */
+  readonly root: string;
+  /** Ensure this store's root is initialized (tracked marker present). Idempotent. */
+  ensureMarker(): void;
+  /** Write one message into `toId`'s inbox. Collision-free by `msg.id`. */
+  putMessage(toId: string, msg: Message): void;
+  /** The full unread/read split for one agent's inbox. */
+  listInbox(id: string): InboxSnapshot;
+  /** Ack a message by moving it out of the unread set; throws if it is not currently unread. */
+  ackMessage(id: string, msgId: string): Message;
+  /** Permanently remove a message (unread or already-acked) from `id`'s inbox; throws if absent. */
+  removeMessage(id: string, msgId: string): void;
+  /** Upsert an agent record (keyed by `rec.id`). */
+  putAgent(rec: AgentRecord): void;
+  getAgent(id: string): AgentRecord | undefined;
+  listAgents(): AgentRecord[];
+  removeAgent(id: string): void;
+  removeAgentData(id: string): void;
+  putPaneIndex(pane: string, agentId: string): void;
+  resolvePaneId(pane: string): string | undefined;
+  /** Reverse-lookup: an agent's pane from the index, when the agent record itself carries none
+   * (e.g. a herdr peer, whose pane is stored only in this index). */
+  findPaneByAgentId(agentId: string): string | undefined;
+  removePaneIndex(pane: string): void;
+  writeBrief(agentId: string, text: string): void;
+  readBrief(agentId: string): string | undefined;
+  /** Path this dispatch's result file would live at (computed only — no IO; existence not implied). */
+  resultPath(id: string): string;
+  /** Write a dispatch's result as JSON text. */
+  writeResult(id: string, value: unknown): void;
+  /** Read a dispatch's result JSON text, or undefined if not yet written. */
+  readResult(id: string): string | undefined;
+}
+//#endregion
+//#region src/identity.d.ts
+/** Runs a command synchronously; returns trimmed stdout, or null on any failure. */
+type Exec = (cmd: string, args: string[]) => string | null;
+declare const realExec: Exec;
+interface IdContext {
+  store: Store;
+  env?: NodeJS.ProcessEnv;
+  exec?: Exec;
+  now?: () => number;
+}
+declare function loadAgent(store: Store, id: string): AgentRecord | undefined;
+declare function listAgents(store: Store): AgentRecord[];
+/** Detect the harness: explicit wins, then env probes, then the tmux pane command. */
+declare function detectHarness(explicit: string | undefined, ctx: IdContext): Harness | undefined;
+/**
+ * Recover the calling agent's own id. In tmux the pane index is authoritative — a pane with no
+ * pane entry is simply unregistered and must NOT adopt `$CYBERLEGION_AGENT_ID` (that env fallback
+ * applies only when there is no `$TMUX_PANE`). There is no shared bare "self" file — self-id is
+ * always pane-keyed or explicit via the env var.
+ */
+declare function resolveSelfId(ctx: IdContext): string | undefined;
+interface RegisterInput {
+  handle?: string;
+  harness?: string;
+}
+/** Register (or idempotently refresh) this session's identity. */
+declare function register(ctx: IdContext, input: RegisterInput): AgentRecord;
+/** Resolve a recipient argument (id or handle) to an agent id. */
+declare function resolveRecipient(store: Store, to: string): string;
+/**
+ * Resolve a unit reference by id, handle, or its worktree branch (the unit↔CR join key: an
+ * `AgentRecord.worktree.branch` equals the SDD `<cr-ref>` it maps to, when spawned for one). Used
+ * by verbs that address "the unit working on CR X" as well as "the unit named X".
+ */
+declare function resolveAgent(store: Store, ref: string): AgentRecord;
+declare function bumpLastSeen(ctx: IdContext, id: string): void;
+/** Refresh this session's own last-seen if it is registered — best-effort, never throws. */
+declare function touch(ctx: IdContext): void;
+/** Mark agents whose pane is gone or whose last-seen is stale as exited. */
+declare function prune(ctx: IdContext): AgentRecord[];
+//#endregion
+//#region src/agentdef/resolve.d.ts
+interface AgentDef {
+  name: string;
+  description?: string;
+  model?: string;
+  effort?: string;
+  harness?: Harness;
+  warm?: boolean;
+  interactive?: boolean;
+  instructions: string;
+  path: string;
+}
+interface ResolveAgentDefInput {
+  /** Resolve `<name>.md` by search — mutually exclusive with `file`. */
+  name?: string;
+  /** Read this exact path — bypasses name search entirely (the plugin-scoped escape hatch). */
+  file?: string;
+  /** Extra dirs to search (each dir is checked for `<name>.md`), ahead of the project convention. */
+  searchRoots?: string[];
+  cwd?: string;
+}
+/** Resolve one agent definition, by explicit file or by name search. Throws a clear error when
+ * neither locates a def — never returns a partial/empty result. */
+declare function resolveAgentDef(input: ResolveAgentDefInput): AgentDef;
+/** List every resolvable agent def under `.agents/agents/` (+ any extra search roots). Definitive
+ * empty array when the dir is absent or empty — never throws for "none found" here (unlike a
+ * named resolve, listing is inherently zero-or-more). */
+declare function listAgentDefs(input?: {
+  cwd?: string;
+  searchRoots?: string[];
+}): AgentDef[];
+//#endregion
+//#region src/agentdef/realize.d.ts
+interface RealizeLaunchOptions {
+  /** Overrides def.model when present. */
+  model?: string;
+  /** Overrides def.harness when present; falls back to 'claude' when neither is set. */
+  harness?: Harness;
+}
+interface RealizedLaunch {
+  harness: Harness;
+  command: string;
+}
+/** Build the harness launch invocation for a def — explicit `model`/`harness` win over the def's
+ * own tags, which win over the harness default. Every harness gets the same shape (bin,
+ * `--model` when known, `--append-system-prompt` carrying the def's instructions body) since the
+ * exact per-harness flag surface is realized later by the launching caller, not by cyberlegion. */
+declare function realizeLaunch(def: AgentDef, opts?: RealizeLaunchOptions): RealizedLaunch;
+interface RealizeSubagentOptions {
+  /** File the spawned subagent reads its brief from. */
+  briefFile: string;
+  /** File the spawned subagent writes its result JSON to. */
+  resultFile: string;
+}
+/** Build the instruction string a parent model uses to spawn its OWN harness Task subagent for
+ * `def` — cyberlegion never invokes the Task tool itself. Names `subagent_type: <def.name>` for a
+ * harness that recognizes it, but always inlines the model + full instructions too so the same
+ * instruction string is correct even when the harness has no such named subagent type. */
+declare function realizeSubagentInstruction(def: AgentDef, opts: RealizeSubagentOptions): string;
+//#endregion
+//#region src/console/session.d.ts
+/** Generic multiplexer seam — no legion-specific concepts, so this composes with any host. */
+/** Where a new pane/window/session should be placed relative to the caller's current one. */
+type SessionPlacement = 'pane:right' | 'pane:down' | 'tab' | 'window';
+interface SessionOpenOptions {
+  /** Working directory the new pane/window/session should start in. */
+  cwd: string;
+  /** Command line to launch inside the new pane once it is open. */
+  launch: string;
+  /** Placement relative to the caller; defaults to 'pane:right'. */
+  at?: SessionPlacement;
+}
+/** Opaque handle to an open pane/window/session; backend-specific id lives in `id`. */
+interface SessionTarget {
+  id: string;
+}
+interface SessionReadOptions {
+  /** How many trailing lines of output to capture; omit for the backend's default. */
+  lines?: number;
+}
+interface SessionAdapter {
+  /** Backend name, e.g. "tmux" or "herdr". */
+  readonly name: string;
+  /** Create a new pane/window running `opts.launch` in `opts.cwd`; returns its target handle. */
+  open(exec: Exec, opts: SessionOpenOptions): SessionTarget;
+  /** Type text into the target session (submitted, not queued). */
+  send(exec: Exec, target: SessionTarget, text: string): void;
+  /** Capture the target session's current output. */
+  read(exec: Exec, target: SessionTarget, opts?: SessionReadOptions): string;
+  /** Move input focus to the target session; best-effort (may no-op if the backend can't). */
+  focus(exec: Exec, target: SessionTarget): void;
+  /** Close the target session. */
+  teardown(exec: Exec, target: SessionTarget): void;
+}
+//#endregion
+//#region src/console/index.d.ts
+/**
+ * Backend selection via the two-mode mux probe (`$CYBERLEGION_MUX` fast-path/override, else
+ * ancestry discovery from `$$` falling back to the `$TMUX`/`$HERDR_ENV` hint when the walk is
+ * inconclusive) — tmux/herdr map to their existing adapters; anything else is a clear error.
+ */
+declare function selectSessionAdapter(env: NodeJS.ProcessEnv, exec?: Exec): SessionAdapter;
+//#endregion
+//#region src/console/mux-probe.d.ts
+type Mux = 'tmux' | 'herdr' | 'screen' | 'none';
+interface MuxProbe {
+  mux: Mux;
+  pane?: string;
+  /** 'env' — trusted the $CYBERLEGION_MUX fast-path/override. 'ancestry' — walked the process tree. */
+  via: 'env' | 'ancestry';
+}
+/**
+ * Two-mode multiplexer detection.
+ *
+ * Fast-path: `$CYBERLEGION_MUX` (tmux | herdr | screen | none) is trusted outright — this also
+ * serves as an OVERRIDE (`=none` forces no-mux even inside a real multiplexer). `$CYBERLEGION_MUX_PANE`
+ * carries the pane id alongside it.
+ *
+ * Discovery (else): walk the process ancestry from `$$` via `ps -o ppid=,comm= -p <pid>`, since the
+ * tool's own shell may not be the human's pane. `$TMUX`/`$HERDR_ENV` are NOT trusted alone — they
+ * are used only as a fast-positive hint the ancestry walk falls back to when the walk itself is
+ * inconclusive (e.g. `ps` unavailable), never as a substitute for it.
+ */
+declare function probeMultiplexer(exec: Exec, env: NodeJS.ProcessEnv, opts?: {
+  discover?: boolean;
+}): MuxProbe;
+//#endregion
+//#region src/console/worktree.d.ts
+/** Generic multiplexer/worktree seam — no legion-specific concepts. */
+interface WorktreeAddOptions {
+  /** The primary checkout's root — the repo `git worktree add` runs against. */
+  primaryRoot: string;
+  /** Where the new worktree should be checked out. */
+  path: string;
+  /** Branch to create the worktree on. */
+  branch: string;
+}
+interface Worktree {
+  root: string;
+  branch: string;
+}
+interface WorktreeRemoveOptions {
+  primaryRoot: string;
+}
+interface WorktreeAdapter {
+  add(exec: Exec, opts: WorktreeAddOptions): Worktree;
+  remove(exec: Exec, path: string, opts: WorktreeRemoveOptions): void;
+}
+/** The only worktree backend at MVP — plain `git worktree`. */
+declare const gitWorktreeAdapter: WorktreeAdapter;
+/**
+ * Resolve the primary checkout's root regardless of whether the caller's cwd is the primary
+ * checkout or a linked worktree — `--git-common-dir` always points at the main repo's `.git`.
+ */
+declare function resolvePrimaryRoot(exec: Exec): string;
+/**
+ * Refuse the primary checkout: a spawned unit's resolved worktree root must never be the primary
+ * checkout itself. A unit is never run in the primary checkout.
+ */
+declare function assertDistinctFromPrimary(worktreeRoot: string, primaryRoot: string): void;
+//#endregion
+//#region src/decommission.d.ts
+interface DecommissionInput {
+  id: string;
+  /** Discard uncommitted changes in the worktree. Never overrides refusing the primary checkout. */
+  force?: boolean;
+}
+interface DecommissionResult {
+  agent: AgentRecord;
+  worktreeRoot?: string;
+  pane?: string;
+}
+/**
+ * Tear a unit down and reap its registry record — the deterministic inverse of `spawn`. Refuses
+ * the primary checkout (absolute — `--force` never overrides it) and a dirty worktree unless
+ * `--force`. Teardown always precedes reap: an already-gone worktree or pane is tolerated, but a
+ * genuine worktree-removal failure aborts and leaves the record intact so the operation is
+ * retryable.
+ */
+declare function decommission(ctx: IdContext, input: DecommissionInput): DecommissionResult;
+//#endregion
+//#region src/dispatch/prep.d.ts
+interface DispatchContext {
+  store: Store;
+}
+interface PrepInput {
+  /** Resolve an agent def (`.agents/agents/<name>.md`) to build the instruction from. */
+  agent?: string;
+  /** Read an exact agent def file instead of resolving by name (plugin-scoped escape hatch). */
+  agentFile?: string;
+  /** Role label folded into the generic instruction when no agent def is given. */
+  role?: string;
+  /** Brief body text. */
+  briefText?: string;
+  /** Read the brief from a file, or `-` for stdin. */
+  briefFile?: string;
+  /** JSON schema file the eventual result must satisfy — carried through by callers that validate. */
+  verdictSchema?: string;
+  /** Thread id correlating a channel-path reply; defaults to the minted dispatch id. */
+  thread?: string;
+}
+interface DispatchEnvelope {
+  id: string;
+  thread: string;
+  briefFile: string;
+  resultFile: string;
+  instruction: string;
+}
+/**
+ * Allocate a dispatch: mint an id (thread defaults to it), write the brief into the Store, compute
+ * the result-slot path, and build the instruction from a resolved agent def (or a generic one).
+ * Spawns nothing — the envelope is handed to whatever spawns next (a Task tool, `channel()`, a
+ * human).
+ */
+declare function prep(ctx: DispatchContext, input: PrepInput, readStdin?: () => string): DispatchEnvelope;
+//#endregion
+//#region src/dispatch/channel.d.ts
+interface ChannelInput extends PrepInput {
+  /** Block for the mail-thread reply and return a validated `DispatchResult`; without it, the peer
+   * is spawned and the envelope is returned so the caller can `mail await` later. */
+  wait?: boolean;
+  /** Placement relative to the caller; defaults to 'pane:right'. */
+  at?: SessionPlacement;
+  timeoutMs?: number;
+  maxWaitS?: number;
+}
+interface DispatchResult {
+  id: string;
+  verdict?: unknown;
+  body: string;
+  ts: number;
+}
+/** Thrown by a `--wait` channel call when its internal poll-cycle cap is hit with no reply yet — a
+ * clean, re-armable sentinel (mirrors `mail await`'s "waiting" outcome), never a failure. */
+declare class DispatchWaitingError extends Error {
+  readonly thread: string;
+  constructor(thread: string);
+}
+/**
+ * `prep()` + spawn a peer session realized from the same agent def + (optionally) `awaitReply` on
+ * the thread. Requires `--agent`/`--agent-file` (a channel peer needs a real launch to realize).
+ */
+declare function channel(ctx: IdContext, input: ChannelInput, readStdin?: () => string): Promise<DispatchResult | DispatchEnvelope>;
+//#endregion
+//#region src/dispatch/collect.d.ts
+interface CollectContext {
+  store: Store;
+  now?: () => number;
+}
+/** Read + validate a dispatch's result file. Throws (fail-loud) when the file is not yet written,
+ * or when it fails the optional verdict schema. */
+declare function collect(ctx: CollectContext, id: string, verdictSchema?: string): DispatchResult;
+//#endregion
+//#region src/runtime/inject-inbox.d.ts
+type HookEvent = 'SessionStart' | 'PostToolUse';
+interface InjectPayload {
+  hookSpecificOutput: {
+    hookEventName: HookEvent;
+    additionalContext: string;
+  };
+}
+/**
+ * Resolve the calling agent, gather its pending brief + unread mail, and return the
+ * SessionStart-style injection payload — or null when there is nothing to inject (an
+ * unregistered caller or an empty inbox never fails the harness hook).
+ */
+declare function injectInbox(ctx: IdContext, event: string): InjectPayload | null;
+//#endregion
+//#region src/install.d.ts
+type InstallStatus = 'registered' | 'already present';
+interface InstallResult {
+  harness: Harness;
+  event: HookEvent;
+  vendorEvent: string;
+  file: string;
+  status: InstallStatus;
+}
+/** Register the surfacing hook into one harness's config, idempotently. */
+declare function install(harness: Harness, projectDir?: string): InstallResult[];
+//#endregion
+//#region src/message.d.ts
+interface MsgContext {
+  store: Store;
+  now?: () => number;
+}
+interface SendInput {
+  fromId: string;
+  to: string;
+  subject?: string;
+  body: string;
+  thread?: string;
+  replyTo?: string;
+}
+/** Write one message into the recipient's inbox. Collision-free by <epochMs>-<hex>. */
+declare function send(ctx: MsgContext, input: SendInput): Message;
+/** Resolve a message body from the --body flag, a --body-file path, or stdin (--body-file -). */
+declare function resolveBody(body: string | undefined, bodyFile: string | undefined, readStdin?: () => string): string;
+interface InboxItem extends Message {
+  read: boolean;
+}
+interface InboxQuery {
+  meId: string;
+  unread?: boolean;
+  from?: string;
+  /** Filter to messages carrying this thread id; a message with no thread is excluded. */
+  thread?: string;
+}
+/** List the caller's mail, chronological (lexical id sort == time order). */
+declare function inbox(ctx: MsgContext, q: InboxQuery): InboxItem[];
+/** Peek at a message (unread or already-acked) without changing its state. */
+declare function peek(ctx: MsgContext, meId: string, msgId: string): Message | undefined;
+/** Acknowledge a message by moving it out of the unread set. Errors if not currently unread. */
+declare function ack(ctx: MsgContext, meId: string, msgId: string): Message;
+/** Permanently remove a message (unread or already-acked) from the caller's inbox. */
+declare function deleteMessage(ctx: MsgContext, meId: string, msgId: string): void;
+//#endregion
+//#region src/output.d.ts
+type Format = 'toon' | 'json';
+/** One TOON-encoded object: `key: value` lines, blank/undefined fields dropped. */
+declare function toonObject(fields: Record<string, unknown>): string;
+/** One TOON-encoded list: a `name[N]{field,...}:` header plus one row per item, then an aggregate
+ * summary line. Definitive on empty — still emits `name[0]{...}:` plus the summary line. */
+declare function toonList<T>(name: string, items: T[], fields: {
+  key: string;
+  get: (item: T) => unknown;
+}[], summary: string): string;
+interface EmitPayload<T = unknown> {
+  /** The TOON-rendered string (already includes any aggregate/summary line). */
+  toon: string;
+  /** The structured value emitted verbatim as JSON under `--format json`. */
+  json: T;
+}
+/** Print a command's result to stdout in the requested format. */
+declare function emit(format: Format, payload: EmitPayload): void;
+/** A stderr-only next-step suggestion — never part of the machine-readable stdout result. */
+declare function nextStep(msg: string): void;
+/** A structured, fail-loud error: stderr + exit 1. Never prompts, never partially writes. */
+declare function fail(msg: string): never;
+//#endregion
+//#region src/paths.d.ts
+/** Walk up from `cwd` to the nearest git repo root; fall back to `cwd`. */
+declare function projectRoot(cwd?: string): string;
+/** Runs a command synchronously in `cwd`; returns trimmed stdout, or null on any failure. */
+type Exec$1 = (cmd: string, args: string[]) => string | null;
+interface RootOptions {
+  root?: string;
+  space?: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  exec?: Exec$1;
+}
+/**
+ * Resolve the cyberlegion hub root. Precedence: explicit --root/--space, then `$CYBERLEGION_ROOT`,
+ * then the GLOBAL hub `~/.agents/cyberlegion` (addressable across every project and worktree
+ * boundary — identity/mail/registry state lives here by default; `--space` isolates it), falling
+ * back to a project-local `.agents/cyberlegion` only when no home directory is resolvable.
+ */
+declare function resolveRoot(opts?: RootOptions): string;
+/**
+ * Resolve the primary checkout's project-local cyberlegion dir — where spawned unit worktrees
+ * live (never the global hub), keyed off `git worktree`'s common-dir so it resolves the same from
+ * the primary checkout or from any of its linked worktrees.
+ */
+declare function resolveProjectLocalRoot(opts?: RootOptions): string;
+/**
+ * Create the tracked `config.json` marker at `root` (a hub root) if it does not already exist.
+ * Callers pass the root under which the marker should be created/ensured; this mkdir's it as
+ * needed. Idempotent — never overwrites an existing marker.
+ */
+declare function ensureMarker(root: string): void;
+declare const paths: {
+  agentsDir: (root: string) => string;
+  agentFile: (root: string, id: string) => string;
+  panesDir: (root: string) => string;
+  paneFile: (root: string, pane: string) => string;
+  inboxDir: (root: string, id: string) => string;
+  inboxReadDir: (root: string, id: string) => string;
+  dataDir: (root: string, id: string) => string;
+  briefFile: (root: string, id: string) => string;
+  resultFile: (root: string, id: string) => string;
+  worktreeDir: (root: string, id: string) => string;
+};
+//#endregion
+//#region src/session.d.ts
+interface SpawnInput {
+  harness?: string;
+  task?: string;
+  briefFile?: string;
+  handle?: string;
+  /** Override the default per-harness launch command (e.g. an agent-def's `realizeLaunch` output,
+   * carrying `--model`/`--append-system-prompt`) — composed in by callers, never by `spawn` itself
+   * (avoids a session.ts ↔ agentdef/realize.ts import cycle, since `realizeLaunch` already reads
+   * `LAUNCH_MAP` from here). */
+  command?: string;
+  /** Branch to create the unit's worktree on; defaults to `cyberlegion/unit-<id>`. */
+  branch?: string;
+  /** Where to check out the unit's worktree; defaults under `<primary>/.agents/cyberlegion/worktrees/<id>`. */
+  worktreePath?: string;
+  /** Placement relative to the caller; defaults to 'pane:right'. */
+  at?: SessionPlacement;
+}
+interface SpawnResult {
+  agent: AgentRecord;
+  pane: string;
+  launch: string;
+}
+/**
+ * Launch a new peer session as a genuine sibling unit: create a real git worktree distinct from
+ * the primary checkout (refuse the primary checkout), open a session backend (tmux or herdr) with
+ * its cwd set to that worktree, pre-register the peer, and drop its brief as a file the peer's own
+ * SessionStart hook reads — never typed into its prompt.
+ *
+ * Spawned unit worktrees live project-local (`<primary>/.agents/cyberlegion/worktrees/<id>`), even
+ * though the registry/mailbox itself lives in the global hub — the hub addresses units across
+ * project and worktree boundaries, but a unit's checkout is necessarily project-local.
+ */
+declare function spawn(ctx: IdContext, input: SpawnInput): SpawnResult;
+//#endregion
+//#region src/store/file-store.d.ts
+/** The on-disk `Store` implementation — current per-writer sharded `.json` layout (ADR-0020):
+ * one file per message/agent, collision-free filenames, ack = atomic rename into `read/`. */
+declare class FileStore implements Store {
+  readonly root: string;
+  constructor(root: string);
+  ensureMarker(): void;
+  putMessage(toId: string, msg: Message): void;
+  listInbox(id: string): InboxSnapshot;
+  ackMessage(id: string, msgId: string): Message;
+  removeMessage(id: string, msgId: string): void;
+  putAgent(rec: AgentRecord): void;
+  getAgent(id: string): AgentRecord | undefined;
+  listAgents(): AgentRecord[];
+  removeAgent(id: string): void;
+  removeAgentData(id: string): void;
+  putPaneIndex(pane: string, agentId: string): void;
+  resolvePaneId(pane: string): string | undefined;
+  findPaneByAgentId(agentId: string): string | undefined;
+  removePaneIndex(pane: string): void;
+  writeBrief(agentId: string, text: string): void;
+  readBrief(agentId: string): string | undefined;
+  resultPath(id: string): string;
+  writeResult(id: string, value: unknown): void;
+  readResult(id: string): string | undefined;
+}
+//#endregion
+//#region src/wake/await.d.ts
+interface AwaitInput {
+  meId: string;
+  thread: string;
+  from?: string;
+  /** Give up after this many ms with no match; 0 = wait forever. Default 600_000 (600s). */
+  timeoutMs?: number;
+  /** Self-cap for one internal poll cycle, in seconds. Default 240 (well under a harness tool-timeout). */
+  maxWaitS?: number;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+type AwaitOutcome = {
+  kind: 'matched';
+  message: InboxItem;
+} | {
+  kind: 'waiting';
+} | {
+  kind: 'timed-out';
+};
+/**
+ * Block on the caller's UNREAD inbox until a message matching `thread` (and optional `from`)
+ * arrives, polling on a fixed ~1s internal interval. Three unambiguous outcomes:
+ *
+ * - `matched` — a message arrived; it is printed by the caller AND acked here (moved to read/), so
+ *   it leaves the unread set. Block-then-read: each await consumes exactly its round.
+ * - `waiting` — this call's internal poll cycle hit its `maxWaitS` cap (default 240s, always well
+ *   under a harness tool-timeout SIGKILL) with no match yet. A clean, non-error return the caller
+ *   re-arms on (calls `awaitReply` again) — NOT the same as giving up.
+ * - `timed-out` — the caller's overall `timeoutMs` (default 600_000ms / 600s; `0` = wait forever)
+ *   elapsed across re-arms with no match. The caller should exit non-zero.
+ */
+declare function awaitReply(ctx: MsgContext, input: AwaitInput): Promise<AwaitOutcome>;
+//#endregion
+//#region src/wake/wake-path.d.ts
+/**
+ * The wake-matrix path a gateway would drive a turn through. Pure decision helper — no I/O, no
+ * polling, no session backend calls; the gateway (`legion-gateway-legate`, CR-5) composes this with
+ * the actual `mail await` / `session nudge` primitives.
+ *
+ * - **A** — a single unbounded `mail await` (not returned here; superseded by A-loop everywhere the
+ *   gateway drives this decision, since a raw A risks a harness tool-timeout SIGKILL).
+ * - **A-loop** — the portable default: a bounded `mail await` cycle, re-armed by the caller.
+ * - **A-prime** — Claude Code with an observable background task: run `await` via
+ *   `run_in_background` and poll its result instead of blocking the turn.
+ * - **B** — a live foreign session behind a verified multiplexer: ring the doorbell
+ *   (`session nudge`) instead of polling. Never selected without a mux.
+ * - **C** — own-the-PTY (dropped from the shipped matrix; kept as a type for completeness).
+ * - **D** — `/loop`-style external re-invocation (dropped from the shipped matrix).
+ * - **E** — hook surfacing at a turn boundary (selected by the caller directly, not by this
+ *   function — it has no wait/poll shape to decide between).
+ */
+type WakePath = 'A' | 'A-loop' | 'A-prime' | 'B' | 'C' | 'D' | 'E';
+interface WakePathInput {
+  /** The calling harness, e.g. 'claude' | 'cursor' | 'codex'. */
+  harness: string;
+  mux: MuxProbe;
+  /** The harness can observe a backgrounded task's result without blocking the turn. */
+  observable?: boolean;
+  /** The target is a live, foreign interactive session that can be rung rather than polled. */
+  dedicatedListener?: boolean;
+}
+interface WakePathResult {
+  path: WakePath;
+  why: string;
+}
+/**
+ * Select a wake path from the shipped matrix. Rule order: a `mux.mux === 'none'` caller can never
+ * get **B** — it always falls through to the bounded poll. Claude Code + an observable background
+ * task prefers **A-prime**. A live foreign session behind a verified mux prefers **B**. Otherwise
+ * the portable default is **A-loop**.
+ */
+declare function selectWakePath(input: WakePathInput): WakePathResult;
+//#endregion
+//#region src/wake/watch.d.ts
+interface WatchInput {
+  meId: string;
+  thread?: string;
+  from?: string;
+}
+interface WatchOptions {
+  sleep?: (ms: number) => Promise<void>;
+  /** Bounds the loop for tests; omitted (default) runs until the process is interrupted. */
+  maxIterations?: number;
+}
+/**
+ * A continuous foreground observer: prints each NEW matching message as it arrives, polling on a
+ * fixed ~1s interval, until interrupted (or `maxIterations` in tests). Never acks — a message
+ * `watch` prints stays unread and still surfaces later in `mail inbox`/`mail await`.
+ */
+declare function watchMail(ctx: MsgContext, input: WatchInput, onMessage: (msg: InboxItem) => void, opts?: WatchOptions): Promise<void>;
+//#endregion
+export { type AgentDef, type AgentRecord, type AwaitInput, type AwaitOutcome, type ChannelInput, type DecommissionInput, type DecommissionResult, type DispatchEnvelope, type DispatchResult, DispatchWaitingError, type Exec, FileStore, type Format, type Harness, type HookEvent, type IdContext, type InboxItem, type InboxQuery, type InboxSnapshot, type Message, type MuxProbe, type PrepInput, type RegisterInput, type RootOptions, type SendInput, type SpawnInput, type SpawnResult, type Store, type WakePathInput, type WakePathResult, ack, assertDistinctFromPrimary, awaitReply, bumpLastSeen, channel, collect, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, inbox, injectInbox, install, listAgentDefs, listAgents, loadAgent, nextStep, paths, peek, prep, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, realizeSubagentInstruction, register, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, selectSessionAdapter, selectWakePath, send, spawn, toonList, toonObject, touch, watchMail };

package/dist/index.mjs

@@ -0,0 +1,28 @@
+import { A as resolveProjectLocalRoot, B as loadAgent, C as resolveAgentDef, D as ensureMarker, E as spawn, F as selectSessionAdapter, G as resolveRecipient, H as realExec, I as probeMultiplexer, K as resolveSelfId, L as bumpLastSeen, M as assertDistinctFromPrimary, N as gitWorktreeAdapter, O as paths, P as resolvePrimaryRoot, R as detectHarness, S as listAgentDefs, T as realizeSubagentInstruction, U as register, V as prune, W as resolveAgent, _ as inbox, a as fail, b as send, c as toonObject, d as DispatchWaitingError, f as channel, g as deleteMessage, h as ack, i as emit, j as resolveRoot, k as projectRoot, l as install, m as awaitReply, n as FileStore, o as nextStep, p as prep, q as touch, r as injectInbox, s as toonList, t as watchMail, u as collect, v as peek, w as realizeLaunch, x as decommission, y as resolveBody, z as listAgents } from "./watch-DA8I44dv.mjs";
+//#region src/wake/wake-path.ts
+/**
+* Select a wake path from the shipped matrix. Rule order: a `mux.mux === 'none'` caller can never
+* get **B** — it always falls through to the bounded poll. Claude Code + an observable background
+* task prefers **A-prime**. A live foreign session behind a verified mux prefers **B**. Otherwise
+* the portable default is **A-loop**.
+*/
+function selectWakePath(input) {
+	if (input.mux.mux === "none") return {
+		path: "A-loop",
+		why: "no multiplexer detected — bounded poll only, B is never available"
+	};
+	if (input.harness === "claude" && input.observable) return {
+		path: "A-prime",
+		why: "Claude Code + an observable background task — await via run_in_background"
+	};
+	if (input.dedicatedListener) return {
+		path: "B",
+		why: `a live foreign session behind a verified ${input.mux.mux} mux — ring the doorbell`
+	};
+	return {
+		path: "A-loop",
+		why: "portable default — bounded mail await cycle"
+	};
+}
+//#endregion
+export { DispatchWaitingError, FileStore, ack, assertDistinctFromPrimary, awaitReply, bumpLastSeen, channel, collect, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, inbox, injectInbox, install, listAgentDefs, listAgents, loadAgent, nextStep, paths, peek, prep, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, realizeSubagentInstruction, register, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, selectSessionAdapter, selectWakePath, send, spawn, toonList, toonObject, touch, watchMail };