indusagi-coding-agent 0.2.8 → 0.2.9

package/src/boot/runners/checkpoint.ts

@@ -0,0 +1,169 @@
+/**
+ * Per-session file-checkpoint store — the product half of rewind (#24).
+ *
+ * The framework's mutating file tools (write/edit) consult a host-injected handle
+ * on `ctx.framework` under the string-literal key {@link CHECKPOINT_HANDLE_KEY}.
+ * Immediately before a file is written — and after the read-before-edit gate has
+ * passed — the framework reads the file's CURRENT on-disk content and hands it to
+ * the handle as `record(absPath, previous)`, where `previous` is the old bytes or
+ * `null` when the file did not yet exist. This module supplies the missing host
+ * piece: a store that files those pre-mutation snapshots against the transcript
+ * node that was active when the mutation happened, so a later rewind to that node
+ * can roll the working tree back to exactly that point.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname as dirname2, normalize as normalize2 } from "node:path";
+
+/**
+ * The string-literal key under which the host wires this store onto the deck's
+ * `ctx.framework` bag.
+ *
+ * Mirrors the existing `DELEGATE_HANDLE_KEY = "delegate"`,
+ * `MEMORY_HANDLE_KEY = "memoryStore"`, and `READ_STATE_HANDLE_KEY = "readState"`
+ * conventions. The framework's mutating file tools read
+ * `ctx.framework["checkpoint"]` by the same literal, so the two sides agree by
+ * string rather than by a shared imported symbol.
+ */
+export const CHECKPOINT_HANDLE_KEY = "checkpoint";
+
+const ROOT_NODE_ID = "__root__";
+
+/**
+ * One file's pre-mutation snapshot: the path that was mutated and the content it
+ * held immediately before. `previous === null` records that the file did not
+ * exist on disk before the mutation, so restoring this snapshot deletes it.
+ */
+export interface FileSnapshot {
+  readonly path: string;
+  readonly previous: string | null;
+}
+
+/**
+ * Per-session file-checkpoint store, keyed by transcript node id.
+ *
+ * For each node id it holds a map of normalized absolute path → the FIRST-seen
+ * pre-mutation content for that path under that node. The framework calls
+ * `record` (via the duck-typed handle) before every write; the host pins the
+ * active node id with `setActiveNodeId` as the conductor's head moves; and
+ * `restore` rolls the working tree back to a node's recorded state.
+ */
+export class CheckpointStore {
+  /** node id → (normalized abs path → first-seen pre-mutation content). */
+  private readonly byNode = new Map<string, Map<string, string | null>>();
+
+  /** The transcript node the next `record` files its snapshot under. */
+  private current: string | null = null;
+
+  /** Normalize an absolute path into the store's canonical per-node key. */
+  private key(absPath: string): string {
+    return normalize2(absPath);
+  }
+
+  /** The node id new snapshots are currently filed under (`null` until pinned). */
+  activeNodeId(): string | null {
+    return this.current;
+  }
+
+  /**
+   * Pin the transcript node subsequent `record` calls file snapshots under.
+   *
+   * The conductor calls this as its head advances (at turn start), so all of a
+   * turn's edits key to the node that was active before the turn ran. Passing
+   * the same id again is harmless.
+   *
+   * @param id the active transcript node id, or `null` to fall back to the root
+   */
+  setActiveNodeId(id: string | null): void {
+    this.current = id;
+  }
+
+  /** The node id snapshots are filed under right now (active id or the root). */
+  private resolveNodeId(): string {
+    return this.current ?? ROOT_NODE_ID;
+  }
+
+  /**
+   * Capture the pre-mutation content of `absPath` under the active node.
+   *
+   * The framework's duck-typed `CheckpointHandle` entry point. Called once per
+   * mutated path immediately before the write lands, with the file's OLD
+   * on-disk content (or `null` when the file did not exist). First-seen wins:
+   * a later `record` of the same path under the same node is ignored so the
+   * snapshot reflects the file's state when the node became active, not a
+   * mid-turn rewrite.
+   *
+   * @param absPath  absolute path of the file about to be written
+   * @param previous the file's content before this mutation, or `null` if absent
+   */
+  record(absPath: string, previous: string | null): void {
+    const nodeId = this.resolveNodeId();
+    let paths = this.byNode.get(nodeId);
+    if (paths === undefined) {
+      paths = new Map<string, string | null>();
+      this.byNode.set(nodeId, paths);
+    }
+    const k = this.key(absPath);
+    if (paths.has(k)) return;
+    paths.set(k, previous);
+  }
+
+  /**
+   * The recorded snapshots for a node, or `[]` when nothing was tracked there.
+   *
+   * Each entry pairs the normalized absolute path with the content it held
+   * before the node's first mutation of it (`null` = the file was absent).
+   *
+   * @param nodeId the transcript node to read snapshots for
+   */
+  snapshotFor(nodeId: string): readonly FileSnapshot[] {
+    const paths = this.byNode.get(nodeId);
+    if (paths === undefined) return [];
+    return [...paths].map(([path, previous]) => ({ path, previous }));
+  }
+
+  /** Whether a node has ANY recorded file snapshot (the picker's restore gate). */
+  hasSnapshot(nodeId: string): boolean {
+    const paths = this.byNode.get(nodeId);
+    return paths !== undefined && paths.size > 0;
+  }
+
+  /**
+   * Roll the working tree back to a node's recorded state.
+   *
+   * For each path the node tracked: when its snapshot is a string, the file
+   * is rewritten with that pre-mutation content (creating parent directories
+   * as needed); when the snapshot is `null` the file is DELETED (it did not
+   * exist at that point). Returns the absolute paths that were restored, in
+   * record order.
+   *
+   * A safe no-op when the node has no snapshot — navigating to a node that
+   * never mutated files restores nothing. Per-path failures are swallowed so
+   * one unwritable path never aborts the rest of the restore.
+   *
+   * @param nodeId the transcript node whose file state to restore to
+   * @returns the absolute paths that were written or deleted
+   */
+  restore(nodeId: string): string[] {
+    const snapshots = this.snapshotFor(nodeId);
+    const restored: string[] = [];
+    for (const { path, previous } of snapshots) {
+      try {
+        if (previous === null) {
+          rmSync(path, { force: true });
+        } else {
+          mkdirSync(dirname2(path), { recursive: true });
+          writeFileSync(path, previous, "utf8");
+        }
+        restored.push(path);
+      } catch {
+        // swallow per-path failures — never abort the rest of the restore
+      }
+    }
+    return restored;
+  }
+}
+
+/** Mint a fresh, empty per-session checkpoint store. */
+export function createCheckpointStore(): CheckpointStore {
+  return new CheckpointStore();
+}

package/src/boot/runners/delegate-runner.ts

@@ -0,0 +1,294 @@
+/**
+ * Boot helper: a live {@link DelegateRunner} that makes the `task` tool real.
+ *
+ * The `task` capability ({@link "../../capability-deck/cards/task-card"}) advertises
+ * sub-agent delegation but only *runs* it when a {@link DelegateRunner} is wired
+ * into the deck context under {@link DELEGATE_HANDLE_KEY}; absent one it degrades
+ * to a typed `STUB_NOTE`. This module supplies that runner.
+ *
+ * Each delegated objective spins a *fresh, isolated* framework {@link Agent} (the
+ * same `facade/bot` Agent the conductor already drives — NOT the swarm `Crew` nor
+ * `runtime/createAgent`) bound to the parent's model id and credential resolver,
+ * given a survey-style system prompt and a deck that DELIBERATELY excludes the
+ * `task` card. That exclusion is the recursion guard: a sub-agent with no `task`
+ * tool cannot spawn its own sub-agents. The runner submits one prompt, lets the
+ * sub-agent run its own tool loop to completion, then extracts the final
+ * assistant turn's text as the single report handed back to the parent.
+ *
+ * The runner never throws out of `run()`: a model that does not resolve, a
+ * sub-agent error, or an empty transcript all map to a `{ ok:false, report }`
+ * result so a delegation failure surfaces to the parent agent as an ordinary
+ * tool error rather than crashing the turn. Cancellation is forwarded: an
+ * already-aborted signal short-circuits, and an abort raised mid-run calls
+ * `agent.abort()`.
+ *
+ * The `spawn`/`tools` options are pure test seams — they let a unit test drive
+ * the runner with an in-memory fake instead of a real network round-trip.
+ */
+import { Agent } from "indusagi/agent";
+import {
+  type AgentMessage,
+  type AgentTool,
+  type DelegateRunner,
+  type SessionPermissionPolicy,
+  ModelCatalog,
+  ModelMatcher,
+  withGatewayBaseUrl,
+  createSubagentPermissionGate,
+} from "../../conductor/index.js";
+import { provisionDeck } from "../../capability-deck/index.js";
+
+/**
+ * The minimal sub-agent surface the runner drives.
+ *
+ * A real framework {@link Agent} satisfies this structurally; a test passes a
+ * lightweight fake via {@link DelegateRunnerOptions.spawn}. Only the pieces the
+ * runner touches are named — submit a prompt, abort, and read the resulting
+ * transcript/error afterward.
+ */
+export interface DelegateSubAgent {
+  prompt(input: string): Promise<void>;
+  abort(): void;
+  readonly state: {
+    messages: readonly AgentMessage[];
+    error?: string;
+  };
+  /**
+   * Optional event subscription (the real framework `Agent` provides it). The
+   * runner uses it to recompute live token spend as the sub-agent works; a test
+   * fake may omit it, in which case no progress is reported.
+   */
+  subscribe?(listener: () => void): () => void;
+}
+
+/** Configuration for {@link createDelegateRunner}. */
+export interface DelegateRunnerOptions {
+  /** The model id the sub-agent runs under (the parent's resolved model). */
+  readonly modelId: string;
+  /** The working directory the sub-agent's deck is scoped to. */
+  readonly cwd: string;
+  /** The system prompt that shapes the sub-agent's behaviour. */
+  readonly system: string;
+  /**
+   * Per-call credential resolver, forwarded to the framework `Agent` unchanged
+   * (OAuth-only providers, short-lived token rotation). Omitted from the agent
+   * options entirely when undefined so the framework env-var lookup still wins.
+   */
+  readonly getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+  /**
+   * Test seam: build the sub-agent from the objective instead of constructing a
+   * real framework `Agent`. When omitted the runner uses `new Agent`.
+   */
+  readonly spawn?: (objective: string, context?: string) => DelegateSubAgent;
+  /**
+   * Test seam: the tool deck the sub-agent runs with. When omitted the runner
+   * provisions the read-only `'authoring'` profile (which already excludes the
+   * `task` card — the recursion guard).
+   */
+  readonly tools?: () => AgentTool[];
+  /**
+   * Resolve the current server-tier gateway routing map (provider -> gateway
+   * base url). Called FRESH on every `run()` — never cached — so a mid-session
+   * `/login` (to "Indus Server"), including one that lands after this runner was
+   * constructed but before a given delegated call, is always picked up. This
+   * mirrors {@link getApiKey}, which is likewise invoked per-request rather than
+   * resolved once at construction.
+   */
+  readonly getGatewayBaseUrls?: () => Promise<Record<string, string>>;
+  /**
+   * The parent session's live permission policy: the SAME mutable rule list the
+   * parent gate reads plus a live getter onto the conductor's current mode. When
+   * present, every spawned sub-agent runs under a RESOLVER-LESS gate built from
+   * it — deny/ask rules, plan-mode enforcement, and the catastrophic-bash
+   * blocklist apply per inner tool call, and a mid-run mode switch (Shift+Tab)
+   * retargets the very next delegated tool call. A sub-agent cannot prompt, so
+   * an `ask` decision deterministically denies with an actionable message.
+   * Absent (a bare test construction), the sub-agent runs ungated as before.
+   */
+  readonly permissionPolicy?: SessionPermissionPolicy;
+}
+
+function sumTokens(messages: readonly AgentMessage[]): number {
+  let total = 0;
+  for (const message of messages) {
+    const usage = (message as { usage?: { input?: number; output?: number } }).usage;
+    if (usage) total += (usage.input ?? 0) + (usage.output ?? 0);
+  }
+  return total;
+}
+
+function oneLine(text: string, max = 120): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+
+function argPreview(args: unknown): string {
+  if (args === null || typeof args !== "object") return "";
+  const entries = Object.entries(args as Record<string, unknown>);
+  if (entries.length === 0) return "";
+  const value = entries[0][1];
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  return ` (${oneLine(String(text), 56)})`;
+}
+
+interface ActivityEntry {
+  tone: "reason" | "tool";
+  text: string;
+}
+
+function buildActivity(messages: readonly AgentMessage[]): ActivityEntry[] {
+  const out: ActivityEntry[] = [];
+  for (const message of messages) {
+    if (message.role !== "assistant") continue;
+    const content = (message as { content?: unknown }).content;
+    if (!Array.isArray(content)) continue;
+    for (const part of content as Array<Record<string, unknown>>) {
+      const p = part;
+      if ((p.type === "text" && typeof p.text === "string" && p.text.trim()) || (p.type === "thinking" && typeof p.thinking === "string" && p.thinking.trim())) {
+        out.push({ tone: "reason", text: oneLine((p.text ?? p.thinking) as string) });
+      } else if (p.type === "toolCall" && typeof p.name === "string") {
+        const name = (p.name as string).charAt(0).toUpperCase() + (p.name as string).slice(1);
+        out.push({ tone: "tool", text: `${name}${argPreview(p.arguments)}` });
+      }
+    }
+  }
+  return out.slice(-14);
+}
+
+const MAX_PARALLEL_TASKS = (() => {
+  const n = parseInt(process.env.INDUS_MAX_PARALLEL_TASKS ?? "", 10);
+  return Number.isFinite(n) && n >= 1 ? n : 2;
+})();
+
+const MAX_REPORT_CHARS = (() => {
+  const n = parseInt(process.env.INDUS_MAX_DELEGATE_REPORT_CHARS ?? "", 10);
+  return Number.isFinite(n) && n >= 1000 ? n : 48000;
+})();
+
+let activeTasks = 0;
+const taskQueue: Array<() => void> = [];
+
+async function acquireTaskSlot(): Promise<() => void> {
+  if (activeTasks < MAX_PARALLEL_TASKS) {
+    activeTasks++;
+  } else {
+    await new Promise<void>((resolve) => taskQueue.push(resolve));
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const next = taskQueue.shift();
+    if (next) next();
+    else activeTasks--;
+  };
+}
+
+function clampReport(report: string): string {
+  if (report.length <= MAX_REPORT_CHARS) return report;
+  const head = Math.floor(MAX_REPORT_CHARS * 0.7);
+  const tail = MAX_REPORT_CHARS - head;
+  const omitted = report.length - MAX_REPORT_CHARS;
+  return `${report.slice(0, head)}\n\n\u2026[delegate report truncated \u2014 ${omitted} characters omitted to protect parent context]\u2026\n\n${report.slice(report.length - tail)}`;
+}
+
+function finalAssistantText(messages: readonly AgentMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role !== "assistant") continue;
+    const content = (message as { content?: unknown }).content;
+    if (!Array.isArray(content)) return typeof content === "string" ? content : "";
+    return (content as Array<Record<string, unknown>>)
+      .filter(
+        (block) => !!block && typeof block === "object" && block.type === "text" && typeof block.text === "string",
+      )
+      .map((block) => block.text as string)
+      .join("");
+  }
+  return "";
+}
+
+/**
+ * Build a live {@link DelegateRunner} the host wires into the deck context.
+ *
+ * The model is resolved once up front; if the id resolves to nothing the runner
+ * still builds but every `run()` reports `{ ok:false }` rather than throwing, so
+ * a misconfigured model can never crash the parent's turn.
+ *
+ * @param opts the model id, cwd, system prompt, and optional credential/test seams
+ * @returns a runner satisfying the task card's {@link DelegateRunner} contract
+ */
+export function createDelegateRunner(opts: DelegateRunnerOptions): DelegateRunner {
+  const model = new ModelMatcher(new ModelCatalog()).resolveCard(opts.modelId)?.model;
+  return {
+    async run(
+      request: { objective: string; context?: string },
+      signal?: AbortSignal,
+      onProgress?: (info: { tokens: number; activity: ActivityEntry[] }) => void,
+    ) {
+      if (opts.spawn === undefined && model === undefined) {
+        return { ok: false, report: "no model resolved for delegation" };
+      }
+      if (signal?.aborted) {
+        return { ok: false, report: "delegation aborted" };
+      }
+      const objective = request.context
+        ? `${request.objective}\n\nContext:\n${request.context}`
+        : request.objective;
+      const gatewayBaseUrls = await opts.getGatewayBaseUrls?.();
+      const releaseSlot = await acquireTaskSlot();
+      try {
+        if (signal?.aborted) {
+          return { ok: false, report: "delegation aborted" };
+        }
+        let agent: DelegateSubAgent | undefined = opts.spawn?.(request.objective, request.context);
+        if (agent === undefined) {
+          const tools = opts.tools?.() ?? provisionDeck("authoring", { cwd: opts.cwd }).tools();
+          agent = new Agent({
+            initialState: {
+              model: withGatewayBaseUrl(model as never, gatewayBaseUrls ?? {}),
+              systemPrompt: opts.system,
+              tools,
+            },
+            ...opts.getApiKey ? { getApiKey: opts.getApiKey } : {},
+            ...opts.permissionPolicy !== undefined
+              ? { canUseTool: createSubagentPermissionGate(opts.permissionPolicy, tools) }
+              : {},
+          }) as unknown as DelegateSubAgent;
+        }
+        const onAbort = () => agent!.abort();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        let lastSignature = "";
+        const reportProgress = () => {
+          if (!onProgress) return;
+          const tokens = sumTokens(agent!.state.messages);
+          const activity = buildActivity(agent!.state.messages);
+          const signature = `${tokens}:${activity.length}`;
+          if (signature !== lastSignature) {
+            lastSignature = signature;
+            onProgress({ tokens, activity });
+          }
+        };
+        const offProgress = onProgress ? agent.subscribe?.(reportProgress) : undefined;
+        try {
+          await agent.prompt(objective);
+          reportProgress();
+        } catch (cause) {
+          const message = cause instanceof Error ? cause.message : String(cause);
+          return { ok: false, report: clampReport(message || "delegation failed") };
+        } finally {
+          offProgress?.();
+          signal?.removeEventListener("abort", onAbort);
+        }
+        const error = agent.state.error;
+        const report = finalAssistantText(agent.state.messages);
+        return {
+          ok: error === undefined && report.length > 0,
+          report: clampReport(error ?? (report || "(no output)")),
+        };
+      } finally {
+        releaseSlot();
+      }
+    },
+  };
+}

package/src/boot/runners/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Runners subsystem — public barrel.
+ *
+ * Surfaces the runner registry and the individual placeholder runners. Boot
+ * consumers dispatch through {@link selectRunner} / {@link RUNNERS}; the named
+ * runners are exported for tests and for explicit wiring.
+ */
+export { replRunner } from "./repl-runner.js";
+export { oneshotRunner } from "./oneshot-runner.js";
+export { linkRunner } from "./link-runner.js";
+export { RUNNERS, selectRunner } from "./registry.js";
+export { createReadStateStore, READ_STATE_HANDLE_KEY, ReadStateStore } from "./read-state.js";
+export { createCheckpointStore, CHECKPOINT_HANDLE_KEY, CheckpointStore } from "./checkpoint.js";

package/src/boot/runners/link-runner.ts

@@ -0,0 +1,45 @@
+/**
+ * Runner: `link` — headless JSON-RPC link for a driving parent process.
+ *
+ * Drives the Phase-8 link channel: it assembles a {@link SessionConductor} for
+ * the invocation and serves the declarative {@link SESSION_OPS} registry over the
+ * process stdio pair via {@link createLinkServer}. Every framed request is
+ * dispatched through the registry (data-driven, not a command switch) and the
+ * reply is framed back; the runner resolves the success exit code once the
+ * inbound stream ends.
+ */
+import { createLinkServer, SESSION_OPS } from "../../channels/index.js";
+import type { Runner } from "../contract.js";
+import { buildSessionConductor } from "./session.js";
+
+const EXIT_OK = 0;
+
+const STDOUT = {
+  write(chunk: string | Uint8Array, cb?: (err?: Error | null) => void) {
+    return process.stdout.write(chunk, cb);
+  },
+};
+
+/**
+ * The headless-link runner.
+ *
+ * {@link Runner.accepts} matches invocations whose resolved mode is `link`.
+ * {@link Runner.run} assembles the conductor, starts a link server reading framed
+ * requests from stdin and writing framed replies to stdout, and resolves the
+ * success exit code when the inbound stream is exhausted.
+ */
+export const linkRunner: Runner = {
+  id: "link",
+  accepts(inv) {
+    return inv.mode === "link";
+  },
+  async run(ctx) {
+    const conductor = await buildSessionConductor(ctx);
+    const server = createLinkServer(SESSION_OPS, conductor, {
+      in: process.stdin,
+      out: STDOUT,
+    });
+    await server.done;
+    return EXIT_OK;
+  },
+};

package/src/boot/runners/memdir.ts

@@ -0,0 +1,168 @@
+/**
+ * Durable cross-session memory — a disk-backed working-memory store and the
+ * project-context document that carries it into each session's system prompt.
+ *
+ * The `memory` capability ({@link "../../capability-deck/cards/memory-card"})
+ * already reads a host-injected store from `ctx.framework[MEMORY_HANDLE_KEY]` and
+ * falls back to an in-process buffer when none is wired. This module supplies the
+ * missing piece: a synchronous {@link DiskMemoryStore} that persists the agent's
+ * note to a per-cwd `MEMORY.md` under the profile directory, so a fact written in
+ * one session is still there the next time the agent runs in the same directory.
+ *
+ * The same file is loaded into the briefing as a {@link ContextDoc} ({@link
+ * loadMemoryDoc}) so the model *sees* its prior memory at the top of a fresh
+ * session, not only when it explicitly calls the `memory` tool. The body is
+ * line-and-byte capped by {@link truncateEntrypointContent} so a runaway memory
+ * file cannot bloat the prompt.
+ *
+ * Design notes:
+ *   - The store is STRICTLY SYNCHRONOUS — the {@link MemoryStore} contract the
+ *     card validates is sync (`read`/`replace`/`append` return `void`/`string`),
+ *     and an async store would silently fail that validation and degrade to the
+ *     in-memory fallback.
+ *   - The memory directory is scoped UNDER `workspace.profileDir`, NOT the cwd, so
+ *     persisting memory never writes files into the user's working tree.
+ *   - The cwd is slugged with the SAME regex as {@link "./session".sessionScopeDir}
+ *     so the per-cwd partitioning lines up with the session layout.
+ *   - Files are written `0o600` (owner-only), matching the auth vault — the memory
+ *     note can hold sensitive project facts.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ContextDoc } from "../../briefing/index.js";
+import { type MemoryStore } from "../../capability-deck/index.js";
+import type { Workspace } from "../contract.js";
+
+/** The on-disk filename the durable memory note is stored under. */
+export const MEMORY_ENTRYPOINT = "MEMORY.md";
+/** Maximum number of lines of the memory note inlined into the prompt. */
+export const MAX_ENTRYPOINT_LINES = 200;
+/**
+ * Maximum bytes of the memory note inlined into the prompt.
+ *
+ * ~125 chars/line at 200 lines: this catches long-line indexes that slip past
+ * the line cap (a few very long lines can be far larger than 200 short ones).
+ */
+export const MAX_ENTRYPOINT_BYTES = 25000;
+
+/**
+ * Cap the memory note to {@link MAX_ENTRYPOINT_LINES} and
+ * {@link MAX_ENTRYPOINT_BYTES}, appending a warning naming which cap fired.
+ *
+ * Line-truncates first (a natural boundary), then byte-truncates at the last
+ * newline before the cap so a line is never cut mid-way. Content within both
+ * caps is returned trimmed and unchanged.
+ *
+ * @param raw the raw memory-file text
+ * @returns the prompt-safe body (possibly with a trailing truncation warning)
+ */
+export function truncateEntrypointContent(raw: string): string {
+  const trimmed = raw.trim();
+  const contentLines = trimmed.split("\n");
+  const lineCount = contentLines.length;
+  const byteCount = trimmed.length;
+  const wasLineTruncated = lineCount > MAX_ENTRYPOINT_LINES;
+  const wasByteTruncated = byteCount > MAX_ENTRYPOINT_BYTES;
+  if (!wasLineTruncated && !wasByteTruncated) {
+    return trimmed;
+  }
+  let truncated = wasLineTruncated ? contentLines.slice(0, MAX_ENTRYPOINT_LINES).join("\n") : trimmed;
+  if (truncated.length > MAX_ENTRYPOINT_BYTES) {
+    const cutAt = truncated.lastIndexOf("\n", MAX_ENTRYPOINT_BYTES);
+    truncated = truncated.slice(0, cutAt > 0 ? cutAt : MAX_ENTRYPOINT_BYTES);
+  }
+  const reason = wasByteTruncated && !wasLineTruncated
+    ? `${byteCount} bytes (limit: ${MAX_ENTRYPOINT_BYTES}) \u2014 index entries are too long`
+    : wasLineTruncated && !wasByteTruncated
+      ? `${lineCount} lines (limit: ${MAX_ENTRYPOINT_LINES})`
+      : `${lineCount} lines and ${byteCount} bytes`;
+  return `${truncated}\n\n> WARNING: ${MEMORY_ENTRYPOINT} is ${reason}. Only part of it was loaded. Keep index entries to one line under ~200 chars; move detail into topic files.`;
+}
+
+/**
+ * The per-cwd memory directory under the profile dir: `<profileDir>/memory/--<slug>--`.
+ *
+ * The cwd is slugged — every non-alphanumeric run collapsed to a single dash —
+ * and wrapped in `--…--` markers, the SAME scheme `sessionScopeDir` uses for the
+ * session transcript layout, so the two partitionings line up. The directory
+ * lives under `workspace.profileDir`, never inside the repo, so persisted memory
+ * never pollutes the user's working tree.
+ *
+ * @param workspace the resolved on-disk layout (supplies the profile dir)
+ * @param cwd       the run's working directory
+ */
+export function memoryDirFor(workspace: Workspace, cwd: string): string {
+  const slug = cwd.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return join(workspace.profileDir, "memory", `--${slug}--`);
+}
+
+/**
+ * A synchronous, disk-backed {@link MemoryStore} persisting the working-memory
+ * note to `<memDir>/MEMORY.md`.
+ *
+ * Satisfies the `memory` card's narrow three-method port. STRICTLY synchronous:
+ * the card validates that each of `read`/`replace`/`append` is a function and
+ * calls them inline, so any async variant would break the contract and silently
+ * fall back to the in-memory store. Writes create the directory and use mode
+ * `0o600` (owner-only), matching the auth vault.
+ */
+export class DiskMemoryStore implements MemoryStore {
+  private readonly memDir: string;
+  private readonly file: string;
+
+  constructor(memDir: string) {
+    this.memDir = memDir;
+    this.file = join(memDir, MEMORY_ENTRYPOINT);
+  }
+
+  /** The current note, or `""` when no file has been written yet. */
+  read(): string {
+    try {
+      return existsSync(this.file) ? readFileSync(this.file, "utf8") : "";
+    } catch {
+      return "";
+    }
+  }
+
+  /** Overwrite the note, creating the memory directory as needed (mode 0o600). */
+  replace(content: string): void {
+    mkdirSync(this.memDir, { recursive: true });
+    writeFileSync(this.file, content, { mode: 384 });
+  }
+
+  /** Add a single line to the end of the note (composed of read + replace). */
+  append(line: string): void {
+    const current = this.read();
+    const next = current.length === 0 ? line : `${current}\n${line}`;
+    this.replace(next);
+  }
+}
+
+/**
+ * Load the per-cwd memory note as a {@link ContextDoc} for the briefing's
+ * `# Project context` section, or `undefined` when there is nothing to show.
+ *
+ * An absent file, an empty/whitespace-only note, or any read error yields
+ * `undefined` (no project-context block); a non-empty note is capped by
+ * {@link truncateEntrypointContent} before inlining. The doc's `path` is the
+ * bare `MEMORY.md` label, not the on-disk location, so the heading reads cleanly.
+ *
+ * @param memDir the per-cwd memory directory from {@link memoryDirFor}
+ */
+export function loadMemoryDoc(memDir: string): ContextDoc | undefined {
+  let raw: string | undefined;
+  try {
+    const file = join(memDir, MEMORY_ENTRYPOINT);
+    if (!existsSync(file)) return undefined;
+    raw = readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+  if (raw === undefined) return undefined;
+  const body = truncateEntrypointContent(raw);
+  if (body.length === 0) return undefined;
+  return { path: MEMORY_ENTRYPOINT, body };
+}
+
+/** Re-exported so hosts wiring a store can use one import. */
+export { MEMORY_HANDLE_KEY } from "../../capability-deck/index.js";