@sema-agent/core 5.35.0 → 5.36.0

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/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 →

package/dist/prompts/default.js

@@ -196,6 +196,7 @@ Only use \`/tmp\` if the user explicitly requests it.
 The scratchpad directory is session-specific, isolated from the user's project, and can generally be used without permission prompts. Treat it as ephemeral — it may not survive a long suspension or a resume on a different worker; keep durable outputs in the working directory.`;
 }
 export const GIT_STATUS_MAX_CHARS = 2000;
+export 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.";
 export function buildGitSnapshot(p) {
     const tool = p.statusToolName ?? "Bash";
     const status = sanitizeUntrustedText(p.status.trim());
@@ -205,7 +206,7 @@ export function buildGitSnapshot(p) {
             `\n... (truncated because it exceeds 2k characters. If you need more information, run "git status" using ${tool})`
         : status;
     return [
-        "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.",
+        GIT_SNAPSHOT_CC_PREAMBLE,
         `Current branch: ${inlineUntrusted(p.branch)}`,
         `Main branch (you will usually use this for PRs): ${inlineUntrusted(p.mainBranch)}`,
         ...(p.userName ? [`Git user: ${inlineUntrusted(p.userName)}`] : []),
@@ -255,10 +256,6 @@ export function buildEnvironmentContext(facts) {
     }
     if (facts.isGitRepo !== undefined)
         lines.push(`Is a git repository: ${facts.isGitRepo ? "yes" : "no"}`);
-    if (facts.gitBranch)
-        lines.push(`Git branch: ${inlineUntrusted(facts.gitBranch)}`);
-    if (facts.gitDirty !== undefined)
-        lines.push(`Git working tree: ${facts.gitDirty ? "has uncommitted changes" : "clean"}`);
     if (facts.gitWorktreeRoot)
         lines.push(`Git worktree root: ${inlineUntrusted(facts.gitWorktreeRoot)}`);
     if (facts.isLinkedWorktree) {
@@ -302,8 +299,6 @@ export function buildEnvironmentContext(facts) {
     }
     const base = lines.length > 0 ? `# Environment\n${lines.join("\n")}` : "";
     const sections = [base, ...(facts.scratchpadDir ? [buildScratchpadSection(facts.scratchpadDir)] : [])].filter((s) => s.length > 0);
-    if (facts.gitSnapshot)
-        sections.push(facts.gitSnapshot);
     return sections.join("\n\n");
 }
 export const CODE_AGENT_PROMPT = `You are a capable software-engineering agent that acts through tools.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.35.0",
+  "version": "5.36.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",