@sema-agent/server 1.323.0 → 2.0.0

package/dist/project-memory.d.ts

@@ -7,13 +7,35 @@ interface ProjectMemoryCtx {
     sessionId?: string;
     phase?: "fresh" | "resume" | "post-compact" | "post-clear";
 }
+/**
+ * Build a `loadProjectMemory` for the host lane. Returns null (skip) unless hands are enabled AND cwd is a local
+ * directory. Reads the instruction-file chain (AGENTS.md → CLAUDE.md → .claude/CLAUDE.md, S-1) + (non-subagent)
+ * `git log -5` / `git status`, redacts secrets, and caps the total. A subagent gets a trimmed instruction file and
+ * no git narrative (cost control, H7). When an instruction file is hit the return is a `ProjectMemoryLoad`
+ * declaring it in `instructionSources` (path + sha256 over the raw bounded-read window) so core's
+ * instructions-change lane can probe it mid-run.
+ *
+ * Session snapshot cache (S-2): keyed on ctx.sessionId — a session keeps ONE stable instruction snapshot
+ * (mid-run file edits surface via the probe as tail attachments, never a silently re-rendered prefix).
+ * `phase: "post-compact"` forces a re-read (core re-renders the prefix there anyway). No entry for
+ * sessionless one-shot runs. (post-clear never arrives from core — RB-9 — so it is not a cache key here.)
+ */
 export declare function makeLoadProjectMemory(opts: {
     logger?: {
         debug?: (msg: string, data: Record<string, unknown>) => void;
     };
     maxBytes?: number;
+    /** TEST-ONLY: shrink the snapshot-cache bound so the settle-time trim is observable without 256 sessions. */
     cacheMax?: number;
 }): (ctx: ProjectMemoryCtx) => Promise<string | null | ProjectMemoryLoad>;
+/**
+ * ② The `RunnerDeps.probeInstructionSources` seam: re-fingerprint the declared instruction files mid-run so
+ * core's instructions-change lane can append a tail attachment when one changes. Same read posture as the
+ * loader (lstat symlink gate → bounded read of the first `INSTRUCTION_READ_CAP` bytes → sha256) — any drift
+ * here would fabricate phantom "changed" signals every turn. Per-source failure → `contentHash: null`
+ * (source gone/unreadable); any unexpected top-level failure → `null` (probe abstains; core also races this
+ * against a 2s ceiling and treats a throw as null, but we stay honest on our side of the seam).
+ */
 export declare function makeProbeInstructionSources(): NonNullable<import("@sema-agent/core").RunnerDeps["probeInstructionSources"]>;
 export {};
 //# sourceMappingURL=project-memory.d.ts.map

package/dist/project-memory.js

@@ -1,46 +1,95 @@
+/**
+ * design/113 C4 — `RunnerDeps.loadProjectMemory` (core 1.182): the DEPLOYMENT half that makes sema "open like CC" —
+ * inject the project's CLAUDE.md + recent git narrative as a read-only, fenced virtual memory layer at the tail of the
+ * env block, so a fresh "你好" lands on "I'm the AI for the acme-widget project…" instead of a blank greeting.
+ *
+ * core's half (1.182/1.184): it calls this once per prepare, fences+sanitizes the return as UNTRUSTED data (CLAUDE.md
+ * is data, not an instruction), caps it at MAX_MEMORY_BYTES, and (1.184) auto-prepends a TRUSTED framing line. We just
+ * return the content.
+ *
+ * 🔴 HOST/FILE LANE ONLY. The ctx hands us only `cwd` (a string) — NO executionEnv instance and NO sessionId. So we can
+ * read with the worker's own `fs`/`execFile` ONLY when cwd is a LOCAL path (the host lane). On a remote sandbox lane
+ * (e2b/k8s/ssh/adb/local-docker) cwd lives in the container — the worker can't read it, and there's no env handle in
+ * the ctx to exec through — so main.ts only wires this on the host lane; here we defensively re-check (stat the dir).
+ */
 import { promises as fs, constants as fsConstants } from "node:fs";
 import { execFile } from "node:child_process";
 import { createHmac, randomBytes } from "node:crypto";
 import { isAbsolute, join, sep } from "node:path";
 import { scrubSecretEnv } from "@sema-agent/core";
 import { redactSecrets } from "./trace/redact.js";
+/** The instruction-file name chain (core 1.302 S-1): AGENTS.md wins, CLAUDE.md is the fallback, then the
+ *  `.claude/` nested form. The FIRST hit is the single declared instruction source. */
 const INSTRUCTION_FILE_CHAIN = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];
+/** One byte budget shared by the loader AND the probe — the fingerprint is sha256 over the first
+ *  `INSTRUCTION_READ_CAP` raw bytes, so both sides MUST read the same bounded window or every probe
+ *  would report a phantom change. (Consequence: an edit past the cap is invisible to the probe —
+ *  honest limit of the bounded-read design, same reason the injected content is capped.) */
 const INSTRUCTION_READ_CAP = 24 * 1024;
+/** Cap a string to a byte budget on a UTF-8 character boundary (never split a multi-byte char). */
 function capUtf8(s, maxBytes) {
     const buf = Buffer.from(s, "utf8");
     if (buf.length <= maxBytes)
         return s;
     let end = maxBytes;
+    // back off to a UTF-8 lead byte (0xxxxxxx or 11xxxxxx) so we don't slice mid-character
     while (end > 0 && (buf[end] & 0xc0) === 0x80)
         end -= 1;
     return buf.subarray(0, end).toString("utf8");
 }
+/** Bounded raw read of an ABSOLUTE path (lstat symlink gate → first `maxBytes` bytes). The shared primitive
+ *  under both the loader and `makeProbeInstructionSources` — one read posture, one fingerprint. */
 async function readRawCapped(target, maxBytes, truncatedFlag = { v: false }) {
     let fh;
     try {
+        // Symlink containment: a `CLAUDE.md` symlink must NOT read an arbitrary file outside the repo (double-review #3).
+        // 🔴 win32 真机(S6, 2026-07-04): `fsConstants.O_NOFOLLOW` is UNDEFINED on Windows Node, so `O_RDONLY | undefined`
+        // silently collapses to `O_RDONLY` (0) — the flag is a no-op and the symlink IS followed (verified: read out the
+        // outside file). O_NOFOLLOW only exists/atomically-enforces on POSIX. So gate portably with an explicit lstat
+        // symlink-reject: authoritative on win32 (where the open-flag can't enforce it), belt-and-suspenders on POSIX.
         const lst = await fs.lstat(target);
         if (lst.isSymbolicLink())
-            return null;
+            return null; // a symlinked CLAUDE.md → refuse (no arbitrary-file read), same as O_NOFOLLOW → ELOOP
         if (lst.size > maxBytes)
-            truncatedFlag.v = true;
+            truncatedFlag.v = true; // S23: cap fired — surfaced as claudeTruncated on the injection event
+        // Keep O_NOFOLLOW in the flags too: on POSIX it closes the tiny lstat→open TOCTOU window atomically; on win32 it's
+        // a harmless 0. BOUNDED read of the first maxBytes bytes — never buffer the whole file, so a 50MB/hostile CLAUDE.md
+        // can't amplify memory (double-review #2: the old fs.readFile loaded the WHOLE file before capping).
         fh = await fs.open(target, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
         const buf = Buffer.allocUnsafe(maxBytes);
         const { bytesRead } = await fh.read(buf, 0, maxBytes, 0);
         return buf.subarray(0, bytesRead);
     }
     catch {
-        return null;
+        return null; // ENOENT / EISDIR / ELOOP (a symlink, rejected by O_NOFOLLOW) / EACCES — absent or unreadable → no content
     }
     finally {
         await fh?.close();
     }
 }
+/** Keyed fingerprint over the RAW bounded-read window (pre-capUtf8 bytes — the ①"cap 前原始字节" contract).
+ *  KEYED, not a plain digest (self-review, information-surface lens): core puts the short form of this
+ *  fingerprint into the MODEL-VISIBLE instructions-change notice and the steering trace — a plain sha256
+ *  of the raw bytes would let anyone holding a known template dictionary-compare low-entropy controlled
+ *  fields against the digest. A per-process random key makes the digest correspond to nothing outside
+ *  this process. Loader and probe share THIS one function (any split would fabricate phantom "changed"
+ *  signals); sources are re-declared at every prepare in the declaring process, so a restart (new key)
+ *  never gets compared against old fingerprints. */
 const INSTRUCTION_HASH_KEY = randomBytes(16);
 function instructionHash(raw) {
     return `hmac-sha256:${createHmac("sha256", INSTRUCTION_HASH_KEY).update(raw).digest("hex")}`;
 }
+/** The "declared absent, watched for appearance" fingerprint for higher-priority chain members —
+ *  core 1.310 ([1006]①) widened `instructionSources[].contentHash` to `string | null`, so this is a
+ *  plain typed null (an appearing file renders as `hash absent → <hash>` in the change notice). */
 const ABSENT_HASH = null;
+/** Recover (root, rel) for a path the LOADER declared — every declared path is `root + one chain member`,
+ *  so the chain suffix identifies the split unambiguously. The probe needs this to re-run the loader's
+ *  parent-directory symlink gate each round (self-review: the probe checked only the final component, so
+ *  swapping `.claude` for a symlink out of the repo MID-RUN made the probe fingerprint an outside file). */
 function chainCoordinates(absPath) {
+    // LONGEST suffix wins: `…/.claude/CLAUDE.md` also ends with the bare `/CLAUDE.md` — matching in chain
+    // order would split off `.claude` into the root and skip the parent gate entirely (caught by the test).
     let best = null;
     for (const rel of INSTRUCTION_FILE_CHAIN) {
         const suffix = sep + rel.split("/").join(sep);
@@ -50,6 +99,11 @@ function chainCoordinates(absPath) {
     }
     return best && { root: best.root, rel: best.rel };
 }
+/** Reject a symlink on ANY intermediate directory of `rel` under root (adversarial review F2): the final
+ *  component's lstat/O_NOFOLLOW can't see a `.claude` DIRECTORY that is itself a symlink out of the repo
+ *  (e.g. → ~/.claude) — the target file there lstat's as a plain file and would be read and injected.
+ *  Same TOCTOU honesty as the final-component gate: the lstat→open window on a swapped intermediate dir
+ *  is accepted (a local attacker with user rights can read the target directly anyway). */
 async function hasSymlinkedParent(root, rel) {
     const parts = rel.split("/").slice(0, -1);
     let cur = root;
@@ -61,30 +115,60 @@ async function hasSymlinkedParent(root, rel) {
     }
     return false;
 }
+/** Run a fixed git subcommand under root with execFile (argv array → NO shell → no injection), timeout + maxBuffer.
+ *  🔴 The repo's own `.git/config` can otherwise STEER these read-only calls into code execution — double-review proved
+ *  `core.fsmonitor=<prog>` runs `<prog>` on `git status` (auto-fires on every prepare in a hostile working dir). We
+ *  neutralize the exec-config inlets: `-c core.fsmonitor=false -c core.hooksPath=/dev/null` override the repo's values,
+ *  and GIT_CONFIG_GLOBAL/SYSTEM=/dev/null drop the global/system config so a planted one can't inject either. */
 function git(root, args, maxBytes) {
     const safeArgs = ["-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", ...args];
     return new Promise((res) => {
-        execFile("git", safeArgs, { cwd: root, timeout: 5000, maxBuffer: maxBytes, env: { ...scrubSecretEnv(process.env), GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null" } }, (err, stdout, stderr) => {
+        execFile("git", safeArgs, 
+        // scrubSecretEnv: a git hook / credential helper must not see the orchestrator's *_KEY/*_TOKEN/*_SECRET env.
+        // GIT_CONFIG_GLOBAL/SYSTEM=/dev/null: ignore ~/.gitconfig + /etc/gitconfig so a planted exec-config can't steer us.
+        { cwd: root, timeout: 5000, maxBuffer: maxBytes, env: { ...scrubSecretEnv(process.env), GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null" } }, (err, stdout, stderr) => {
             if (!err)
                 return res({ out: stdout.trim() });
+            // S23: the git narrative used to vanish with zero fingerprint — classify why (→ gitDropReason).
             const e = err;
             const fail = e.killed ? "timeout" : e.code === "ENOENT" ? "git-missing" : /not a git repository/i.test(String(stderr)) ? "non-repo" : /maxBuffer/i.test(String(e.message)) ? "maxbuffer" : "error";
             res({ out: "", fail });
         });
     });
 }
+/**
+ * Build a `loadProjectMemory` for the host lane. Returns null (skip) unless hands are enabled AND cwd is a local
+ * directory. Reads the instruction-file chain (AGENTS.md → CLAUDE.md → .claude/CLAUDE.md, S-1) + (non-subagent)
+ * `git log -5` / `git status`, redacts secrets, and caps the total. A subagent gets a trimmed instruction file and
+ * no git narrative (cost control, H7). When an instruction file is hit the return is a `ProjectMemoryLoad`
+ * declaring it in `instructionSources` (path + sha256 over the raw bounded-read window) so core's
+ * instructions-change lane can probe it mid-run.
+ *
+ * Session snapshot cache (S-2): keyed on ctx.sessionId — a session keeps ONE stable instruction snapshot
+ * (mid-run file edits surface via the probe as tail attachments, never a silently re-rendered prefix).
+ * `phase: "post-compact"` forces a re-read (core re-renders the prefix there anyway). No entry for
+ * sessionless one-shot runs. (post-clear never arrives from core — RB-9 — so it is not a cache key here.)
+ */
 export function makeLoadProjectMemory(opts) {
-    const totalCap = opts.maxBytes ?? 32 * 1024;
+    const totalCap = opts.maxBytes ?? 32 * 1024; // service self-cap, tighter than core's 100KiB MAX_MEMORY_BYTES backstop
     const claudeCap = INSTRUCTION_READ_CAP;
     const subagentClaudeCap = 4 * 1024;
     const gitCap = 8 * 1024;
     const cache = new Map();
     const CACHE_MAX = opts.cacheMax ?? 256;
     return async (ctx) => {
+        // All gates that decide WHETHER anything loads run BEFORE the cache (F3): a hands-less or bad-cwd call
+        // must answer null itself, never serve (or seed) a session slot it wasn't allowed to read.
         if (!ctx.handsEnabled)
-            return null;
+            return null; // hands-less chat: no real project (H4)
         if (!isAbsolute(ctx.cwd))
             return null;
+        // Canonicalize through the FILESYSTEM, not lexically (self-review, information-surface lens): a
+        // lexical resolve() keeps symlinks and case aliases distinct — a symlinked cwd re-pointed at another
+        // project would keep hitting the OLD slot and serve project A's instruction snapshot inside project B,
+        // and a case alias would silently split one project across two slots. realpath is both the cache key
+        // AND the read root, so key and content can never disagree. Unresolvable cwd (gone/unreadable) → null,
+        // the same answer doLoad's stat gate would give.
         let root;
         try {
             root = await fs.realpath(ctx.cwd);
@@ -92,17 +176,26 @@ export function makeLoadProjectMemory(opts) {
         catch {
             return null;
         }
+        // Subagents share the parent's project but get a differently-capped view — never let the two shapes
+        // poison one cache slot; the subagent leg just stays uncached (cheap, trimmed read).
         const cacheKey = ctx.sessionId && !ctx.isSubagent ? `${ctx.sessionId}\u0000${root}` : undefined;
         if (cacheKey) {
             const hit = cache.get(cacheKey);
             if (hit && ctx.phase !== "post-compact")
                 return hit.load;
+            // Post-compact single-flight (codex lens-1 remainder): two post-compact calls on one slot must share
+            // ONE fresh read — each starting its own would leave the surviving snapshot dependent on launch
+            // order. An in-flight entry that was ITSELF started post-compact is that generation's read (the
+            // settle window is milliseconds; a next compaction landing inside it joins the same read — accepted).
             if (hit && !hit.settled && hit.phase === "post-compact")
                 return hit.load;
         }
         const load = doLoad(ctx, root);
         if (cacheKey) {
             if (cache.size >= CACHE_MAX && !cache.has(cacheKey)) {
+                // Evict the oldest SETTLED entry only (codex lens-1 remainder): deleting an in-flight promise
+                // orphans its read (the key's next call starts a second one). No settled entry → allow a
+                // temporary over-cap; loads settle in milliseconds, so the map stays bounded in practice.
                 for (const [k, e] of cache) {
                     if (e.settled) {
                         cache.delete(k);
@@ -112,6 +205,10 @@ export function makeLoadProjectMemory(opts) {
             }
             const entry = { load, settled: false, phase: ctx.phase };
             cache.set(cacheKey, entry);
+            // Release-review finding: a burst of >CACHE_MAX concurrent DISTINCT loads sails past the insert-time
+            // eviction (nothing settled to evict yet) and, without this, the map would stay at the burst's
+            // high-water mark forever (each later insert evicts exactly one settled entry, net zero). Trim back
+            // down to the cap as loads settle — oldest settled first, in-flight entries always survive.
             const trimSettled = () => {
                 if (cache.size <= CACHE_MAX)
                     return;
@@ -128,6 +225,9 @@ export function makeLoadProjectMemory(opts) {
                 trimSettled();
             }, () => {
                 entry.settled = true;
+                // A rejected load must not poison the slot (doLoad catches everything today; belt for future
+                // edits). Guard the delete on identity (codex lens-1): an OLD generation's failure must not
+                // evict the NEWER entry that a post-compact refresh has already installed in the same slot.
                 if (cache.get(cacheKey) === entry)
                     cache.delete(cacheKey);
                 trimSettled();
@@ -138,7 +238,12 @@ export function makeLoadProjectMemory(opts) {
     async function doLoad(ctx, root) {
         const st = await fs.stat(root).catch(() => null);
         if (!st?.isDirectory())
-            return null;
+            return null; // remote-lane cwd not present locally, or a bad path → skip
+        // S-1 file-name chain: first hit wins and is the ONE declared instruction source.
+        // Consistent-snapshot selection (codex lens-1 remainder): the chain walk is not atomic — a
+        // higher-priority file created between "checked absent" and "picked the fallback" would silently
+        // lose to the fallback until a post-compact reload. After a non-top pick, re-verify the members
+        // above it; an appearance redoes the walk (bounded — after the retries the last pick stands).
         const claudeTrunc = { v: false };
         let claudeRaw = null;
         let hitFile;
@@ -153,7 +258,7 @@ export function makeLoadProjectMemory(opts) {
             for (let i = 0; i < INSTRUCTION_FILE_CHAIN.length; i++) {
                 const rel = INSTRUCTION_FILE_CHAIN[i];
                 if (rel.includes("/") && (await hasSymlinkedParent(root, rel)))
-                    continue;
+                    continue; // F2: a symlinked .claude dir escapes the repo
                 const raw = await readRawCapped(join(root, rel), claudeCap, claudeTrunc);
                 if (raw !== null) {
                     claudeRaw = capUtf8(raw.toString("utf8"), claudeCap);
@@ -164,10 +269,11 @@ export function makeLoadProjectMemory(opts) {
                 }
             }
             if (hitIndex <= 0)
-                break;
+                break; // top pick or nothing found: no higher-priority member to re-verify
             let appeared = false;
             for (const rel of INSTRUCTION_FILE_CHAIN.slice(0, hitIndex)) {
                 const higher = await fs.lstat(join(root, rel)).catch(() => null);
+                // A symlink would be REFUSED by the read gate — its appearance is not a better pick.
                 if (higher && !higher.isSymbolicLink()) {
                     appeared = true;
                     break;
@@ -177,9 +283,9 @@ export function makeLoadProjectMemory(opts) {
                 break;
         }
         const claude = ctx.isSubagent && claudeRaw ? capUtf8(claudeRaw, subagentClaudeCap) : claudeRaw;
-        const claudeTruncated = claudeTrunc.v || Boolean(ctx.isSubagent && claudeRaw && Buffer.byteLength(claudeRaw, "utf8") > subagentClaudeCap);
+        const claudeTruncated = claudeTrunc.v || Boolean(ctx.isSubagent && claudeRaw && Buffer.byteLength(claudeRaw, "utf8") > subagentClaudeCap); // S23
         let gitNarrative = "";
-        let gitOk = true;
+        let gitOk = true; // S23: subagent (git not attempted) stays ok=absent-by-design
         let gitDropReason;
         if (!ctx.isSubagent) {
             const [log, status] = await Promise.all([
@@ -192,22 +298,33 @@ export function makeLoadProjectMemory(opts) {
             if (log.out)
                 parts.push(`## Recent commits\n${log.out}`);
             if (status.out)
-                parts.push(`## Working tree\n${status.out.split("\n").slice(0, 40).join("\n")}`);
+                parts.push(`## Working tree\n${status.out.split("\n").slice(0, 40).join("\n")}`); // bound the dirty list
             gitNarrative = parts.join("\n\n");
         }
         const sections = [];
         if (claude && hitFile)
-            sections.push(`# ${hitFile}\n${claude}`);
+            sections.push(`# ${hitFile}\n${claude}`); // heading = the REAL file name (S-1)
         if (gitNarrative)
             sections.push(gitNarrative);
         if (sections.length === 0)
             return null;
+        // redact secrets BEFORE capping (a key must not survive into the injected context, where a tool could exfil it).
         const redacted = redactSecrets(sections.join("\n\n"));
         const capped = capUtf8(redacted, totalCap);
+        // S23: gitOk/gitDropReason/claudeTruncated — a silently-emptied narrative now has a fingerprint here.
+        // cacheSize: the snapshot cache's population at THIS load (bound observability — the settle-time trim
+        // keeps it ≤ the cap once in-flight bursts settle; also what the deterministic trim test asserts).
         opts.logger?.debug?.("project_memory_loaded", { cwd: root, bytes: Buffer.byteLength(capped, "utf8"), isSubagent: ctx.isSubagent, gitOk, ...(gitDropReason ? { gitDropReason } : {}), claudeTruncated, ...(hitFile ? { instructionFile: hitFile } : {}), ...(ctx.phase ? { phase: ctx.phase } : {}), cacheSize: cache.size });
         if (!capped)
             return null;
+        // Declare the instruction source (①): absolute path + fingerprint. The hash is over the PRE-redaction,
+        // pre-cap raw window — the probe re-reads the file itself, so the fingerprint must be file-derived, not
+        // derived from the redacted/assembled injection text.
         if (hitFile && hitHash) {
+            // Watch the chain members ABOVE the pick too (codex lens-1 remainder): core's change lane only
+            // probes DECLARED paths, so a higher-priority file appearing mid-run would otherwise never produce
+            // a signal until a post-compact reload. Absent members are pre-declared with the runtime's
+            // "absent" hash (ABSENT_HASH note) — appearance renders as `hash absent → <hash>` in the notice.
             return {
                 content: capped,
                 instructionSources: [
@@ -219,15 +336,27 @@ export function makeLoadProjectMemory(opts) {
         return capped;
     }
 }
+/**
+ * ② The `RunnerDeps.probeInstructionSources` seam: re-fingerprint the declared instruction files mid-run so
+ * core's instructions-change lane can append a tail attachment when one changes. Same read posture as the
+ * loader (lstat symlink gate → bounded read of the first `INSTRUCTION_READ_CAP` bytes → sha256) — any drift
+ * here would fabricate phantom "changed" signals every turn. Per-source failure → `contentHash: null`
+ * (source gone/unreadable); any unexpected top-level failure → `null` (probe abstains; core also races this
+ * against a 2s ceiling and treats a throw as null, but we stay honest on our side of the seam).
+ */
 export function makeProbeInstructionSources() {
     return async (sources) => {
         try {
             return await Promise.all(sources.map(async ({ path }) => {
                 if (!isAbsolute(path))
-                    return { path, contentHash: null };
+                    return { path, contentHash: null }; // we only ever declare absolute paths
+                // Re-run the loader's parent-directory symlink gate EVERY round (self-review: the probe checked
+                // only the final component, so swapping `.claude` for a symlink out of the repo mid-run made the
+                // probe fingerprint an outside file — and its short form reaches the model-visible notice).
+                // Declared paths are always root+chain-member, so the coordinates are recoverable from the path.
                 const coords = chainCoordinates(path);
                 if (coords && coords.rel.includes("/") && (await hasSymlinkedParent(coords.root, coords.rel))) {
-                    return { path, contentHash: null };
+                    return { path, contentHash: null }; // swapped-in symlinked parent → refuse, same as the loader
                 }
                 const raw = await readRawCapped(path, INSTRUCTION_READ_CAP);
                 return { path, contentHash: raw === null ? null : instructionHash(raw) };

package/dist/prompts-domain-validate.d.ts

@@ -1,10 +1,21 @@
 import { type PromptTextDeclaration, type PublishedPromptArtifactEnvelope } from "@sema-agent/core";
+/** [1057]⓪ 下发形(remote effective 的 additive key,JSON verbatim 面——不经 registry-core parse,所以
+ *  cli 补位前 center 发的 `contentHash` 也原样到达)。 */
 export interface EffectiveCenterPrompts {
+    /** `center:<contentDigest 前 12>` — 纯内容寻址(同内容重发布=同 packId,epoch 不误重 pin)。 */
     packId: string;
+    /** canonical JSON 全量 sha256(非盐化,operator 对账位 [1050]②)。 */
     contentDigest: string;
+    /** covering 已在 center 走完的基线终形(层信息不下发,worker 零解析义务)。 */
     sections: PromptTextDeclaration[];
+    /** per-scenario 完整重算终形(整包替换基线,非增量);无键=用基线。 */
     scenarioOverrides?: Record<string, PromptTextDeclaration[]>;
 }
+/**
+ * 结构判形(防炸底线,非语义复检)。`ok:false` 时调用方拒绝采用该候选的 prompts 面并 warn——绝不让
+ * 一个坏 pack 把每个任务的 prepare 炸掉。校验与 core assemble 的 THROW 条件同形(id 规范/长度/core/
+ * 保留、slot 闭集)+ 下发信封两键形;`contentHash` 只查形(值的校验归 core 1.315,错值 core 丢弃+warn)。
+ */
 export declare function validateCenterPrompts(raw: unknown): {
     ok: true;
     value: EffectiveCenterPrompts;
@@ -12,13 +23,30 @@ export declare function validateCenterPrompts(raw: unknown): {
     ok: false;
     error: string;
 };
+/** core 引擎版本(verifyPromptArtifact 的 compatibleCore range 输入)——经 exports map 解析包根读
+ *  package.json(`require('@sema-agent/core/package.json')` 被 exports 封死,ERR_PACKAGE_PATH_NOT_EXPORTED
+ *  第一手教训)。解析失败回 "0.0.0" = range-gated artifact 被诚实拒(fail-closed 响,绝不静默采用)。 */
 export declare const CORE_ENGINE_VERSION: string;
+/** validatePromptsDomain 的归一产物:两轴的已判形面 + 变更检测身份(adopt 去重键,跨轴稳定)。 */
 export interface PromptsDomainFaces {
+    /** A 形(declaration 轴)——centerPromptProvider 继续消费(现行链路零改动)。 */
     declarations?: EffectiveCenterPrompts;
+    /** B 形(catalog 轴)——core S1 verify 已过(digest 复算/上限/range 全管线);server 不解释内容,
+     *  原样交 core artifact 仓(e/b 班车接线位)。 */
     catalog?: PublishedPromptArtifactEnvelope;
+    /** 采用去重键:两轴 digest 拼接(轴缺席记 "-")。 */
     identity: string;
+    /** 观测面([985]a §3:`center_prompts_adopted` 增 axes,看两轴共存窗)。 */
     axes: Array<"declarations" | "catalog">;
 }
+/**
+ * prompts 域候选门 v2(validateCenterPrompts 的双轴升级;整拒语义不变=任一在场轴坏形 ⇒ 整个 prompts
+ * 面拒绝采用,LKG/内置继续服务)。两形都认:
+ *  - legacy 平铺(无 schemaVersion 键)= declaration 轴单轴(存量 center 停发平铺前的兼容窗);
+ *  - `{schemaVersion:1, declarations?, catalog?}`(registry-core `EffectivePromptsWire`)= 至少一轴。
+ * catalog 轴的语义权威=core `verifyPromptArtifact`(形/digest 逐位复算/ARTIFACT_LIMITS/compatibleCore
+ * range 全在 core 一处——[1242]③ a 解,上限单真源永不漂)。
+ */
 export declare function validatePromptsDomain(raw: unknown): {
     ok: true;
     value: PromptsDomainFaces;

package/dist/prompts-domain-validate.js

@@ -1,9 +1,22 @@
+/**
+ * prompts 域候选门(判形)——从 capabilities/center-prompts.ts **下沉**的中立叶子(design/158 S6,
+ * lens2 §G:`config-lkg.ts → capabilities/center-prompts.ts` 是全仓唯一一条显式分层反向边,config 层
+ * 值 import capabilities 层)。本模块只依赖 node 内置 + `@sema-agent/core`,不依赖 capabilities/
+ * config 任何东西,config-lkg(LKG 读侧复判)与 capabilities(候选门)同引即无反向边。
+ * center-prompts.ts 原位置 re-export 保兼容,语义/文案零改动——逐字搬运。
+ *
+ * ─── 以下为原 center-prompts.ts 的判形半场,注释原样保留 ───
+ *
+ * 本模块仅有的一层「形校验」不是语义复检,是**防炸底线**:core 对坏形声明的守卫是 THROW(assemble 期),
+ * 一个坏 pack 会让每个任务 prepare 炸掉——server 在采用前做结构判形,坏形=拒绝采用该候选的 prompts 面
+ * (warn 点名,沿用上一个好的/内置),任务面永不因配置坏形而全灭(config 候选门同精神,只作用于本域)。
+ */
 import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { verifyPromptArtifact } from "@sema-agent/core";
-const ID_RE = /^[a-z0-9][a-z0-9/._-]*$/;
+const ID_RE = /^[a-z0-9][a-z0-9/._-]*$/; // core assemble 同形(≤128、非 core/ 前缀在下面单查)
 const SLOTS = new Set(["identity", "scenario", "behavior"]);
 const HASH_RE = /^sha256:[0-9a-f]{64}$/;
 function declarationIssue(d, where) {
@@ -18,6 +31,10 @@ function declarationIssue(d, where) {
         return `${where}: bad slot`;
     if (typeof o.text !== "string" || o.text.length === 0)
         return `${where}: text must be a non-empty string`;
+    // 发版复审(1.224 批)F1:contentHash **必备且重算比对**——core 的 epoch 声明轴用 (id,slot,chars,
+    // contentHash?),hash 缺席/被 core 丢弃(错值)后**同长度文本编辑不改 artifactDigest=不重 pin**,
+    // 恰是撤 restart 臂所依赖的审计不变量被击穿。center 链路恒逐 section 铸([1065]),正常路径零影响;
+    // 这里拒的是坏发布/被改载荷(整拒候选,LKG/内置继续服务)。
     if (typeof o.contentHash !== "string" || !HASH_RE.test(o.contentHash))
         return `${where}: contentHash is required (sha256:<64hex> — the epoch declaration axis needs it for byte-level change detection)`;
     const expected = `sha256:${createHash("sha256").update(o.text).digest("hex")}`;
@@ -25,6 +42,11 @@ function declarationIssue(d, where) {
         return `${where}: contentHash does not match sha256(text) — stale or tampered declaration`;
     return undefined;
 }
+/**
+ * 结构判形(防炸底线,非语义复检)。`ok:false` 时调用方拒绝采用该候选的 prompts 面并 warn——绝不让
+ * 一个坏 pack 把每个任务的 prepare 炸掉。校验与 core assemble 的 THROW 条件同形(id 规范/长度/core/
+ * 保留、slot 闭集)+ 下发信封两键形;`contentHash` 只查形(值的校验归 core 1.315,错值 core 丢弃+warn)。
+ */
 export function validateCenterPrompts(raw) {
     if (raw === null || typeof raw !== "object")
         return { ok: false, error: "prompts is not an object" };
@@ -33,6 +55,11 @@ export function validateCenterPrompts(raw) {
         return { ok: false, error: "bad packId form (center:<digest12>)" };
     if (typeof p.contentDigest !== "string" || !HASH_RE.test(p.contentDigest))
         return { ok: false, error: "bad contentDigest form" };
+    // 发版复审 F2/F4 两条硬化:
+    //  - 数组内 id 必须唯一(core composer 对 duplicate section id 是 THROW——独立判形查不出对撞,必须
+    //    整数组查重;基线与各 override 互不查——override 整包替换,不同数组不共存于一次装配);
+    //  - 空数组=坏形拒绝(F4:wire 契约是「整包替换终形」,空数组语义未定义——「显式清空场景」不是 v1
+    //    用例,静默把空重解释为「回落内置」会跑出与 center 发布物不同的提示词;语义决定权推回 center)。
     const arrayIssue = (decls, where) => {
         if (!Array.isArray(decls))
             return `${where} is not an array`;
@@ -65,6 +92,10 @@ export function validateCenterPrompts(raw) {
     }
     return { ok: true, value: raw };
 }
+// ═══ 双轴门(a 实现班车,[985]a/[1242]/[1248] 过轮定稿;registry-core 0.10.20 同班车)═══
+/** core 引擎版本(verifyPromptArtifact 的 compatibleCore range 输入)——经 exports map 解析包根读
+ *  package.json(`require('@sema-agent/core/package.json')` 被 exports 封死,ERR_PACKAGE_PATH_NOT_EXPORTED
+ *  第一手教训)。解析失败回 "0.0.0" = range-gated artifact 被诚实拒(fail-closed 响,绝不静默采用)。 */
 export const CORE_ENGINE_VERSION = (() => {
     try {
         const entry = createRequire(import.meta.url).resolve("@sema-agent/core");
@@ -74,6 +105,14 @@ export const CORE_ENGINE_VERSION = (() => {
         return "0.0.0";
     }
 })();
+/**
+ * prompts 域候选门 v2(validateCenterPrompts 的双轴升级;整拒语义不变=任一在场轴坏形 ⇒ 整个 prompts
+ * 面拒绝采用,LKG/内置继续服务)。两形都认:
+ *  - legacy 平铺(无 schemaVersion 键)= declaration 轴单轴(存量 center 停发平铺前的兼容窗);
+ *  - `{schemaVersion:1, declarations?, catalog?}`(registry-core `EffectivePromptsWire`)= 至少一轴。
+ * catalog 轴的语义权威=core `verifyPromptArtifact`(形/digest 逐位复算/ARTIFACT_LIMITS/compatibleCore
+ * range 全在 core 一处——[1242]③ a 解,上限单真源永不漂)。
+ */
 export function validatePromptsDomain(raw) {
     if (raw === null || typeof raw !== "object")
         return { ok: false, error: "prompts is not an object" };
@@ -100,6 +139,8 @@ export function validatePromptsDomain(raw) {
         const c = verifyPromptArtifact(w.catalog, { engineVersion: CORE_ENGINE_VERSION });
         if (!c.ok)
             return { ok: false, error: `catalog axis: ${c.code}: ${c.reason}` };
+        // verify 返回的是重建后的 typed artifact;wire 上的 envelope 原样保留(sourceRevision 不进 digest,
+        // e/b 接线时 core artifact 仓吃 envelope 全形)。
         value.catalog = w.catalog;
         value.axes.push("catalog");
     }

package/dist/question.d.ts

@@ -1,10 +1,19 @@
 import { type AskQuestionRequest, type QuestionAnswer, type AskQuestion } from "@sema-agent/core";
+/** A live question frame delivered to whoever tails this run's stream. `type` IS the SSE event name (mirrors the
+ *  named-event convention; the payload also carries `type` so a proxy that strips event names still works). The shell
+ *  renders `question` as a dialog and dismisses on `question_complete`. */
 export interface QuestionFrame {
     type: "question" | "question_complete";
     questionId: string;
+    /** "question" only: the model's structured questions, secret-redacted. UNTRUSTED-for-display (shell renders; never
+     *  re-feeds a model). Absent on an over-cap payload (the ask then headless-defaults). */
     questions?: AskQuestion[];
+    /** "question_complete" only: whether the human answered (`answered`) or the ask was released unanswered
+     *  (`unanswered` — ttl/abort → the model got the headless default). Cosmetic dialog-dismiss. */
     outcome?: "answered" | "unanswered";
 }
+/** The per-run context `onQuestion` recovers via ALS. `emit` delivers a frame to the run's live stream; `abortSignal`
+ *  (the run's own cancel signal) releases a question parked awaiting a human when the run aborts. */
 export interface QuestionRunContext {
     taskId: string;
     owner: string | null;
@@ -12,11 +21,17 @@ export interface QuestionRunContext {
     abortSignal?: AbortSignal;
 }
 export interface QuestionThrottle {
+    /** Max concurrent in-flight questions per run leg (parallel tool calls can each ask). Breach ⇒ headless default. */
     maxConcurrentPerRun: number;
+    /** Max total questions one run leg surfaces to the human. Breach ⇒ headless default (flood defense). */
     maxTotalPerRun: number;
+    /** An unanswered question auto-releases (headless default) after this (ms) — the human walked away; don't hold core. */
     ttlMs: number;
 }
 export declare const DEFAULT_QUESTION_THROTTLE: QuestionThrottle;
+/** Validate the respond body = core's {@link QuestionAnswer}. `selected`/`note` are OPAQUE passthrough (core fences
+ *  them: `selected ⊆ options`, `note` untrusted-fenced) — we validate only the outer SHAPE (answers[] of {header,
+ *  selected:string[], note?}), never the option semantics. */
 export declare function parseQuestionResponse(body: unknown): {
     ok: true;
     value: QuestionAnswer;
@@ -24,19 +39,37 @@ export declare function parseQuestionResponse(body: unknown): {
     ok: false;
     error: string;
 };
+/** @deprecated design/158 N22: renamed to {@link parseQuestionResponse} — unifies the HITL trio's parse-fn
+ *  vocabulary (`parseQuestionResponse` / `parseElicitationResponse` / `parseToolApprovalResponse`, all "the
+ *  human's reply body"). Kept as a compat alias. */
 export declare const parseQuestionAnswer: typeof parseQuestionResponse;
+/**
+ * Coordinates AskUserQuestion HITL for the singleton runner. Process-local + same-replica (the pending map is in memory,
+ * like ElicitationCoordinator / steerableRuns): a respond that lands on another replica finds nothing → 404. Present
+ * (passed into `RunnerDeps.onQuestion` + the respond route) ONLY when `ASK_QUESTION_ENABLED` — absent ⇒ core mounts the
+ * AskUserQuestion tool with the headless default (a run never hangs; the model just can't get a live answer).
+ */
 export declare class QuestionCoordinator {
     private readonly als;
     private readonly pending;
     private readonly counters;
     private readonly throttle;
     constructor(throttle?: QuestionThrottle);
+    /** Run `fn` with the per-run question context ambient. On exit, release any still-pending question for this run (a
+     *  live-only question cannot outlive its leg → headless default) and drop the run's counters (no leak). */
     runWithContext<T>(ctx: QuestionRunContext, fn: () => Promise<T>): Promise<T>;
+    /** `RunnerDeps.onQuestion`. core calls this when the agent's AskUserQuestion tool fires; the resolved answer is what
+     *  the model sees. Headless default (`NO_HUMAN`) in every case with no live human, so the run never hangs. Arrow
+     *  property so it can be passed as `onQuestion: coordinator.question` with `this` bound. */
     question: (req: AskQuestionRequest, signal?: AbortSignal) => Promise<QuestionAnswer>;
+    /** `POST /v1/questions/:id/respond` — resolve a parked question with the shell's answer. Owner-gated with a 404 (no
+     *  existence oracle): a non-owner AND an unknown id (answered / expired / wrong replica) both get 404. Returns the
+     *  HTTP {status, body}; the HTTP layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling. */
     respond(id: string, principal: string | undefined, body: unknown): {
         status: number;
         body: unknown;
     };
+    /** Test/observability hook: number of currently-parked questions. */
     pendingCount(): number;
     private countersFor;
 }