@sema-agent/core 5.35.0 → 5.37.0

package/dist/core/runner/git-status-frame.d.ts

@@ -0,0 +1,219 @@
+import type { AgentMessage, ExecutionEnv, GitAnnouncementKind, SessionTreeEntry } from "../../internal/harness-types.js";
+/** Bound into the hash domain: bump when the frame's wording/structure changes so the upgraded
+ *  renderer re-announces on its first leg instead of being suppressed by a pre-upgrade hash. */
+export declare const GIT_STATUS_FRAME_FORMAT_VERSION = 1;
+/**
+ * The frame's own first paragraph (replaces the CC "will not update during the conversation" head,
+ * which would be FALSE under the frame protocol). Wording obligations: self-declares the update
+ * semantics (latest frame supersedes earlier ones), promises re-send on VISIBLE-view change only
+ * (truncation-bound honesty), and "observed while preparing" does not claim an atomic instant (the
+ * probe is two shell round-trips and a write can land between them).
+ */
+export declare const GIT_STATUS_FRAME_PREAMBLE = "This is the git status observed while preparing this request. When the visible snapshot changes it will be re-sent in a later message \u2014 the most recent git status frame supersedes earlier ones.";
+/** Tombstone body — the probes could not reach git at all while earlier frames announced a
+ *  positive view (sent once, on the availability flip edge only). */
+export declare const GIT_STATUS_UNAVAILABLE_BODY = "Git status is currently unavailable; the most recent git status frame above may be stale.";
+/** Tombstone body — the directory stopped being a git repository while earlier frames announced a
+ *  positive view (sent once, on the flip edge; the env block's static is-repo line flips the same leg). */
+export declare const GIT_STATUS_NON_REPO_BODY = "The working directory is no longer a git repository; earlier git status frames no longer apply.";
+/** The `steering_injected` echo previews for the frame — CONSTANT wordings on purpose: branch and
+ *  status text are repo-controlled and must not enter the event telemetry plane through the echo. */
+export declare const GIT_STATUS_ECHO_PREVIEW: Record<GitAnnouncementKind, string>;
+/** The raw material of one probe cycle, as prepare-task resolved it (§4.3 unified ladder):
+ *  - `full`     — §E14 and the H4 snapshot both succeeded: `snapshot` = the pre-rendered
+ *                 {@link import("../../prompts/default.js").buildGitSnapshot} block (CC template,
+ *                 sanitized + bounded by its renderer);
+ *  - `degraded` — §E14 yielded git facts but the H4 snapshot failed (exit 41/42, timeout, sentinel
+ *                 mis-split): branch + dirtiness are all that is honestly known;
+ *  - `unavailable` — the §E14 probe itself failed (git facts unknowable this leg);
+ *  - `non-repo` — the probe ran and the cwd is not a git repository. */
+export type GitStatusProbeOutcome = {
+    kind: "full";
+    snapshot: string;
+} | {
+    kind: "degraded";
+    branch?: string;
+    dirty?: boolean;
+} | {
+    kind: "unavailable";
+} | {
+    kind: "non-repo";
+};
+/** Render the frame BODY (the text inside the `<system-reminder>` shell) for one probe outcome. */
+export declare function renderGitStatusFrameBody(outcome: GitStatusProbeOutcome): string;
+/**
+ * Content hash of a rendered frame body — the hash half of the `(kind, hash)` comparison tuple.
+ * Digest domain = format version + canonical repo root + kind + body, NUL-separated (none of the
+ * inputs may contain NUL: the body is sanitized text, the root a canonical path). `canonicalRoot`
+ * is the ExecutionEnv-canonicalized worktree root (or cwd outside a repo) so identical bytes from
+ * two different checkouts never share an announcement.
+ */
+export declare function hashGitStatusFrame(kind: GitAnnouncementKind, body: string, canonicalRoot: string): string;
+/** One resolved frame — outcome rendered and hashed, ready for the (kind, hash) compare. */
+export interface ResolvedGitStatusFrame {
+    kind: GitAnnouncementKind;
+    body: string;
+    hash: string;
+    /** Pre-rendered DEGRADED body + hash for the same probe cycle (present only when kind is
+     *  `full`): the one-shot deterministic shrink target of the irreducible-core over-budget arc —
+     *  computed at prepare time because the request-build path must not re-run probes. */
+    shrunk?: {
+        body: string;
+        hash: string;
+    };
+}
+/** Render + hash one probe outcome (and its deterministic degraded shrink target when full). */
+export declare function resolveGitStatusFrame(outcome: GitStatusProbeOutcome, canonicalRoot: string, degradedMaterial?: {
+    branch?: string;
+    dirty?: boolean;
+}): ResolvedGitStatusFrame;
+/**
+ * The run-local git-status lane state (one per run, on `Prepared`) — the coordination surface
+ * between prepare (probe resolution), the run loop (delivery + receipt + compaction re-assertion)
+ * and the request-build context handler (trim protection). Deliberately a plain mutable ref, the
+ * `announcedListingsRef` discipline.
+ */
+export interface GitStatusLaneRef {
+    /** This leg's resolved frame (undefined ⇒ hands-less leg: the lane is out of scope, announced
+     *  state untouched — the env block equally carried no git facts for such a leg). */
+    frame?: ResolvedGitStatusFrame;
+    /** Canonical repo root the frame was hashed against. */
+    canonicalRoot?: string;
+    /** The announced state as THIS run knows it (seeded from the read ladder at leg start, advanced
+     *  at each receipt) — mirrored onto the suspend checkpoint. `pending: true` ⇒ a re-announcement
+     *  is owed (frame append failed / compaction restated pending); the next boundary retries. */
+    announced?: {
+        kind: GitAnnouncementKind;
+        hash: string;
+        entryId?: string;
+        pending?: true;
+    };
+    /** Exact WRAPPED text of the newest announced frame — the frame SEGMENT, on both carry forms
+     *  (rescan doc-rot fix: r1 moved this off "the whole first-message text"; the contract here had
+     *  kept the pre-r1 words). The context guard finds the carrier by CONTAINING this engine-held
+     *  string (engine-region gated), protects that carrier as a replace-by-key slot — only the newest
+     *  carrier is protected, older frames trim like ordinary history — and charges the irreducible
+     *  core by THIS segment, never by the whole carrier (the objective riding the same message keeps
+     *  its own overflow exit). */
+    protectedText?: string;
+    /** One-shot latch of the irreducible-core arc's DISCLOSURE: the request view substituted the
+     *  degraded rendering at least once (the substitution itself is per-request deterministic; the
+     *  disclosure + pending re-announcement fire only on the first). */
+    overBudgetShrunk?: boolean;
+    /** The exact WRAPPED frame segment of the protected carrier and its degraded substitution target
+     *  (both `<system-reminder>`-shelled, exactly as delivered) — the irreducible-core shrink is a
+     *  literal string replace of `find` with `replace` inside the carrier's text. Set at delivery
+     *  alongside {@link GitStatusLaneRef.protectedText}; present only for a full-kind frame. */
+    wrappedShrink?: {
+        find: string;
+        replace: string;
+    };
+    /** Wired by the run loop once its queue exists: re-assert the current frame (compaction landing
+     *  + boundary retry both call this). */
+    reassert?: () => Promise<void>;
+    /** F5 (falsification round 1) — the typed terminal's surface bridge: the loop converts a
+     *  context-hook throw into a failure MESSAGE (text only), so the thrown `code` never reaches
+     *  result assembly on its own. Set alongside the throw; the run loop lifts it into
+     *  `TaskResult.errorCode`. */
+    terminalCode?: "irreducible_core_over_budget";
+    /** F4 (falsification round 1) — the receipt's mirror write, PARKED instead of fired: a
+     *  fire-and-forget CAS append from inside the message_end walk can race the loop's own next
+     *  transcript append and fail the CRITICAL write with a conflict. The run loop flushes this at
+     *  serialization points only (turn boundary, prompt settle); an unflushed slot at suspend is
+     *  covered by the checkpoint rung (the frame IS on the branch — visibility check passes). */
+    mirrorOwed?: {
+        kind: GitAnnouncementKind;
+        hash: string;
+        entryId: string;
+    };
+    /** The duplicate-tolerant receipt slot: set when a frame delivery is in flight, settled by the
+     *  run loop's `message_end` walk when the CARRYING message commits (matched on the exact
+     *  engine-held message text). Commit-on-receipt, never commit-before-append — the git lane's
+     *  error asymmetry is the REVERSE of the listing lane's (a false "announced" = stale git facts
+     *  forever; a duplicate frame = a few idempotent kilobytes). */
+    pendingReceipt?: {
+        text: string;
+        commit: (entryId: string) => void;
+    };
+}
+/**
+ * prepare-side probe half of the lane (H4, extracted from prepareTask under the design/238 D-7
+ * body ratchet): run the CC-shape snapshot round-trip through the SAME ExecutionEnv seam when the
+ * §E14 probe confirmed a repo, resolve the outcome through the §4.3 unified kind ladder, and hash
+ * the rendered frame with the canonical repo root bound in. `envFacts` carries the §E14 results
+ * (read-only here). Every degrade names its reason through `onDegrade` — including the sentinel
+ * MIS-SPLIT arm (parts !== 4), which previously dropped the snapshot with ZERO telemetry (the
+ * loud-bad-value fix). Returns the run's lane ref (empty on a hands-less leg).
+ *
+ * H4 anchor notes carried from the prepareTask body: four sections split by a sentinel line —
+ * main-branch inference (CC qP symref → [inferred, main, master] each show-ref → renderer falls
+ * back "main"), `git config user.name`, `git --no-optional-locks status --short`, and
+ * `git --no-optional-locks log --oneline -n 5` (CC-exact commands). 1.256 复审 MED-4: the two
+ * REQUIRED sections fail the WHOLE script with distinct exit codes (41 = status, 42 = log) so a
+ * failing status never half-renders as "(clean)"; both now DEGRADE the frame to the branch+dirty
+ * residual instead of silently skipping. The main-branch/user sections stay best-effort.
+ */
+export declare function probeGitStatusLane(args: {
+    executionEnv: Pick<ExecutionEnv, "exec" | "canonicalPath">;
+    envFacts: {
+        isGitRepo?: boolean;
+        gitBranch?: string;
+        gitDirty?: boolean;
+        gitWorktreeRoot?: string;
+        cwd?: string;
+    };
+    handsEnabled: boolean;
+    taskRoot: string;
+    onDegrade: (reason: string) => void;
+}): Promise<GitStatusLaneRef>;
+/**
+ * Request-build half of the trim protection (extracted from prepareTask's context handler under the
+ * same D-7 ratchet): wraps {@link protectGitFrame} with the lane ref's state — the substitution
+ * pair, the one-shot disclosure latch and the pending re-announcement on the first shrink — and
+ * converts the over-budget verdict into the LOUD typed terminal (`irreducible_core_over_budget`),
+ * never a pretended trim success. Returns the (possibly re-inserted / shrunk) request view.
+ */
+export declare function applyGitFrameGuard(args: {
+    before: AgentMessage[];
+    trimmed: AgentMessage[];
+    budgetTokens: number;
+    ref: GitStatusLaneRef;
+    charsPerToken?: number;
+    onDegrade: (message: string) => void;
+}): AgentMessage[];
+/**
+ * R2-1 + R3-1/R3-2 + r4-2 (falsification rounds 2-4) — the transcript-side classifier of engine
+ * git frames. The mirror plane is a CACHE of "which frame is newest"; the TRANSCRIPT is the truth,
+ * and the two diverge exactly when a mirror write was lost. This scan finds the NEWEST engine git
+ * frame on the branch, with TOP-LEVEL WRAPPED-UNIT matching:
+ *   - positive frame: the wrapped unit's head (open tag + newline + the frame preamble);
+ *   - tombstone: the exact wrapped unit (open tag + newline + tombstone body + newline + close tag);
+ *   - the occurrence must sit inside the message's ENGINE region (engineMinted / enginePrefixChars
+ *     / engineSegments — metadata gates, never user-text shape-guessing), AND at TOP LEVEL (r4-2:
+ *     start-of-text or right after a close tag — a hook relay that QUOTES the exact frame unit
+ *     nests it inside its own shell with prose before the open tag, and is rejected);
+ *   - within one message the LAST top-level unit wins (textual order = issue order).
+ */
+export declare function newestEngineGitFrame(branch: SessionTreeEntry[]): {
+    entryId: string;
+    positive: boolean;
+} | undefined;
+/**
+ * Remove POSITIVE git_status wrapped units from an engine-region text before a downstream parser
+ * scans it (rescan P3): the frame embeds REPO-CONTROLLED lines (branch names, commit subjects —
+ * tag-neutralized at wrap, but plain text rides verbatim), and the listing-replay parser reads
+ * engine-region text as trusted state — a commit subject spelling a listing header could reset the
+ * announced-set to empty (one spurious roster re-announcement). Tombstone units are constants
+ * (zero repo text) and need no stripping. The wrap sanitizer neutralizes the system-reminder CLOSE
+ * TAG inside the body (not `<` generally — refuter-precision note), so a unit's body cannot
+ * contain the close tag and the first close tag after a head is that unit's own on every
+ * contiguous region sema mints; the ownership check below is defense-in-depth for foreign text.
+ */
+export declare function stripGitStatusUnits(text: string): string;
+/**
+ * The readable-absence tombstone question (R2-1), answered by the classifier above: does the
+ * branch carry a still-context-visible POSITIVE engine frame as its newest git frame? A newest
+ * TOMBSTONE means the disowning already happened (no re-spam); no frame at all means a genuinely
+ * fresh lane (no tombstone out of nowhere).
+ */
+export declare function branchCarriesVisiblePositiveGitFrame(branch: SessionTreeEntry[]): boolean;

package/dist/core/runner/git-status-frame.js

@@ -0,0 +1,212 @@
+import { createHash } from "node:crypto";
+import { GIT_SNAPSHOT_CC_PREAMBLE, buildGitSnapshot } from "../../prompts/default.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+import { engineRegionCovers, protectGitFrame } from "../context-guard.js";
+import { gitFrameContextVisible } from "../../internal/harness.js";
+export const GIT_STATUS_FRAME_FORMAT_VERSION = 1;
+export const GIT_STATUS_FRAME_PREAMBLE = "This is the git status observed while preparing this request. When the visible snapshot changes it will be re-sent in a later message — the most recent git status frame supersedes earlier ones.";
+export const GIT_STATUS_UNAVAILABLE_BODY = "Git status is currently unavailable; the most recent git status frame above may be stale.";
+export const GIT_STATUS_NON_REPO_BODY = "The working directory is no longer a git repository; earlier git status frames no longer apply.";
+export const GIT_STATUS_ECHO_PREVIEW = {
+    full: "git status updated",
+    degraded: "git status updated (degraded: branch and dirtiness only)",
+    unavailable: "git status unavailable",
+    "non-repo": "git status: no longer a git repository",
+};
+function toWellFormedText(s) {
+    const native = s.toWellFormed;
+    if (typeof native === "function")
+        return native.call(s);
+    return s.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "�");
+}
+export function renderGitStatusFrameBody(outcome) {
+    switch (outcome.kind) {
+        case "full": {
+            const body = outcome.snapshot.startsWith(GIT_SNAPSHOT_CC_PREAMBLE)
+                ? GIT_STATUS_FRAME_PREAMBLE + outcome.snapshot.slice(GIT_SNAPSHOT_CC_PREAMBLE.length)
+                : `${GIT_STATUS_FRAME_PREAMBLE}\n\n${outcome.snapshot}`;
+            return toWellFormedText(body);
+        }
+        case "degraded": {
+            const lines = [GIT_STATUS_FRAME_PREAMBLE];
+            lines.push(`Current branch: ${inlineUntrusted(outcome.branch ?? "HEAD")}`);
+            if (outcome.dirty !== undefined) {
+                lines.push(`Git working tree: ${outcome.dirty ? "has uncommitted changes" : "clean"}`);
+            }
+            return toWellFormedText(lines.join("\n\n"));
+        }
+        case "unavailable":
+            return GIT_STATUS_UNAVAILABLE_BODY;
+        case "non-repo":
+            return GIT_STATUS_NON_REPO_BODY;
+    }
+}
+export function hashGitStatusFrame(kind, body, canonicalRoot) {
+    return `sha256:${createHash("sha256")
+        .update(`${GIT_STATUS_FRAME_FORMAT_VERSION}\u0000${canonicalRoot}\u0000${kind}\u0000${body}`)
+        .digest("hex")}`;
+}
+export function resolveGitStatusFrame(outcome, canonicalRoot, degradedMaterial) {
+    const body = renderGitStatusFrameBody(outcome);
+    const resolved = {
+        kind: outcome.kind,
+        body,
+        hash: hashGitStatusFrame(outcome.kind, body, canonicalRoot),
+    };
+    if (outcome.kind === "full") {
+        const shrunkBody = renderGitStatusFrameBody({ kind: "degraded", ...(degradedMaterial ?? {}) });
+        resolved.shrunk = { body: shrunkBody, hash: hashGitStatusFrame("degraded", shrunkBody, canonicalRoot) };
+    }
+    return resolved;
+}
+export async function probeGitStatusLane(args) {
+    const { executionEnv, envFacts, handsEnabled, taskRoot, onDegrade } = args;
+    const ref = {};
+    if (!handsEnabled)
+        return ref;
+    let outcome;
+    if (envFacts.isGitRepo === true) {
+        const SEP = "@@SEMA_ENV_GIT_SPLIT@@";
+        outcome = {
+            kind: "degraded",
+            ...(envFacts.gitBranch !== undefined ? { branch: envFacts.gitBranch } : {}),
+            ...(envFacts.gitDirty !== undefined ? { dirty: envFacts.gitDirty } : {}),
+        };
+        try {
+            const snap = await executionEnv.exec(`(m=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null); m=\${m#origin/}; for s in "$m" main master; do if [ -n "$s" ] && git show-ref --verify --quiet "refs/remotes/origin/$s"; then echo "$s"; break; fi; done) || true; echo "${SEP}"; (git config user.name 2>/dev/null || true); echo "${SEP}"; gs=$(git --no-optional-locks status --short) || exit 41; printf '%s\\n' "$gs"; echo "${SEP}"; gl=$(git --no-optional-locks log --oneline -n 5) || exit 42; printf '%s\\n' "$gl"`, { cwd: envFacts.cwd, timeout: 10 });
+            if (snap.ok && snap.value.exitCode === 0) {
+                const parts = snap.value.stdout.split(`${SEP}\n`);
+                if (parts.length === 4) {
+                    outcome = {
+                        kind: "full",
+                        snapshot: buildGitSnapshot({
+                            branch: envFacts.gitBranch ?? "HEAD",
+                            mainBranch: parts[0].trim() || "main",
+                            ...(parts[1].trim() ? { userName: parts[1].trim() } : {}),
+                            status: parts[2],
+                            log: parts[3],
+                        }),
+                    };
+                }
+                else {
+                    onDegrade(`sentinel mis-split (${parts.length} sections, expected 4)`);
+                }
+            }
+            else {
+                onDegrade(snap.ok
+                    ? snap.value.exitCode === 41
+                        ? "git status failed (exit 41)"
+                        : snap.value.exitCode === 42
+                            ? "git log failed (exit 42)"
+                            : `git exited ${snap.value.exitCode}`
+                    : `exec failed: ${snap.error.message}`);
+            }
+        }
+        catch (err) {
+            onDegrade(err instanceof Error ? err.message : String(err));
+        }
+    }
+    else if (envFacts.isGitRepo === false) {
+        outcome = { kind: "non-repo" };
+    }
+    else {
+        outcome = { kind: "unavailable" };
+    }
+    const rootRaw = envFacts.gitWorktreeRoot ?? envFacts.cwd ?? taskRoot;
+    let canonicalRoot = rootRaw;
+    try {
+        const c = await executionEnv.canonicalPath(rootRaw);
+        if (c.ok)
+            canonicalRoot = c.value;
+    }
+    catch {
+    }
+    ref.canonicalRoot = canonicalRoot;
+    ref.frame = resolveGitStatusFrame(outcome, canonicalRoot, {
+        ...(envFacts.gitBranch !== undefined ? { branch: envFacts.gitBranch } : {}),
+        ...(envFacts.gitDirty !== undefined ? { dirty: envFacts.gitDirty } : {}),
+    });
+    return ref;
+}
+export function applyGitFrameGuard(args) {
+    const { before, trimmed, budgetTokens, ref, charsPerToken, onDegrade } = args;
+    if (ref.protectedText === undefined)
+        return trimmed;
+    const guarded = protectGitFrame(before, trimmed, budgetTokens, {
+        protectedText: ref.protectedText,
+        ...(ref.frame?.kind === "full" && ref.frame.shrunk !== undefined && ref.wrappedShrink !== undefined ? { substitute: ref.wrappedShrink } : {}),
+    }, charsPerToken);
+    if (guarded.action === "over_budget") {
+        ref.terminalCode = "irreducible_core_over_budget";
+        throw Object.assign(new Error("irreducible core over budget: the compaction summary plus the git status frame alone exceed the request budget — no trim can produce an honest request"), { code: "irreducible_core_over_budget" });
+    }
+    if (guarded.action === "shrunk" && !ref.overBudgetShrunk) {
+        ref.overBudgetShrunk = true;
+        if (ref.announced !== undefined)
+            ref.announced = { ...ref.announced, pending: true };
+        onDegrade("git status frame degraded under budget pressure: the full snapshot no longer fits the request budget — requests carry the branch+dirty residual; the degraded view will be re-announced");
+    }
+    return guarded.messages;
+}
+export function newestEngineGitFrame(branch) {
+    const positiveHead = `<system-reminder>\n${GIT_STATUS_FRAME_PREAMBLE}`;
+    const tombUnits = [`<system-reminder>\n${GIT_STATUS_UNAVAILABLE_BODY}\n</system-reminder>`, `<system-reminder>\n${GIT_STATUS_NON_REPO_BODY}\n</system-reminder>`];
+    const topLevel = (text, at) => {
+        if (at === 0)
+            return true;
+        const before = text.slice(0, at).replace(/\n+$/, "");
+        return before === "" || before.endsWith("</system-reminder>");
+    };
+    const allTopLevel = (text, needle, m) => {
+        const out = [];
+        for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + 1)) {
+            if (topLevel(text, at) && engineRegionCovers(m, at, needle.length))
+                out.push(at);
+        }
+        return out;
+    };
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry === undefined || entry.type !== "message")
+            continue;
+        const m = entry.message;
+        if (m.role !== "user")
+            continue;
+        const c = m.content;
+        const text = typeof c === "string" ? c : Array.isArray(c) && c.length >= 1 && c[0].type === "text" ? (c[0].text ?? "") : undefined;
+        if (text === undefined)
+            continue;
+        let best;
+        for (const at of allTopLevel(text, positiveHead, m)) {
+            if (best === undefined || at > best.at)
+                best = { at, positive: true };
+        }
+        for (const unit of tombUnits) {
+            for (const at of allTopLevel(text, unit, m)) {
+                if (best === undefined || at > best.at)
+                    best = { at, positive: false };
+            }
+        }
+        if (best !== undefined)
+            return { entryId: entry.id, positive: best.positive };
+    }
+    return undefined;
+}
+export function stripGitStatusUnits(text) {
+    const head = `<system-reminder>\n${GIT_STATUS_FRAME_PREAMBLE}`;
+    const close = "</system-reminder>";
+    let out = text;
+    for (let at = out.indexOf(head); at !== -1; at = out.indexOf(head)) {
+        const end = out.indexOf(close, at);
+        if (end === -1)
+            break;
+        if (out.slice(at + head.length, end).includes("<system-reminder>"))
+            break;
+        out = out.slice(0, at) + out.slice(end + close.length);
+    }
+    return out;
+}
+export function branchCarriesVisiblePositiveGitFrame(branch) {
+    const newest = newestEngineGitFrame(branch);
+    return newest !== undefined && newest.positive && gitFrameContextVisible(branch, newest.entryId);
+}

package/dist/core/runner/prepare-memory.d.ts

@@ -1,4 +1,4 @@
-import type { BeforeWriteHook, RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
+import type { BeforeWriteHook, EffectiveMemoryScopes, RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
 import type { Prepared } from "./prepare-task.js";
 export interface PrepareMemoryInput {
     spec: TaskSpec;
@@ -106,5 +106,15 @@ export interface PrepareMemoryResult {
     /** The session's own frozen verdict to persist at suspend — present iff this leg ADJUDICATED an
      *  org plane (including adjudicated-empty); `undefined` for an org-less task. */
     ownOrgVerdict: import("../memory-admission.js").OwnOrgAdmissionVerdict | undefined;
+    /**
+     * design/178 v2 §2.3 (件①) — the memory-visibility OBSERVATION this phase minted for
+     * `TaskResult.effectiveMemoryScopes` (see {@link EffectiveMemoryScopes} for the state law).
+     * ALWAYS present when the phase returns: the memory-less outcomes are their own values
+     * (`none` / `memoryless`), never an absent seat — absence on the RESULT means only "prepare
+     * never completed" (this phase threw). Minted AFTER the materialize outcome (the fail-open arm
+     * sits between the admission verdict and the mount — an earlier stamp would report a mount that
+     * never happened); the deliberate-refusal `config.memory_*` throws produce no value at all.
+     */
+    effectiveMemoryScopes: EffectiveMemoryScopes;
 }
 export declare function prepareMemory(input: PrepareMemoryInput): Promise<PrepareMemoryResult>;

package/dist/core/runner/prepare-memory.js

@@ -12,12 +12,16 @@ export async function prepareMemory(input) {
     const memorySpec = normalizeMemorySpec(spec.memory);
     let admittedOrgScopes = [];
     let ownOrgVerdict;
+    const deploymentScopeSet = new Set(deps.deploymentMemoryScopes ?? []);
+    const scopeOriginsSnapshot = memorySpec?.scopeOrigins !== undefined ? { ...memorySpec.scopeOrigins } : undefined;
+    if (memorySpec && scopeOriginsSnapshot !== undefined)
+        memorySpec.scopeOrigins = scopeOriginsSnapshot;
     if (memorySpec && memorySpec.enabled && deps.memoryBackend) {
         const outcome = await admitMemoryScopes({
             memorySpec,
             principal: spec.principal,
             admission: deps.memoryScopeAdmission,
-            deploymentScopes: new Set(deps.deploymentMemoryScopes ?? []),
+            deploymentScopes: deploymentScopeSet,
             orgMemoryDenied: admissionCtx.orgMemoryDenied,
             complianceDegraded: admissionCtx.complianceDegraded,
             parentAdmittedOrgScopes: admissionCtx.parentAdmittedOrgScopes,
@@ -38,6 +42,15 @@ export async function prepareMemory(input) {
     const useMemoryEngine = Boolean(memorySpec && memorySpec.enabled && deps.memoryBackend);
     let memoryEngineSession;
     let memoryTools;
+    let effectiveMemoryScopes;
+    const originOf = (scope) => scopeOriginsSnapshot !== undefined
+        ? scopeOriginsSnapshot[scope] === "deployment"
+            ? "deployment"
+            : "request"
+        : deploymentScopeSet.has(scope)
+            ? "deployment"
+            : "request";
+    const materializedResidue = [];
     if (useMemoryEngine && memorySpec) {
         try {
             const backend = deps.memoryBackend;
@@ -133,6 +146,12 @@ export async function prepareMemory(input) {
                     b)
                 : (b.retrievalView?.() ?? b);
             const planeScopes = (scopes, write) => [...new Set([...scopes, ...(write !== null ? [write] : [])])];
+            const mountedScopeRows = (dual
+                ? [
+                    ...planeScopes(planes.project, planes.writePlane === "project" ? memorySpec.writeScope : null),
+                    ...planeScopes(planes.personal, planes.writePlane === "personal" ? memorySpec.writeScope : null),
+                ]
+                : planeScopes(memorySpec.scopes, memorySpec.writeScope)).map((scope) => ({ scope, origin: originOf(scope) }));
             const pollutedOpts = (engine) => {
                 const rec = engine.sessionPollution(sessionId);
                 return rec !== undefined ? { polluted: { reason: rec.reason } } : {};
@@ -179,7 +198,9 @@ export async function prepareMemory(input) {
                 const personalEngine = personal.engine;
                 const p = planes;
                 const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null, { adoptionRestricted });
+                materializedResidue.push(...planeScopes(p.project, p.writePlane === "project" ? memorySpec.writeScope : null));
                 const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null, { adoptionRestricted });
+                materializedResidue.push(...planeScopes(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null));
                 const writeIsPersonal = p.writePlane === "personal";
                 writeEngine = writeIsPersonal ? personalEngine : projectEngine;
                 writeHandle = writeIsPersonal ? personalHandle : projectHandle;
@@ -222,6 +243,7 @@ export async function prepareMemory(input) {
                 const personal = createPersonalEngine(choosePersonalBackend());
                 const personalEngine = personal.engine;
                 const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted });
+                materializedResidue.push(...planeScopes(memorySpec.scopes, memorySpec.writeScope));
                 writeEngine = personalEngine;
                 writeHandle = handle;
                 injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted });
@@ -243,6 +265,7 @@ export async function prepareMemory(input) {
                     onIncident: onEngineIncident,
                 });
                 const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted });
+                materializedResidue.push(...planeScopes(memorySpec.scopes, memorySpec.writeScope));
                 writeEngine = engine;
                 writeHandle = handle;
                 injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted });
@@ -311,6 +334,12 @@ export async function prepareMemory(input) {
                     execIsExternalContent: memorySpec.execIsExternalContent === true,
                 },
             };
+            effectiveMemoryScopes = {
+                state: "mounted",
+                contract: memorySpec.scopeContract === "v2" ? "v2" : "legacy",
+                scopes: mountedScopeRows,
+                writeScope: memorySpec.writeScope,
+            };
             if (input.memorySearchToolsPlanned)
                 memoryTools = createMemoryEngineTools({ planes: toolPlanes });
         }
@@ -322,6 +351,16 @@ export async function prepareMemory(input) {
                 throw err;
             }
             deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
+            if (effectiveMemoryScopes === undefined) {
+                effectiveMemoryScopes = {
+                    state: "memoryless",
+                    reason: "mount-failed",
+                    contract: memorySpec.scopeContract === "v2" ? "v2" : "legacy",
+                    scopes: [],
+                    writeScope: null,
+                    ...(materializedResidue.length > 0 ? { materializedResidue: [...new Set(materializedResidue)] } : {}),
+                };
+            }
         }
     }
     let memoryBlock;
@@ -359,5 +398,12 @@ export async function prepareMemory(input) {
         if (memoryBlock !== undefined && injection.indexSeed !== undefined && input.rosterCanPersist)
             seedFiles = [injection.indexSeed];
     }
-    return { memoryEngineSession, memoryBlock, admittedOrgScopes, ownOrgVerdict, ...(memoryTools !== undefined ? { memoryTools } : {}), ...(seedFiles !== undefined ? { seedFiles } : {}) };
+    if (effectiveMemoryScopes === undefined) {
+        effectiveMemoryScopes = memorySpec
+            ? memorySpec.enabled
+                ? { state: "memoryless", reason: "no-backend", contract: memorySpec.scopeContract === "v2" ? "v2" : "legacy", scopes: [], writeScope: null }
+                : { state: "none", reason: "disabled", scopes: [], writeScope: null }
+            : { state: "none", reason: "no-spec", scopes: [], writeScope: null };
+    }
+    return { memoryEngineSession, memoryBlock, admittedOrgScopes, ownOrgVerdict, effectiveMemoryScopes, ...(memoryTools !== undefined ? { memoryTools } : {}), ...(seedFiles !== undefined ? { seedFiles } : {}) };
 }

package/dist/core/runner/prepare-task.d.ts

@@ -17,6 +17,7 @@ import { CacheBreakDetector, type ToolFingerprintInput } from "../cache-break-de
 import { type BrainCallGuardrailRef } from "../../brain/timeout.js";
 import { type OutputRef, type BlockedRef, type SkillListingEntry } from "./synthetic-tools.js";
 import type { MemoryEngine } from "../memory-engine/engine.js";
+import { type GitStatusLaneRef } from "./git-status-frame.js";
 import { type ToolManifestRow } from "../../prompt-assembly/tool-catalog.js";
 import type { ToolDisclosureManifest } from "../trace.js";
 import type { TaskNotificationPayload } from "../task-notification.js";
@@ -204,6 +205,11 @@ export interface Prepared {
      *  excluded), echoed on `TaskResult.effectiveReadDenyPatterns`. Present iff non-empty; a defensive
      *  copy (the wide-scope working array stays the engine's own). */
     effectiveReadDenyPatterns?: readonly import("../../tools/fs/read-deny.js").NormalizedReadDenyEntry[];
+    /** design/178 v2 §2.3 (件①) — the memory-visibility observation prepareMemory minted (echoed on
+     *  `TaskResult.effectiveMemoryScopes`). Always present on a completed prepare (the memory-less
+     *  states are their own values); the seat is optional only so a Prepared shape without the phase
+     *  cannot fabricate one. */
+    effectiveMemoryScopes?: import("../types.js").EffectiveMemoryScopes;
     /** design/99 §E13 — the per-task logical cwd ref when a real shell is mounted (else undefined). The Runner
      *  reads `cwdRef.current` after each tool to detect a `cd` move and emit `workspace_changed`. */
     cwdRef?: CwdRef;
@@ -747,6 +753,12 @@ export interface Prepared {
         skills?: readonly string[];
         models?: readonly string[];
     };
+    /** env-tail migration (#254 shape) — the git-status frame lane's run-local state: this leg's
+     *  resolved frame (probe outcome rendered + hashed at prepare), the announced `(kind, hash)`
+     *  mirror the checkpoint serializer reads, the trim-protection slot the request-build context
+     *  handler matches on, and the re-assert closure the compaction landing + boundary retry call.
+     *  Always present (empty object on a hands-less leg — the lane is then out of scope). */
+    gitStatusRef: GitStatusLaneRef;
     /** G1 通告层 — narrow post-compact getter over the process task registry: THIS run's visible
      *  pending/running background tasks (same owner/scope/session identity the TaskOutput/TaskStop tools
      *  use), as a bounded display projection (id/description/status — never handles/env/abort). Called by
@@ -1244,6 +1256,15 @@ export interface RunInternals {
      * stamping. TRUSTED run-scoped channel (never a {@link TaskSpec} field).
      */
     delegationTaskType?: import("../types.js").DelegationTaskType;
+    /**
+     * #258 — the registry row's stop-cycle generation this run executes as (fresh spawn = 1, a
+     * revival's bumped counter), threaded by the BACKGROUND delegation lanes from the registry's own
+     * `cycleSeq` so every `task_progress` tick the run mints carries it as `seq` (same axis as
+     * `TaskNotificationPayload.seq` / `BackgroundChildEvent.seq`). Absent for runs with no `a*` row
+     * (sync children, workflow agents, top-level) — same absence-is-a-fact posture as
+     * {@link delegationTaskType} above. TRUSTED run-scoped channel (never a TaskSpec field).
+     */
+    cycleSeq?: number;
     /** δ 批 [1498]⑦/A-3 — the ROOT host session of the whole delegation tree (fixed point: the
      *  spawner passes its own `ctx.rootSessionId ?? ctx.sessionId`, so depth 1 gets the host session
      *  and every deeper level inherits it verbatim). `parentSessionId` is the IMMEDIATE spawner —