@sema-agent/core 5.35.0 → 5.36.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-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";
@@ -747,6 +748,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 +1251,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 —

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

@@ -56,7 +56,8 @@ import { limitConfigError, prepareConfigDoors } from "./prepare-config-doors.js"
 import { NAMESPACED_NAME_SHAPES, prepareSafetyScan } from "./prepare-safety-scan.js";
 import { prepareAcquireReconcile } from "./prepare-acquire-reconcile.js";
 import { prepareWorkspaceRestore, rebaseWorkspacePath, remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./prepare-workspace-restore.js";
-import { defaultPromptProvider, buildEnvironmentContext, buildGitSnapshot, formatLocalDate, isValidTimeZone, PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
+import { defaultPromptProvider, buildEnvironmentContext, formatLocalDate, isValidTimeZone, PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
+import { applyGitFrameGuard, probeGitStatusLane } from "./git-status-frame.js";
 import { assemblePrompt } from "../../prompt-assembly/assemble.js";
 import { auditToolCollisions, getToolContract, projectToolManifest } from "../../prompt-assembly/tool-catalog.js";
 import { resolveEpochAgainstBundled } from "../../prompt-assembly/epoch.js";
@@ -1875,38 +1876,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }
             catch {
             }
-            if (envFacts.isGitRepo === true) {
-                const SEP = "@@SEMA_ENV_GIT_SPLIT@@";
-                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) {
-                            envFacts.gitSnapshot = buildGitSnapshot({
-                                branch: envFacts.gitBranch ?? "HEAD",
-                                mainBranch: parts[0].trim() || "main",
-                                ...(parts[1].trim() ? { userName: parts[1].trim() } : {}),
-                                status: parts[2],
-                                log: parts[3],
-                            });
-                        }
-                    }
-                    else {
-                        const reason = 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}`;
-                        deps.onError?.(new Error(`env git snapshot skipped — ${reason}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
-                    }
-                }
-                catch (err) {
-                    deps.onError?.(new Error(`env git snapshot skipped — ${err instanceof Error ? err.message : String(err)}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
-                }
-            }
         }
+        const gitStatusRef = await probeGitStatusLane({
+            executionEnv,
+            envFacts,
+            handsEnabled,
+            taskRoot: taskRootFinal,
+            onDegrade: (reason) => deps.onError?.(new Error(`env git snapshot degraded — ${reason}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" }),
+        });
         if (toolFaceSnapshot.exclude !== undefined && toolFaceSnapshot.exclude.length > 0) {
             const excluded = new Set(toolFaceSnapshot.exclude);
             for (let i = tools.length - 1; i >= 0; i--)
@@ -3577,6 +3554,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         ...(announcedListingsRef.models !== undefined ? { models: [...announcedListingsRef.models] } : {}),
                     }
                     : undefined,
+                gitAnnouncement: gitStatusRef.announced !== undefined ? { ...gitStatusRef.announced } : undefined,
                 delegationProvenance: internals?.delegationProvenance !== undefined ? { ...internals.delegationProvenance.ref.current } : undefined,
             });
             const commitSuspendSaga = async (token, cp, remoteEnv, remoteHandle) => {
@@ -4388,6 +4366,20 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ts: Date.now(),
                 }));
             }
+            trimmed = applyGitFrameGuard({
+                before: edited,
+                trimmed,
+                budgetTokens: guardAt,
+                ref: gitStatusRef,
+                charsPerToken,
+                onDegrade: (message) => {
+                    try {
+                        deps.onError?.(new Error(message), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
+                    }
+                    catch {
+                    }
+                },
+            });
             const swept = dropOrphanToolResults(trimmed);
             if (swept.dropped.length > 0) {
                 try {
@@ -4404,7 +4396,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     mediaCapped !== capped ||
                     edited !== mediaCapped ||
                     trimDroppedMessages ||
-                    swept.dropped.length > 0;
+                    swept.dropped.length > 0 ||
+                    gitStatusRef.overBudgetShrunk === true;
             return { messages: swept.messages };
         });
         const cacheBreakDetector = deps.cacheBreakDetection === false ? undefined : new CacheBreakDetector();
@@ -4593,7 +4586,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const effectiveReadFaceObserved = carrierReadFace();
         const effectiveReadDenyObserved = readDenyAdditionsNormalized.length > 0 ? readDenyAdditionsNormalized.map((e) => ({ ...e })) : undefined;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath: taskRootFinal, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, approvalSettlement, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath: taskRootFinal, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, approvalSettlement, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;