@sema-agent/core 5.35.0 → 5.37.0

package/dist/core/types.d.ts

@@ -2713,6 +2713,79 @@ export interface RemoteEnvFailureNote {
     message: string;
 }
 /** Result returned when a task finishes or gets stuck. Designed to be machine-readable for an external AI. */
+/**
+ * design/178 v2 §2.3 (件①) — the value of {@link TaskResult.effectiveMemoryScopes}: the memory
+ * visibility face a leg ACTUALLY ran under, as a DISCRIMINATED three-state union (deliberately no
+ * `"partial"` state — the engine session is built only after every plane materialized, so a
+ * half-mounted scene is a fail-open `memoryless` with residue, never a served half-face):
+ *
+ *  - `"mounted"` — the memory engine session mounted. `scopes` is the EFFECTIVE VISIBILITY set in
+ *    the effective serving order, both exactly as the engine mounted them: per plane, the
+ *    admission-projected read layering PLUS a distinct write-only scope where one exists (the
+ *    engine registers the write scope's dir and its entries ride the injected index — a write-only
+ *    scope IS visible; the common writeScope∈scopes form dedups to the plain layering), project
+ *    plane first on a dual root. Each row carries its admission ORIGIN (`"deployment"` = the
+ *    operator's own declared set; `"request"` = the caller's spec — the two trust planes of the
+ *    org admission door). `writeScope` is the effective write face as granted (an org writeScope
+ *    not explicitly granted reads `null` here, exactly as it ran). `contract` names the
+ *    scope-identity contract in force (`"v2"` typed keys / `"legacy"` opaque strings).
+ *    SCOPE OF THE CLAIM (stated precisely): the rows are the MEMORY-ENGINE scope set this leg
+ *    mounted — the dirs the engine registered and indexed. They deliberately do NOT cover the
+ *    separate memory-adjacent faces (the shared-memory store pair, the project-context memory
+ *    layer — each its own surface with its own disclosure), and two REGISTERED engine-plane
+ *    channels can carry another scope's bytes without a row here: a root-owning scope's non-empty
+ *    on-disk index is served verbatim to a later mount of that root ("live file wins"),
+ *    and control-plane announcements carry no producing scope and drain plane-wide. Both are
+ *    engine mount semantics under their own tickets, disclosed here so this face is never read as
+ *    a complete cross-face visibility proof.
+ *  - `"memoryless"` — memory was configured but did not mount. `reason: "mount-failed"` = the
+ *    fail-open mount arm caught a fault anywhere in the mount phase (directory resolution through
+ *    materialize — named for the whole captured span, not one step); `reason: "no-backend"` = the
+ *    spec enables memory but no `RunnerDeps.memoryBackend` is configured. `materializedResidue`
+ *    (mount-failed only) lists plane scopes whose PHYSICAL materialize had already completed when
+ *    the fault hit — a LOWER bound (a plane that threw mid-materialize is not listed; on-disk
+ *    residue is ≥ this list), and explicitly NOT a visibility face: an auditor must never read
+ *    residue as mounted scopes, which is why it is a separate seat from the always-empty `scopes`.
+ *  - `"none"` — memory was not in play at all: `"no-spec"` = the task carries no usable memory
+ *    spec; `"disabled"` = a spec is present with `enabled: false`.
+ *
+ * Deliberate-refusal configurations (`config.memory_*` codes) fail the whole prepare and produce
+ * NO observation — this union never dresses a refusal as a state. Honesty note (design r7): the
+ * `?: never` members forbid non-`undefined` values at the type level; the repo does not compile
+ * with `exactOptionalPropertyTypes`, so explicit-`undefined` presence is a wire-validator concern,
+ * not a type-level one.
+ */
+export type EffectiveMemoryScopes = {
+    state: "mounted";
+    reason?: never;
+    contract: "v2" | "legacy";
+    scopes: Array<{
+        scope: string;
+        origin: "deployment" | "request";
+    }>;
+    writeScope: string | null;
+    materializedResidue?: never;
+} | {
+    state: "memoryless";
+    reason: "mount-failed";
+    contract?: "v2" | "legacy";
+    scopes: [];
+    writeScope: null;
+    materializedResidue?: string[];
+} | {
+    state: "memoryless";
+    reason: "no-backend";
+    contract?: "v2" | "legacy";
+    scopes: [];
+    writeScope: null;
+} | {
+    state: "none";
+    reason: "no-spec" | "disabled";
+    contract?: never;
+    scopes: [];
+    writeScope: null;
+    materializedResidue?: never;
+};
 export interface TaskResult {
     taskId: string;
     /** Use this to continue the same conversation on the next call. */
@@ -2972,6 +3045,28 @@ export interface TaskResult {
      * governing the WORK, never the contents of any checkpoint row.
      */
     effectiveReadDenyPatterns?: readonly import("../tools/fs/read-deny.js").NormalizedReadDenyEntry[];
+    /**
+     * design/178 v2 §2.3 (件①) — the memory VISIBILITY face this leg actually ran under, as an
+     * engine-filled OBSERVATION (never a knob: writing it on a spec does nothing). This is the
+     * EFFECTIVE face, not the requested one: a refused request never reaches a terminal at all (the
+     * whole prepare fails with its governance code), so what this seat answers is "what was actually
+     * given" — the delta against the request is directly readable (an org writeScope not explicitly
+     * granted collapses to `null` here as it did in the run; a fail-open mount failure reads
+     * `memoryless`, never a dressed-up mount).
+     *
+     * **In-presence condition** (same law as {@link effectiveReadFace}): present on every terminal of
+     * a leg that COMPLETED prepare — the memory-less states are answered as their own values
+     * (`none` / `memoryless`), so consumers must never read ABSENCE as "no memory"; absence means
+     * only "prepare never completed". Delegated children mint their own on their own legs (their
+     * request plane can only narrow the parent's frozen org verdict); a resume leg's value is the
+     * re-adjudication at resume time (admission runs in every prepare — the current-policy reading,
+     * same axis as the read-face seats).
+     *
+     * Minted AFTER the materialize outcome, not after the admission verdict — the fail-open mount
+     * arm sits between the two, and stamping earlier would report a mount that never happened.
+     * See {@link EffectiveMemoryScopes} for the per-state field law.
+     */
+    effectiveMemoryScopes?: EffectiveMemoryScopes;
     /**
      * `turns`/`tokens`/`costMicroUsd` are this task's OWN model usage. `nested` is the summed usage of any
      * delegated sub-runs (sub-agents) it spawned — present only when it delegated. The true total
@@ -3647,9 +3742,15 @@ export type TaskEvent = ({
      * (one event per attachment; a multi-attachment boundary still coalesces into ONE steer message
      * on the model lane). [c209-C]: the listing family's FIRST-FRAME deliveries (initial roster /
      * `<skills>` block riding the first user message, not a steer) emit the same echo frames.
+     *
+     * `git_status` (env-tail migration, additive member): the git-status frame — the turn-dynamic
+     * git facts' carrier since they left the system prompt. Emitted at the frame's append RECEIPT
+     * (first-frame / resume-continuation / compaction re-assert deliveries alike). Its `preview`
+     * is a CONSTANT wording on purpose (never frame bytes): branch names and status text are
+     * repo-controlled and must not enter the event telemetry plane through this echo.
      */
     type: "steering_injected";
-    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification";
+    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
     preview: string;
 } & TaskEventIdentity) | ({
     /**
@@ -3790,6 +3891,18 @@ export type TaskEvent = ({
      * read absence as "not an agent".
      */
     taskType?: DelegationTaskType;
+    /**
+     * #258 — the registry row's STOP-CYCLE generation this tick reports from (fresh
+     * spawn = 1, every launched revival bumps it), the same counter `TaskNotificationPayload.seq`
+     * and `BackgroundChildEvent.seq` already speak — one axis, not a third spelling. It answers
+     * the one question a fleet consumer cannot otherwise decide when a frame arrives late: "late
+     * first frame of the cycle I know (same value), or a revived run I have not folded yet
+     * (higher value)?" Advisory observation, stamped at spawn/revive from the registry's own
+     * counter; the settle-time ledger stays the authority. ABSENT is a fact, not a gap: a run
+     * with no `a*` registry row (a SYNCHRONOUS delegated child, a workflow `wa*` agent, a
+     * top-level run) has no generation concept, and absence must never be read as "cycle 1".
+     */
+    seq?: number;
     /** [1611] workflow-lane self-identification (server field-proof: the SSE-forwarded tick of a
      *  WORKFLOW child previously carried a bare uuid with no workflow identity — indistinguishable
      *  from an unknown nested subagent; the fleet lane had `wa*`+workflowRunId but this lane had
@@ -4294,12 +4407,14 @@ export interface BackgroundChildEvent {
     resumable?: boolean;
     /** terminal: the settled status. */
     status?: "completed" | "killed" | "failed";
-    /** terminal (PAIR-REVIEW-01 C-3 half): the stop-cycle number — MIRROR of the sibling
-     *  task_notification's `TaskNotificationPayload.seq` (same settle, same X3 snapshot), so a
-     *  fleet-lane consumer can key multi-cycle events (`taskId:status[:seq]`) without the notify lane.
-     *  Same honest downgrade: present whenever a cycle number is knowable (the retain ledger's `cycleSeq`,
-     *  or the durable row's `seq` on a tier-3 revival / parked resume), absent when neither carrier exists
-     *  (single-cycle child; forging a period would lie). */
+    /** terminal + spawn/tick (#258 widened the carriers): the stop-cycle number — on a TERMINAL frame
+     *  a MIRROR of the sibling task_notification's `TaskNotificationPayload.seq` (same settle, same X3
+     *  snapshot); on SPAWN and TICK frames the registry row's generation at emit (fresh spawn = 1, a
+     *  revived cycle's bumped counter), so a fleet consumer can tell a LATE first frame from a revived
+     *  cycle's frame without waiting for the terminal. One axis with `task_progress`'s `seq` — the tick
+     *  mirrors the frame's own stamp. Same honest downgrade as ever: present whenever a cycle number is
+     *  knowable (the registry handle / retain ledger's `cycleSeq`, the durable row's `seq` on a tier-3
+     *  revival / parked resume), absent when no carrier exists (forging a period would lie). */
     seq?: number;
     /** terminal, P1-3(黑板 [1920]/[1921]/[1924]/[1925]): the cross-channel completion correlation id —
      *  MIRROR of the sibling task_notification's `TaskNotificationPayload.completionId` (same settle,

package/dist/engine/harness/types.d.ts

@@ -498,6 +498,53 @@ export interface WorkspaceState {
 export interface WorkspaceStateEntry extends SessionTreeEntryBase, WorkspaceState {
     type: "workspace_state";
 }
+/** The closed kind set of a git-status announcement (the availability half of the `(kind, hash)`
+ *  comparison tuple): `full` = five-segment snapshot frame; `degraded` = branch+dirty two-line frame
+ *  (the snapshot round-trip failed while the basic probe succeeded); `unavailable` / `non-repo` =
+ *  tombstone frames announcing that earlier git frames no longer describe the tree. */
+export type GitAnnouncementKind = "full" | "degraded" | "unavailable" | "non-repo";
+/**
+ * The git-status frame ANNOUNCED STATE — which rendered git view the model has last been shown on
+ * this branch, as a `(kind, hash)` tuple (hash = content hash of the rendered frame body with the
+ * frame format version and the canonical repo root bound into the digest domain). Two-phase receipt
+ * protocol: `pending: true` = a re-announcement is OWED but its frame append has not produced a
+ * receipt (a compaction restates the tuple as pending in the same CAS that lands the summary; the
+ * announced form is written only once the frame's own append returned an entry id) — any reader
+ * that finds pending nearest MUST conservatively re-announce. `entryId` = the session entry of the
+ * message CARRYING the announced frame; an announced state whose entryId is not on the active
+ * branch (rewind cut it) is treated as pending by the read walk (branch-authority read ladder).
+ */
+export interface GitAnnouncementState {
+    kind: GitAnnouncementKind;
+    hash: string;
+    /** Session entry id of the message carrying the announced frame (absent on a pending restatement). */
+    entryId?: string;
+    /** Two-phase receipt: the tuple is owed but its frame append has no receipt yet. */
+    pending?: true;
+}
+/**
+ * The git-status announced state as a FIRST-CLASS typed entry (same snapshot doctrine as
+ * {@link AnnouncedListingEntry}): the nearest carrier on the branch IS the announced state.
+ * Written at every frame COMMIT point (first-frame receipt / resume-continuation receipt /
+ * compaction re-assertion receipt); a compaction additionally restates the tuple as `pending`
+ * inside its own `details.gitAnnouncement` (same-CAS with the new baseline) until the re-asserted
+ * frame's append receipt lands. The checkpoint mirror (`CheckpointState.gitAnnouncement`) is the
+ * lower seed rung, consulted only when the branch carries no mirror at all.
+ */
+export interface GitAnnouncementEntry extends SessionTreeEntryBase, GitAnnouncementState {
+    type: "git_announcement";
+}
+/** Bounded cap for {@link normalizeGitAnnouncement} entry ids (self-generated ids are short; an
+ *  oversize value is a forgery signal, same posture as the sibling caps). */
+export declare const GIT_ANNOUNCEMENT_MAX_ENTRY_ID_CHARS = 256;
+/**
+ * Strict shape gate for the git announced state — the SINGLE normalization the read walk, the
+ * public append, and the import-validate door all use (the {@link normalizeAnnouncedListing}
+ * posture). Returns a shaped copy carrying ONLY the known keys, or undefined when the value is not
+ * structurally valid: closed kind set, full `sha256:<hex64>` hash grammar (a prefix-only check
+ * would accept junk), bounded entryId, `pending` only as literal `true`.
+ */
+export declare function normalizeGitAnnouncement(v: unknown): GitAnnouncementState | undefined;
 /** Bounded cap for {@link normalizeWorkspaceState} paths (a sha is capped by its hex shape check). */
 export declare const WORKSPACE_STATE_MAX_PATH_CHARS = 4096;
 /**
@@ -544,7 +591,7 @@ export declare function normalizeAnnouncedListing(v: unknown): {
     models?: string[];
 } | undefined;
 /** All persisted session tree entry variants. */
-export type SessionTreeEntry = MessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | LeafEntry | PromptEpochEntry | AnnouncedListingEntry | WorkspaceStateEntry;
+export type SessionTreeEntry = MessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | LeafEntry | PromptEpochEntry | AnnouncedListingEntry | GitAnnouncementEntry | WorkspaceStateEntry;
 export interface SessionContext {
     messages: AgentMessage[];
     thinkingLevel: string;
@@ -684,6 +731,23 @@ export interface Session<TMetadata extends SessionMetadata = SessionMetadata> {
      *  epoch restatement) calls it with `?.()` — an implementer without it degrades to the pre-epoch
      *  path (no restatement), never a crash. */
     getPromptEpoch?(): Promise<import("../../prompt-assembly/epoch.js").PromptEpochDescriptor | undefined>;
+    /** Persist the git-status announced state as a first-class {@link GitAnnouncementEntry}
+     *  (snapshot semantics; see `Session.appendGitAnnouncement`). OPTIONAL on the interface — same
+     *  external-implementer posture as `getPromptEpoch`; consumers call it with `?.()` and an
+     *  implementer without it degrades to conservative re-announcement every leg (duplicate-tolerant
+     *  by design), never a crash. */
+    appendGitAnnouncement?(state: GitAnnouncementState): Promise<string>;
+    /** Branch-authority read of the git announced state (see `Session.getGitAnnouncement`): nearest
+     *  carrier on the active branch, with a pending restatement — or an announced state whose frame
+     *  entryId is NOT on the active branch — surfaced as `status:"pending"` (the reader must
+     *  conservatively re-announce). Undefined ⇒ no carrier visible on this branch. OPTIONAL, same
+     *  posture as `appendGitAnnouncement`. */
+    getGitAnnouncement?(): Promise<{
+        kind: GitAnnouncementKind;
+        hash: string;
+        status: "announced" | "pending";
+        entryId?: string;
+    } | undefined>;
 }
 export interface SessionCreateOptions {
     id?: string;

package/dist/engine/harness/types.js

@@ -66,6 +66,26 @@ export class AgentHarnessError extends Error {
         this.code = code;
     }
 }
+export const GIT_ANNOUNCEMENT_MAX_ENTRY_ID_CHARS = 256;
+export function normalizeGitAnnouncement(v) {
+    if (typeof v !== "object" || v === null)
+        return undefined;
+    const src = v;
+    if (src.kind !== "full" && src.kind !== "degraded" && src.kind !== "unavailable" && src.kind !== "non-repo")
+        return undefined;
+    if (typeof src.hash !== "string" || !/^sha256:[0-9a-f]{64}$/.test(src.hash))
+        return undefined;
+    if (src.entryId !== undefined && (typeof src.entryId !== "string" || src.entryId.length === 0 || src.entryId.length > GIT_ANNOUNCEMENT_MAX_ENTRY_ID_CHARS))
+        return undefined;
+    if (src.pending !== undefined && src.pending !== true)
+        return undefined;
+    return {
+        kind: src.kind,
+        hash: src.hash,
+        ...(src.entryId !== undefined ? { entryId: src.entryId } : {}),
+        ...(src.pending === true ? { pending: true } : {}),
+    };
+}
 export const WORKSPACE_STATE_MAX_PATH_CHARS = 4096;
 export function normalizeWorkspaceState(value) {
     if (value === null || typeof value !== "object")

package/dist/engine/session/import-validate.js

@@ -1,4 +1,4 @@
-import { SessionError, normalizeAnnouncedListing, normalizeWorkspaceState, normalizeCompactionStateCarrier, isValidThinkingLevelChange, isValidModelChange, isOptionalDisplayString, } from "../harness/types.js";
+import { SessionError, normalizeAnnouncedListing, normalizeGitAnnouncement, normalizeWorkspaceState, normalizeCompactionStateCarrier, isValidThinkingLevelChange, isValidModelChange, isOptionalDisplayString, } from "../harness/types.js";
 import { leafIdAfterEntry } from "./storage-base.js";
 import { parseSessionTimestampMs } from "./timestamps.js";
 import { flattenableUserText, normalizeEngineSegments } from "../../core/untrusted-text.js";
@@ -87,6 +87,11 @@ export class StreamingImportValidator {
                 throw new SessionError("invalid_session", `workspace_state entry "${e.id}" is structurally invalid`);
             }
         }
+        else if (e.type === "git_announcement") {
+            if (!normalizeGitAnnouncement(e)) {
+                throw new SessionError("invalid_session", `git_announcement entry "${e.id}" is structurally invalid`);
+            }
+        }
         if (e.type === "thinking_level_change" && !isValidThinkingLevelChange(e)) {
             throw new SessionError("invalid_session", `thinking_level_change entry "${e.id}" carries an invalid thinkingLevel`);
         }
@@ -119,6 +124,10 @@ export class StreamingImportValidator {
             if (restatedListings !== undefined && !normalizeAnnouncedListing(restatedListings)) {
                 throw new SessionError("invalid_session", `compaction "${e.id}" carries a structurally invalid announcedListings restatement`);
             }
+            const restatedGit = e.details?.gitAnnouncement;
+            if (restatedGit !== undefined && !normalizeGitAnnouncement(restatedGit)) {
+                throw new SessionError("invalid_session", `compaction "${e.id}" carries a structurally invalid gitAnnouncement restatement`);
+            }
             const carrier = e.details;
             const shaped = normalizeCompactionStateCarrier(e.details);
             if (carrier?.thinkingLevel !== undefined && shaped.thinkingLevel === undefined) {

package/dist/engine/session/session.d.ts

@@ -1,6 +1,6 @@
 import type { ImageContent, TextContent } from "../llm/index.js";
 import type { AgentMessage } from "../loop/types.js";
-import type { Session, SessionContext, SessionMetadata, SessionStorage, SessionTreeEntry, WorkspaceState } from "../harness/types.js";
+import type { GitAnnouncementState, Session, SessionContext, SessionMetadata, SessionStorage, SessionTreeEntry, WorkspaceState } from "../harness/types.js";
 import type { BuildContextOptions } from "../harness/types.js";
 import type { PromptEpochDescriptor } from "../../prompt-assembly/epoch.js";
 /** Build model context from the active session branch and its latest state markers.
@@ -45,6 +45,31 @@ export declare class StoredSession<TMetadata extends SessionMetadata = SessionMe
         skills?: readonly string[];
         models?: readonly string[];
     }): Promise<string>;
+    /**
+     * Git-status frame announced state (branch-authority mirror): persist the `(kind, hash)` tuple —
+     * announced form carries the frame's own entry id; a compaction restates the tuple as `pending`
+     * inside its `details.gitAnnouncement` instead (same-CAS with the new baseline). Called
+     * best-effort at every frame COMMIT point (append receipt in hand) — an append failure degrades
+     * to a conservative re-announcement on the next leg (duplicate-tolerant), never fails the run.
+     */
+    appendGitAnnouncement(state: GitAnnouncementState): Promise<string>;
+    /**
+     * Branch-authority read of the git announced state: the nearest carrier walking back from the
+     * leaf (a `git_announcement` entry or a compaction's `details.gitAnnouncement` restatement;
+     * SNAPSHOT semantics — first hit wins). The pending gate is a MANDATORY one: a nearest carrier
+     * that is pending, or an announced carrier whose frame entryId is NOT on the active branch (a
+     * rewind cut the frame while a descendant mirror survived), reads as `status:"pending"` — the
+     * caller must conservatively re-announce rather than trust a mirror whose frame the model cannot
+     * see. Malformed carriers are skipped (defense in depth behind the import door). Undefined ⇒ no
+     * carrier visible on this branch (pre-migration session / bounded-tail floor cut every carrier) —
+     * callers fall back to the checkpoint mirror rung, then to conservative re-announcement.
+     */
+    getGitAnnouncement(): Promise<{
+        kind: GitAnnouncementState["kind"];
+        hash: string;
+        status: "announced" | "pending";
+        entryId?: string;
+    } | undefined>;
     /**
      * design/155 (cli [1580]): persist the settle-time workspace state (tracked cwd + active
      * EnterWorktree session) as a first-class typed entry. Called best-effort at task settle when the
@@ -115,3 +140,14 @@ export declare class StoredSession<TMetadata extends SessionMetadata = SessionMe
     appendLabel(targetId: string, label: string | undefined): Promise<string>;
     appendSessionName(name: string): Promise<string>;
 }
+/**
+ * Falsification round 1 (F3) — is `entryId` not merely ON the active branch but inside the region
+ * a context rebuild can actually contain? A branch walk sees the whole tree; `buildSessionContext`
+ * replays only [latest compaction's firstKeptEntryId .. leaf] (plus the summary). A git frame that
+ * sits BEFORE the latest compaction's kept tail is therefore gone from every future request even
+ * though its id is a legitimate branch member — an announced mirror pointing at it must read as
+ * PENDING (re-announce), or the announced hash would suppress re-sends of bytes the model can no
+ * longer see. Shared by the session mirror walk and the run loop's checkpoint seeding rung (one
+ * rule, both readers). Conservative on damage: an unresolvable firstKeptEntryId reads as invisible.
+ */
+export declare function gitFrameContextVisible(branch: SessionTreeEntry[], entryId: string): boolean;

package/dist/engine/session/session.js

@@ -1,5 +1,5 @@
 import { asAgentMessage, createCompactionSummaryMessage, createCustomMessage, } from "../harness/messages.js";
-import { SessionError, isValidModelChange, normalizeAnnouncedListing, normalizeCompactionStateCarrier, normalizeWorkspaceState } from "../harness/types.js";
+import { SessionError, isValidModelChange, normalizeAnnouncedListing, normalizeCompactionStateCarrier, normalizeGitAnnouncement, normalizeWorkspaceState } from "../harness/types.js";
 import { normalizePromptEpoch } from "../../prompt-assembly/epoch.js";
 import { budgetInvokedSkillsRetention, readElidedMessages, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../compaction/utils.js";
 const RETENTION_CLAMP_DEFAULT_CHARS_PER_TOKEN = 4;
@@ -181,6 +181,39 @@ export class StoredSession {
             ...shaped,
         });
     }
+    async appendGitAnnouncement(state) {
+        const shaped = normalizeGitAnnouncement(state);
+        if (!shaped) {
+            throw new SessionError("invalid_entry", "appendGitAnnouncement: state is not a structurally valid git announcement (closed kind, sha256 hash, bounded entryId)");
+        }
+        return this.appendTypedEntry({
+            type: "git_announcement",
+            id: await this.storage.createEntryId(),
+            parentId: await this.storage.getLeafId(),
+            timestamp: new Date().toISOString(),
+            ...shaped,
+        });
+    }
+    async getGitAnnouncement() {
+        const branch = await this.getBranch();
+        for (let i = branch.length - 1; i >= 0; i--) {
+            const entry = branch[i];
+            let carried;
+            if (entry.type === "git_announcement") {
+                carried = normalizeGitAnnouncement(entry);
+            }
+            else if (entry.type === "compaction") {
+                carried = normalizeGitAnnouncement(entry.details?.gitAnnouncement);
+            }
+            if (carried === undefined)
+                continue;
+            const announced = carried.pending !== true && carried.entryId !== undefined && gitFrameContextVisible(branch, carried.entryId);
+            return announced
+                ? { kind: carried.kind, hash: carried.hash, status: "announced", entryId: carried.entryId }
+                : { kind: carried.kind, hash: carried.hash, status: "pending" };
+        }
+        return undefined;
+    }
     async appendWorkspaceState(state) {
         const shaped = normalizeWorkspaceState(state);
         if (!shaped) {
@@ -314,3 +347,25 @@ export class StoredSession {
         });
     }
 }
+export function gitFrameContextVisible(branch, entryId) {
+    let frameIdx = -1;
+    let compactionIdx = -1;
+    let firstKeptId;
+    for (let i = 0; i < branch.length; i++) {
+        const e = branch[i];
+        if (e.id === entryId)
+            frameIdx = i;
+        if (e.type === "compaction") {
+            compactionIdx = i;
+            firstKeptId = e.firstKeptEntryId;
+        }
+    }
+    if (frameIdx === -1)
+        return false;
+    if (compactionIdx === -1 || frameIdx > compactionIdx)
+        return true;
+    if (firstKeptId === undefined)
+        return false;
+    const keptIdx = branch.findIndex((e) => e.id === firstKeptId);
+    return keptIdx !== -1 && frameIdx >= keptIdx;
+}

package/dist/index.d.ts

@@ -164,7 +164,7 @@ export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootA
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./stores/file/adoption/adopt.js";
 export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, type PersistedRuleHit, type PersistedRuleUnreadable, type PersistedRuleAnswer, normalizePersistedRuleHit, type Hooks, type HookToolContext, type HookEnvCapabilities, type HookToolOutput, type PreToolUseResult, type PostToolUseResult, type UserPromptSubmitResult, type HookToolFailure, type PostToolUseFailureResult, type PostToolBatchCall, type PostToolBatchResult, type PreCompactContext, type PreCompactResult, type PostCompactContext, type StopFailureContext, type PermissionDeniedPayload, type PermissionDeniedSource, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, type NormalizedMemorySpec, type MemorySpecInput, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, type Embedder, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, type UtilityGate, type MemoryStore, type MemoryVectorMode, type ScoredMemory, type MemoryNoteHeader, type MemoryNoteRecord, type MemoryNoteType, type StructuredNoteInput, } from "./core/memory.js";
-export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, readV2HeaderHints, type V2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, } from "./core/memory-engine/index.js";
+export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, readV2HeaderHints, type V2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, type SharedMemoryStoreProvider, type SharedMemoryStoreReader, type SharedMemoryPagedList, type SharedMemoryStoreInfo, type SharedMemoryDocumentEntry, type SharedMemorySnapshot, type SharedMemoryRequestContext, type MemoryListDetails, type MemoryReadDetails, } from "./core/shared-memory/types.js";
 export { sharedMemoryStoreContract, type SharedMemoryFixture, type SharedMemoryStoreContractHooks, } from "./core/shared-memory/contract.js";
 export { termSet, jaccardDistance, cosineDistance } from "./core/memory-vector.js";
@@ -254,7 +254,7 @@ export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, EngineNotice, RuntimeCaps, BackgroundChildEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, EngineNotice, RuntimeCaps, BackgroundChildEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";

package/dist/index.js

@@ -126,7 +126,7 @@ export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootA
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./stores/file/adoption/adopt.js";
 export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, normalizePersistedRuleHit, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, } from "./core/memory.js";
-export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, readV2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, migrateScope, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, syncMemoryScope, } from "./core/memory-engine/index.js";
+export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, readV2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, erasureSelectHash, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, migrateScope, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, syncMemoryScope, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, } from "./core/shared-memory/types.js";
 export { sharedMemoryStoreContract, } from "./core/shared-memory/contract.js";
 export { termSet, jaccardDistance, cosineDistance } from "./core/memory-vector.js";

package/dist/internal/harness-types.d.ts

@@ -12,4 +12,5 @@ export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErro
 export type { ExecutionEnvExecOptions, ExecResult } from "../engine/harness/types.js";
 export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/types.js";
 export type { ActiveWorktreeSession, WorkspaceState } from "../engine/harness/types.js";
+export type { GitAnnouncementKind, GitAnnouncementState } from "../engine/harness/types.js";
 export type { SessionForkOptions } from "../engine/harness/types.js";

package/dist/internal/harness.d.ts

@@ -23,3 +23,5 @@ export { InMemorySessionStorage } from "../engine/session/memory-storage.js";
 export { InMemorySessionRepo } from "../engine/session/memory-repo.js";
 export { uuidv7 } from "../engine/session/uuid.js";
 export { SessionError } from "../engine/harness/types.js";
+export { normalizeGitAnnouncement } from "../engine/harness/types.js";
+export { gitFrameContextVisible } from "../engine/session/session.js";

package/dist/internal/harness.js

@@ -12,3 +12,5 @@ export { InMemorySessionStorage } from "../engine/session/memory-storage.js";
 export { InMemorySessionRepo } from "../engine/session/memory-repo.js";
 export { uuidv7 } from "../engine/session/uuid.js";
 export { SessionError } from "../engine/harness/types.js";
+export { normalizeGitAnnouncement } from "../engine/harness/types.js";
+export { gitFrameContextVisible } from "../engine/session/session.js";

package/dist/prompt-assembly/epoch.js

@@ -50,7 +50,7 @@ const PROBE_INPUTS_BASE = {
     roleBase: "\u0000probe-role\u0000",
     roleAppend: "\u0000probe-append\u0000",
     mcpInstructionsBlock: "\u0000probe-mcp\u0000",
-    environmentBlock: "\u0000probe-env\u0000",
+    environmentBlock: "\u0000probe-env@2\u0000",
     memoryBlock: "\u0000probe-memory\u0000",
     modelGuidance: "\u0000probe-guidance\u0000",
 };

package/dist/prompt-assembly/event-registry.js

@@ -13,6 +13,7 @@ export const EVENT_PROMPT_REGISTRY = new Map([
     { kind: "skills_listing", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderSkillsListingDelta" },
     { kind: "mcp_instructions", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderMcpInstructionsDelta" },
     { kind: "mcp_dropped_tools", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderMcpDroppedTools" },
+    { kind: "git_status", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "always", rendererRef: "git-status-frame.ts#renderGitStatusFrameBody" },
     { kind: "limit_approach_converge", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "runtask.ts#limitApproachFrames" },
     { kind: "limit_approach_deliver", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "runtask.ts#limitApproachFrames" },
     { kind: "final_verification", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "runtask.ts#final-verification" },

package/dist/prompts/default.d.ts

@@ -271,9 +271,13 @@ export interface EnvironmentFacts {
     cwd?: string;
     isGitRepo?: boolean;
     /** design/99 §E14 — the current git branch (remote = the container's repo). `"HEAD (detached)"` when on a
-     *  detached HEAD. Absent when not a git repo / no git. A prepare-time snapshot, like cwd (may go stale mid-run). */
+     *  detached HEAD. Absent when not a git repo / no git. A prepare-time snapshot, like cwd (may go stale mid-run).
+     *  env-tail migration (#254 shape): NO LONGER RENDERED by {@link buildEnvironmentContext} — the
+     *  branch is a turn-dynamic fact and rides the `git_status` frame instead; the field remains as a
+     *  structured data carrier for callers that assembled it. */
     gitBranch?: string;
-    /** design/99 §E14 — whether the working tree has uncommitted changes (`git status --porcelain` non-empty). */
+    /** design/99 §E14 — whether the working tree has uncommitted changes (`git status --porcelain` non-empty).
+     *  env-tail migration: NO LONGER RENDERED here (turn-dynamic; rides the `git_status` frame). */
     gitDirty?: boolean;
     /** design/99 §E14 — the working tree's toplevel (`git rev-parse --show-toplevel`). Lets the agent/shell know
      *  it may be in a linked worktree rather than the main checkout. */
@@ -319,10 +323,10 @@ export interface EnvironmentFacts {
     /** A1 — outbound-network posture; `none` renders an explicit downloads-will-fail caveat (TB
      *  autopsy 2026-07-05: agents burned budget retrying downloads in a no-egress sandbox). */
     sandboxEgress?: "none" | "allowlist" | "full";
-    /** H4 (CC 2.1.198 git snapshot) — the pre-rendered {@link buildGitSnapshot} block, appended to the
-     *  `# Environment` block as its own paragraph. A PREPARE-TIME snapshot by contract (its first line
-     *  self-declares "will not update during the conversation"); the date_change re-render carries it
-     *  unchanged. Absent when not a git repo / the probe failed (whole section skipped, CC-same). */
+    /** H4 (CC 2.1.198 git snapshot) — the pre-rendered {@link buildGitSnapshot} block. env-tail
+     *  migration (#254 shape): NO LONGER RENDERED by {@link buildEnvironmentContext} — the snapshot is
+     *  the turn-dynamic git view and rides the `git_status` frame (re-sent only when the rendered view
+     *  changes); the field remains as a structured data carrier for callers that assembled it. */
     gitSnapshot?: string;
     /** [1451] B-half — per-lane resume-continuity facts (deployment-supplied via `TaskSpec.envFacts.resumeFacts`,
      *  copied by prepare ONLY on a durable-resume leg). Each present field renders one honest sentence; absent
@@ -353,11 +357,20 @@ export interface EnvironmentFacts {
 export declare function buildScratchpadSection(scratchpadDir: string): string;
 /** CC 2.1.198 `Juo` — the git status truncation bound (chars) for {@link buildGitSnapshot}. */
 export declare const GIT_STATUS_MAX_CHARS = 2000;
+/** The CC-verbatim first paragraph of the git snapshot (CC 2.1.198 `Quo` head sentence). Kept as a
+ *  named constant so the git-status FRAME renderer (the snapshot's carrier since the env-tail
+ *  migration) can swap exactly this paragraph for its own update-semantics preamble — under the
+ *  frame protocol the snapshot IS re-sent when the visible view changes, so the "will not update"
+ *  claim would be false there. {@link buildGitSnapshot} itself still renders it byte-exact. */
+export declare const GIT_SNAPSHOT_CC_PREAMBLE = "This is the git status at the start of the conversation. Note that this status is a snapshot in time, and will not update during the conversation.";
 /**
  * H4 — the CC 2.1.198 ENV git snapshot block (B1/B2; template + truncation copy verified against
  * observed Claude Code v2.1.198 behavior). Pure renderer — the Runner gathers the raw values through the
  * ExecutionEnv seam (remote = the container's repo) and calls this once per prepareTask (a durable
- * resume re-prepares → re-snapshots, CC new-session 同型).
+ * resume re-prepares → re-snapshots, CC new-session 同型). env-tail migration (#254 shape): the
+ * rendered block now feeds the `git_status` TURN FRAME (src/core/runner/git-status-frame.ts, which
+ * swaps the {@link GIT_SNAPSHOT_CC_PREAMBLE} for an update-semantics preamble) instead of the
+ * `# Environment` system-prompt section — the template body itself stays CC-verbatim.
  *
  * Sanitization (deliberate CC deviation — CC injects raw): status/log/branch/user are REPO-controlled
  * text (filenames, commit subjects, a hostile clone's config) landing in the TRUSTED prompt region →