@sema-agent/core 5.34.0 → 5.36.0

package/dist/core/park-selfcheck.js

@@ -0,0 +1,251 @@
+import { boundInputHashOf, canonicalize } from "./canonical-json.js";
+import { MAX_SUPPORTED_CHECKPOINT_VERSION, mintCheckpointToken, resolveCheckpointStore } from "./checkpoint-store.js";
+import { resolveDeclaredDurability } from "./wiring-manifest.js";
+export const PARK_SELFCHECK_SCOPE_PREFIX = "sema:park-selfcheck:";
+export const PARK_SELFCHECK_STEP_TIMEOUT_MS = 10_000;
+export const PARK_SELFCHECK_ROW_TTL_MS = 60_000;
+async function within(op, step) {
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve()
+                .then(op)
+                .then((ok) => ({ ok }))
+                .catch((threw) => ({ threw })),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve({ timedOut: `${step} did not answer within ${PARK_SELFCHECK_STEP_TIMEOUT_MS}ms — a store that neither answers nor errors is the failure this probe exists to surface, not one it may wait on` }), PARK_SELFCHECK_STEP_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function declaresDurable(store, name) {
+    try {
+        return resolveDeclaredDurability(store, name) === "durable";
+    }
+    catch {
+        return false;
+    }
+}
+export function durableParkGapOf(halves) {
+    if (!halves.checkpointWired)
+        return undefined;
+    if (halves.checkpointDurable && halves.sessionDurable)
+        return undefined;
+    if (halves.checkpointDurable && !halves.sessionDurable) {
+        return ("this deployment wires a checkpoint store that declares durability but a session store that does not " +
+            "(RunnerDeps.sessionStore — absent means the built-in in-memory store): a durable park needs BOTH halves, " +
+            "so a parked approval survives the restart while the conversation it resumes into does not, and a resume " +
+            "arriving afterwards finds the checkpoint and not the session");
+    }
+    if (!halves.checkpointDurable && halves.sessionDurable) {
+        return ("this deployment wires a session store that declares durability but a checkpoint store that does not " +
+            "(RunnerDeps.checkpointStore.durability): a durable park needs BOTH halves, so the conversation survives " +
+            "the restart while the parked approval that was to resume it does not");
+    }
+    return undefined;
+}
+export function durableParkGapFor(deps, spec = {}) {
+    const checkpointStore = resolveCheckpointStore(spec, deps);
+    return durableParkGapOf({
+        checkpointWired: checkpointStore !== undefined,
+        checkpointDurable: declaresDurable(checkpointStore, "checkpointStore"),
+        sessionDurable: declaresDurable(deps.sessionStore, "sessionStore"),
+    });
+}
+function syntheticCheckpoint(scope) {
+    return {
+        token: mintCheckpointToken(),
+        scope,
+        sessionId: `${scope}:session`,
+        leafId: `${scope}:leaf`,
+        gate: { kind: "human", reason: "park wiring self-check (design/252 G-6) — no person is being asked", toolName: "SelfCheck" },
+        pendingAction: {
+            kind: "tool_approval",
+            toolCallId: `${scope}:call`,
+            toolName: "SelfCheck",
+            args: { probe: true, nested: { depth: 2, list: [1, 2, 3] } },
+            boundInputHash: boundInputHashOf({ probe: true, nested: { depth: 2, list: [1, 2, 3] } }),
+            batchToolCallIds: [`${scope}:call`],
+            completedCallIds: [],
+        },
+        state: { activeTools: ["SelfCheck"], nestedStats: { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0, anyUnpriced: false } },
+        status: "pending",
+        createdAt: Date.now(),
+        version: MAX_SUPPORTED_CHECKPOINT_VERSION,
+        suspendCount: 1,
+        suspendedAt: Date.now(),
+        resourceLedger: { spentMicroUsd: 0, spentTokens: 0, spentTurns: 0, sliceCount: 1 },
+        humanReview: { count: 1, totalWaitMs: 0, gates: [{ kind: "human", waitMs: 0, decision: "approve" }] },
+        sourceTaskId: `${scope}:task`,
+        principal: `${scope}:principal`,
+        durableApproval: { scope, ttlMs: PARK_SELFCHECK_ROW_TTL_MS },
+        deadline: Date.now() + PARK_SELFCHECK_ROW_TTL_MS,
+    };
+}
+function faithfulnessDelta(sent, got) {
+    const project = (cp) => ({
+        token: cp.token,
+        scope: cp.scope,
+        sessionId: cp.sessionId,
+        leafId: cp.leafId,
+        gate: cp.gate,
+        pendingAction: cp.pendingAction,
+        state: cp.state,
+        deadline: cp.deadline,
+        createdAt: cp.createdAt,
+        version: cp.version,
+        suspendCount: cp.suspendCount,
+        suspendedAt: cp.suspendedAt,
+        resourceLedger: cp.resourceLedger,
+        humanReview: cp.humanReview,
+        sourceTaskId: cp.sourceTaskId,
+        principal: cp.principal,
+        durableApproval: cp.durableApproval,
+    });
+    const a = canonicalize(project(sent));
+    const b = canonicalize(project(got));
+    return a === b ? undefined : `the row came back different from the row that was filed (sent ${a}; read ${b})`;
+}
+export async function probeParkRoundTrip(deps, spec = {}) {
+    const gap = durableParkGapFor(deps, spec);
+    const gapCell = gap !== undefined ? { durableTopologyGap: gap } : {};
+    const store = resolveCheckpointStore(spec, deps);
+    if (store === undefined) {
+        return {
+            verdict: "not_probed",
+            findings: [],
+            summary: "no checkpoint store is wired on this assembly — there is no park lane to probe (the manifest reports the same fact as parkLane.capable: false)",
+            ...gapCell,
+        };
+    }
+    const scope = `${PARK_SELFCHECK_SCOPE_PREFIX}${mintCheckpointToken()}`;
+    const cp = syntheticCheckpoint(scope);
+    const said = (err) => {
+        try {
+            const m = err instanceof Error ? err.message : undefined;
+            return typeof m === "string" ? m : `a ${typeof err} the store threw`;
+        }
+        catch {
+            return "a value the store threw that could not be described";
+        }
+    };
+    const shown = (v) => {
+        try {
+            return typeof v === "string" ? JSON.stringify(v) : `a ${typeof v}`;
+        }
+        catch {
+            return "an undescribable value";
+        }
+    };
+    const fenceQuietly = async () => {
+        await within(async () => {
+            try {
+                await store.expire(cp.token, scope);
+            }
+            catch {
+            }
+        }, "the cleanup fence");
+    };
+    const failed = async (code, detail) => {
+        await fenceQuietly();
+        return { verdict: "failed", findings: [{ code, detail }], scope, summary: `the park lane failed its round-trip self-check at "${code}": ${detail}`, ...gapCell };
+    };
+    let putStarted;
+    const put = await within(() => {
+        const p = Promise.resolve().then(() => store.put(cp.token, cp));
+        putStarted = p;
+        return p;
+    }, "put");
+    if ("timedOut" in put) {
+        void putStarted?.catch(() => { }).then(() => store.expire(cp.token, scope)).catch(() => { });
+        return await failed("put_failed", put.timedOut);
+    }
+    if ("threw" in put)
+        return await failed("put_failed", `the checkpoint store refused to file a synthetic park: ${said(put.threw)}`);
+    const first = await within(() => store.get(cp.token), "get");
+    if ("timedOut" in first)
+        return await failed("row_not_readable", first.timedOut);
+    if ("threw" in first)
+        return await failed("row_not_readable", `the checkpoint store threw reading back the row it had just accepted: ${said(first.threw)}`);
+    const read = first.ok;
+    if (read === null)
+        return await failed("row_not_readable", "the checkpoint store accepted the row and then answered null for its own token — a park filed here would be unresumable");
+    if (typeof read !== "object")
+        return await failed("row_not_readable", `the checkpoint store answered ${read === undefined ? "undefined" : typeof read} for its own token — neither a checkpoint nor the absence of one`);
+    let delta;
+    let status;
+    try {
+        delta = faithfulnessDelta(cp, read);
+        status = read.status;
+    }
+    catch (err) {
+        return await failed("row_not_faithful", `the row the store returned could not be read for comparison: ${said(err)}`);
+    }
+    if (delta !== undefined)
+        return await failed("row_not_faithful", delta);
+    if (status !== "pending")
+        return await failed("row_not_pending", `the filed row came back with status ${shown(status)} — a park in any other status is one nobody can resolve`);
+    const enumerable = store.listByScope !== undefined;
+    if (store.listByScope !== undefined) {
+        const listByScope = store.listByScope.bind(store);
+        const listed = await within(() => listByScope(scope), "listByScope");
+        if ("timedOut" in listed)
+            return await failed("row_not_enumerable", listed.timedOut);
+        if ("threw" in listed)
+            return await failed("row_not_enumerable", `listByScope threw for the probe's own scope: ${said(listed.threw)}`);
+        let present;
+        try {
+            present = Array.isArray(listed.ok) && listed.ok.some((row) => row?.token === cp.token);
+        }
+        catch (err) {
+            return await failed("row_not_enumerable", `the listByScope result could not be read: ${said(err)}`);
+        }
+        if (!present)
+            return await failed("row_not_enumerable", `listByScope("${scope}") did not include the pending row it holds — an inbox enumerating this scope would show no approvals`);
+    }
+    const fence = await within(() => store.expire(cp.token, scope), "expire");
+    if ("timedOut" in fence)
+        return await failed("fence_failed", fence.timedOut);
+    if ("threw" in fence)
+        return await failed("fence_failed", `expire threw on the probe's own pending row: ${said(fence.threw)}`);
+    const fenced = fence.ok === true;
+    const second = await within(() => store.get(cp.token), "get (after the fence)");
+    if ("timedOut" in second)
+        return await failed("fence_not_durable", second.timedOut);
+    if ("threw" in second)
+        return await failed("fence_not_durable", `the store threw re-reading the fenced row: ${said(second.threw)}`);
+    const after = second.ok;
+    let afterStatus;
+    if (after !== null) {
+        if (typeof after !== "object")
+            return await failed("fence_not_durable", `the store answered ${after === undefined ? "undefined" : typeof after} re-reading the fenced row — neither a checkpoint nor the absence of one`);
+        try {
+            afterStatus = after.status;
+        }
+        catch (err) {
+            return await failed("fence_not_durable", `the fenced row's status could not be read: ${said(err)}`);
+        }
+        if (afterStatus !== "expired") {
+            return await failed(fenced ? "fence_not_durable" : "fence_failed", fenced
+                ? `expire reported a win and the row reads ${shown(afterStatus)} — the contract's transition is pending → expired, so the CAS did not land`
+                : `expire lost an UNCONTENDED CAS and the row reads ${shown(afterStatus)} — the fence that keeps a checkpoint from being both reaped and resumed does not close here`);
+        }
+    }
+    const steps = `filed, read back${enumerable ? ", enumerated" : ""} and fenced`;
+    const notExercised = enumerable ? "" : " (this store implements no listByScope, so the inbox enumeration was NOT exercised)";
+    const casNote = fenced ? "" : " (the expire CAS reported a loss while the row closed — consistent with store housekeeping, but a backend that mis-reports CAS wins is not distinguished here)";
+    return {
+        verdict: "round_trip_ok",
+        findings: [],
+        ...(fenced ? {} : { casLossObserved: true }),
+        scope,
+        summary: after === null
+            ? `the park lane ${steps} a synthetic checkpoint${notExercised} — the row is no longer present (a deleting backend or its own housekeeping removed it), so nothing resumable remains${casNote}`
+            : `the park lane ${steps} a synthetic checkpoint${notExercised} — residual expired row in scope "${scope}"${casNote}`,
+        ...gapCell,
+    };
+}

package/dist/core/runner/assemble-result.d.ts

@@ -149,6 +149,9 @@ export interface ResultFlags {
     budgetAxis?: BudgetAxis;
     blockedReason?: string;
     conflict?: boolean;
+    /** env-tail migration F5: the request-build guard threw the irreducible-core terminal this run —
+     *  the loop folded it into a text-only failure message, so the typed code rides this flag. */
+    gitCoreOverBudget?: boolean;
     outputInvalid?: boolean;
     /** design/72 §2.2 (B): a re-suspend was refused because the task already suspended `maxSuspends` times
      *  (a resume/restart loop). It aborted the run (no `threw`) but must read as `failed`/`suspend.loop`,

package/dist/core/runner/assemble-result.js

@@ -141,6 +141,9 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
             errorCode = lifted;
             errorMessage = stripErrorCodePrefix(errorMessage);
         }
+        else if (flags.gitCoreOverBudget) {
+            errorCode = "irreducible_core_over_budget";
+        }
         else if (flags.conflict) {
             errorCode = "conflict";
         }

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;