@akira-tl/forgerelay 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-09-04
+
+### Added
+
+- Extended `workspace.checkpoint` with `restore.preflight` and optimistic-concurrency-protected `restore`. Restore uses deterministic Git-visible working-tree snapshot identities, refuses stale preflight tokens before mutation, restores content without moving branch HEAD or rewriting history, leaves ignored files outside the restore model, does not reconstruct staged-versus-unstaged state, remains independent from managed-worktree recovery, and routes through the owning Execution ForgeRelay / explicit Composite member.
+
+## [0.9.2] - 2026-09-04
+
+### Added
+
+- Added persistent Workspace-owned `workspace.checkpoint` create/list/inspect/delete operations backed by immutable Git-visible working-tree snapshots. Checkpoints preserve stable Workspace identity across restart, close/reopen, managed-worktree backing recreation, and ordinary idle GC; ignored files stay excluded, Relay execution remains owned by the Execution ForgeRelay, Composite use remains explicit-member scoped, and no Core MCP tool was added.
+
 ## [0.9.1] - 2026-09-04
 
 ### Added

package/capabilities/workspace/workspace-checkpoints/GUIDE.md

@@ -0,0 +1,106 @@
+# Workspace Checkpoints
+
+`workspace.checkpoint` provides low-frequency, persistent checkpoints owned by the current filesystem Workspace. Checkpoints are immutable Git-backed snapshots intended for deliberate recovery/history workflows.
+
+## v0.9.3 surface
+
+Supported operations are:
+
+- `create` — create a named immutable checkpoint of the current Git-visible working tree.
+- `list` — return bounded checkpoint metadata, preserving checkpoint creation order.
+- `inspect` — return bounded metadata for one checkpoint.
+- `restore.preflight` — identify the selected checkpoint content snapshot and the current Git-visible working snapshot without mutating files.
+- `restore` — restore checkpoint content only when the caller supplies the still-current snapshot identity returned by preflight.
+- `delete` — explicitly delete one checkpoint and its ForgeRelay-owned Git ref.
+
+Restore is deliberately a two-step optimistic-concurrency operation. Do not replace it with checkout/reset, hidden merge/rebase behavior, or branch-history rewrites.
+
+## Create
+
+Use:
+
+```json
+{
+  "operation": "create",
+  "name": "before parser refactor"
+}
+```
+
+A checkpoint snapshots the current Git-visible working-tree content using a private temporary Git index. Creation does not move branch `HEAD`, write project history, modify files, or mutate the real staging index.
+
+The snapshot includes tracked files and non-ignored untracked files that Git would normally admit. Git-ignored files are excluded. Consequently Workspace checkpoints are **not a backup mechanism for secrets, ignored configuration, credentials, build caches, or other ignored files**.
+
+Checkpoint metadata includes a stable checkpoint id, user-provided name, creation timestamp, immutable snapshot commit id, base `HEAD`, and bounded file/addition/removal counts. It does not return patches or full file contents by default.
+
+## List and inspect
+
+Use `list` for discovery:
+
+```json
+{
+  "operation": "list",
+  "offset": 0,
+  "limit": 50
+}
+```
+
+Use `inspect` only after selecting an id:
+
+```json
+{
+  "operation": "inspect",
+  "checkpointId": "cp_0123456789"
+}
+```
+
+`list` and `inspect` expose bounded metadata only. Checkpoints do not move when `review.changes` advances its independent last-shown baseline.
+
+## Restore preflight and restore
+
+First preflight the selected checkpoint:
+
+```json
+{
+  "operation": "restore.preflight",
+  "checkpointId": "cp_0123456789"
+}
+```
+
+The result includes `checkpointSnapshot`, the immutable Git tree identity selected for restore, plus `currentSnapshot`, the deterministic Git tree identity of the current Git-visible working content. It also includes a bounded `restoreSummary`. Preflight does not mutate the Workspace.
+
+Then pass that exact `currentSnapshot` back as `expectedCurrentSnapshot`:
+
+```json
+{
+  "operation": "restore",
+  "checkpointId": "cp_0123456789",
+  "expectedCurrentSnapshot": "0123456789abcdef0123456789abcdef01234567"
+}
+```
+
+Immediately before applying content changes ForgeRelay recomputes the current Git-visible working snapshot. If it no longer matches `expectedCurrentSnapshot`, restore fails before mutation and the intervening edits remain untouched. Run preflight again before deciding whether to retry.
+
+A successful restore writes only ordinary working-tree content needed to reproduce the checkpoint's Git-visible tree. It does **not** move branch `HEAD`, rewrite commit history, merge/rebase, auto-commit, or use `git reset --hard` semantics. Ignored files remain outside the checkpoint/restore content model and are not intentionally changed.
+
+The 0.9 restore contract is **content-state only**. ForgeRelay does not reconstruct or promise the historical staged-versus-unstaged partition. Restore does not rewrite the real Git index; existing staging state may therefore differ from the restored working-tree content and should be inspected normally with Git afterward. Results expose `stagingStateRestored: false` to make this explicit.
+
+## Delete
+
+Deletion is explicit:
+
+```json
+{
+  "operation": "delete",
+  "checkpointId": "cp_0123456789"
+}
+```
+
+ForgeRelay verifies that the Workspace-owned Git ref still points at the checkpoint's recorded immutable commit before deleting it. A mismatched or missing ref is treated as inconsistent state rather than silently deleting something else.
+
+Ordinary Workspace close, process restart, idle Workspace cache GC, and managed-worktree backing replacement preserve checkpoints. Permanent `close_workspace { action: "delete" }` removes checkpoints owned by that Workspace identity.
+
+## Relay and Composite Workspaces
+
+Checkpoint ownership belongs to the Execution Workspace. Through Workspace Relay, checkpoint operations execute on the remote Execution ForgeRelay and persist there.
+
+A Composite Workspace does not own filesystem checkpoints itself. Pass an explicit `member` so the operation targets that member's persistent Workspace identity.

package/dist/mcp/server/core/capabilities/workspace-checkpoint.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export const workspaceCheckpointInputSchema = z.discriminatedUnion("operation", [
+    z.object({
+        operation: z.literal("create"),
+        name: z.string().trim().min(1).max(120),
+    }).strict(),
+    z.object({
+        operation: z.literal("list"),
+        offset: z.number().int().min(0).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+    }).strict(),
+    z.object({
+        operation: z.literal("inspect"),
+        checkpointId: z.string().regex(/^cp_[a-f0-9]{10}$/),
+    }).strict(),
+    z.object({
+        operation: z.literal("restore.preflight"),
+        checkpointId: z.string().regex(/^cp_[a-f0-9]{10}$/),
+    }).strict(),
+    z.object({
+        operation: z.literal("restore"),
+        checkpointId: z.string().regex(/^cp_[a-f0-9]{10}$/),
+        expectedCurrentSnapshot: z.string().regex(/^[a-f0-9]{40,64}$/),
+    }).strict(),
+    z.object({
+        operation: z.literal("delete"),
+        checkpointId: z.string().regex(/^cp_[a-f0-9]{10}$/),
+    }).strict(),
+]);

package/dist/mcp/server/core/capabilities.js

@@ -46,6 +46,12 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
         description: "Persistent Task Lists owned by the current Workspace.",
         whenToRead: "Read before creating or maintaining Workspace Tasks.",
     },
+    {
+        name: "workspace-checkpoints",
+        directory: "workspace/workspace-checkpoints",
+        description: "Immutable persistent Git-backed checkpoints owned by the current Workspace.",
+        whenToRead: "Read before creating, listing, inspecting, or deleting Workspace checkpoints.",
+    },
     {
         name: "batch-execution",
         description: "One-call execution of multiple independent ForgeRelay core operations.",
@@ -96,6 +102,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "code.intelligence",
         "workspace.tasks",
         "workspace.recovery",
+        "workspace.checkpoint",
     ];
     if (config.toolMode !== "codex") {
         capabilities.push("batch.execute");

package/dist/mcp/server/core/capability-registry.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { MAX_CODE_INTELLIGENCE_RESULT_LIMIT, } from "../../../lsp/code-intelligence-types.js";
 import { batchExecuteInputSchema, } from "../../operations/batch/types.js";
+import { workspaceCheckpointInputSchema, } from "./capabilities/workspace-checkpoint.js";
 export class CapabilityError extends Error {
     code;
     constructor(code, message) {
@@ -304,6 +305,18 @@ export function createCapabilityRegistry(dependencies) {
                     run: async (input, context, options) => dependencies.workspaceRecovery.run(input, context, options),
                 }]
             : []),
+        ...(dependencies.workspaceCheckpoint
+            ? [{
+                    name: "workspace.checkpoint",
+                    description: "Create, list, inspect, safely restore, or delete immutable Git-backed checkpoints owned by the current persistent Workspace.",
+                    guideName: "workspace-checkpoints",
+                    readGuideBeforeFirstUse: true,
+                    batchPolicy: "unsupported",
+                    inputSchema: workspaceCheckpointInputSchema,
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.workspaceCheckpoint?.available ?? false, dependencies.workspaceCheckpoint?.unavailableReason),
+                    run: async (input, context, options) => dependencies.workspaceCheckpoint.run(input, context, options),
+                }]
+            : []),
         ...(dependencies.workspaceTasks
             ? [{
                     name: "workspace.tasks",

package/dist/mcp/server/workspace/runtime/workspace-tools.js

@@ -15,7 +15,7 @@ const WRITE_TOOL_ANNOTATIONS = {
     openWorldHint: false,
 };
 export function registerWorkspaceAuxiliaryTools(options) {
-    const { server, config, workspaces, remoteWorkspaces, compositeWorkspaces, compositeTaskGuides, capabilityRegistry, coreOperations, activityLifecycle, hooks, workspaceTasks, taskReminders, activityQueries, compositeActivity, workspacePanelStates, processSessions, reviewCheckpoints, codeIntelligence, resolveExecutionTarget, prepareExecutionContext, hostScopeIdFor, presentExecutionResult, presentSemanticWorkResult, } = options;
+    const { server, config, workspaces, remoteWorkspaces, compositeWorkspaces, compositeTaskGuides, capabilityRegistry, coreOperations, activityLifecycle, hooks, workspaceTasks, workspaceCheckpoints, taskReminders, activityQueries, compositeActivity, workspacePanelStates, processSessions, reviewCheckpoints, codeIntelligence, resolveExecutionTarget, prepareExecutionContext, hostScopeIdFor, presentExecutionResult, presentSemanticWorkResult, } = options;
     registerAppTool(server, "workspace_instruction", {
         title: "Read Workspace instruction",
         description: "App-only lazy data source for one instruction file already advertised by the Workspace presentation. Reading through this UI source does not activate nested instructions or create an Activity.",
@@ -399,6 +399,7 @@ export function registerWorkspaceAuxiliaryTools(options) {
                 },
                 payload: { workspaceId: session.id, action: "delete", mode: session.mode },
                 operation: async () => {
+                    await workspaceCheckpoints.deleteWorkspace(session.id);
                     workspaces.deleteWorkspace(session.id);
                     workspaceTasks.deleteWorkspace(session.id);
                     taskReminders.forget(session.id);
@@ -444,6 +445,7 @@ export function registerWorkspaceAuxiliaryTools(options) {
                 },
                 payload: { workspaceId: session.id, action: "delete", mode: session.mode },
                 operation: async () => {
+                    await workspaceCheckpoints.deleteWorkspace(session.id);
                     workspaces.deleteWorkspace(session.id);
                     workspaceTasks.deleteWorkspace(session.id);
                     taskReminders.forget(session.id);
@@ -509,6 +511,7 @@ export function registerWorkspaceAuxiliaryTools(options) {
                     }
                     await Promise.all(physicalWorkspaceIds.map((id) => reviewCheckpoints.releaseWorkspace(id)));
                     if (action === "delete") {
+                        await workspaceCheckpoints.deleteWorkspace(workspace.id);
                         workspaces.deleteWorkspace(workspace.id);
                         workspaceTasks.deleteWorkspace(workspace.id);
                         taskReminders.forget(workspace.id);

package/dist/server.js

@@ -26,6 +26,7 @@ import { shutdownHttpServer } from "./mcp/server/transport/server-shutdown.js";
 import { formatPathForPrompt } from "./workspaces/resources/skills.js";
 import { WorkspaceTaskReminderTracker } from "./workspaces/tasks/workspace-task-reminders.js";
 import { WorkspaceTaskStore } from "./workspaces/tasks/workspace-tasks.js";
+import { WorkspaceCheckpointStore } from "./workspaces/state/workspace-checkpoints.js";
 import { compactWorkspacePresentation } from "./workspaces/presentation/workspace-presentation.js";
 import { formatAgentsPath } from "./workspaces.js";
 import { summarizeSubagentProfile } from "./subagents/profiles.js";
@@ -49,6 +50,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     const compositeWorkspaces = options.compositeWorkspaces
         ?? new CompositeWorkspaceRegistry(config.stateDir);
     const workspaceTasks = new WorkspaceTaskStore(config.stateDir);
+    const workspaceCheckpoints = new WorkspaceCheckpointStore(config.stateDir);
     const taskReminders = options.taskReminders
         ?? new WorkspaceTaskReminderTracker(config.taskReminderInterval, workspaceTasks);
     const compositeTaskGuides = loadCapabilityGuides(config).filter((guide) => guide.name === "workspace-tasks");
@@ -137,6 +139,34 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 value: await workspaces.runManagedWorktreeRecovery(context.workspaceId, input.operation),
             }),
         },
+        workspaceCheckpoint: {
+            available: true,
+            run: async (input, context) => {
+                const root = requireCapabilityWorkspaceRoot(context);
+                switch (input.operation) {
+                    case "create":
+                        return {
+                            value: {
+                                workspaceId: context.workspaceId,
+                                checkpoint: await workspaceCheckpoints.create(context.workspaceId, root, input.name),
+                                ignoredFilesIncluded: false,
+                            },
+                        };
+                    case "list":
+                        return { value: await workspaceCheckpoints.list(context.workspaceId, root, input) };
+                    case "inspect":
+                        return { value: await workspaceCheckpoints.inspect(context.workspaceId, root, input.checkpointId) };
+                    case "restore.preflight":
+                        return { value: await workspaceCheckpoints.preflightRestore(context.workspaceId, root, input.checkpointId) };
+                    case "restore":
+                        return {
+                            value: await workspaceCheckpoints.restore(context.workspaceId, root, input.checkpointId, input.expectedCurrentSnapshot),
+                        };
+                    case "delete":
+                        return { value: await workspaceCheckpoints.delete(context.workspaceId, root, input.checkpointId) };
+                }
+            },
+        },
         workspaceTasks: {
             available: true,
             run: async (input, context) => {
@@ -451,7 +481,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerWorkspaceAuxiliaryTools({
         server, config, workspaces, remoteWorkspaces, compositeWorkspaces, compositeTaskGuides, capabilityRegistry,
-        coreOperations, activityLifecycle, hooks, workspaceTasks, taskReminders, activityQueries, compositeActivity,
+        coreOperations, activityLifecycle, hooks, workspaceTasks, workspaceCheckpoints, taskReminders, activityQueries, compositeActivity,
         workspacePanelStates, processSessions, reviewCheckpoints, codeIntelligence, resolveExecutionTarget,
         prepareExecutionContext, hostScopeIdFor, presentExecutionResult, presentSemanticWorkResult,
     });

package/dist/workspaces/state/workspace-checkpoints.js

@@ -0,0 +1,524 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import * as z from "zod/v4";
+import { getGitEligibility, git, safeWorkspaceRefSegment } from "../git/git.js";
+const CHECKPOINT_STATE_VERSION = 1;
+const CHECKPOINT_REF_PREFIX = "refs/forgerelay/checkpoints";
+const MAX_CHECKPOINTS = 500;
+const MAX_CHECKPOINT_NAME_LENGTH = 120;
+const MAX_CHECKPOINT_STATE_BYTES = 1024 * 1024;
+const checkpointSchema = z.object({
+    id: z.string().regex(/^cp_[a-f0-9]{10}$/),
+    name: z.string().min(1).max(MAX_CHECKPOINT_NAME_LENGTH),
+    createdAt: z.string().min(1),
+    commit: z.string().regex(/^[a-f0-9]{40,64}$/),
+    baseHead: z.string().regex(/^[a-f0-9]{40,64}$/),
+    summary: z.object({
+        files: z.number().int().nonnegative(),
+        additions: z.number().int().nonnegative(),
+        removals: z.number().int().nonnegative(),
+    }).strict(),
+}).strict();
+const checkpointStateSchema = z.object({
+    version: z.literal(CHECKPOINT_STATE_VERSION),
+    revision: z.number().int().nonnegative(),
+    gitCommonDir: z.string().min(1),
+    checkpoints: z.array(checkpointSchema).max(MAX_CHECKPOINTS),
+}).strict().superRefine((state, context) => {
+    const ids = new Set();
+    for (const [index, checkpoint] of state.checkpoints.entries()) {
+        if (ids.has(checkpoint.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["checkpoints", index, "id"],
+                message: `Duplicate checkpoint id ${checkpoint.id}.`,
+            });
+        }
+        ids.add(checkpoint.id);
+    }
+});
+export class WorkspaceCheckpointStore {
+    stateDir;
+    now;
+    mutationChains = new Map();
+    constructor(stateDir, now = () => new Date()) {
+        this.stateDir = stateDir;
+        this.now = now;
+    }
+    async create(workspaceId, workspaceRoot, name) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const checkpointName = normalizeCheckpointName(name);
+        return this.runMutation(id, async () => {
+            const repository = await resolveRepository(workspaceRoot);
+            const loaded = this.tryReadState(id);
+            if (loaded)
+                await assertSameRepository(loaded.gitCommonDir, repository.gitCommonDir, id);
+            if ((loaded?.checkpoints.length ?? 0) >= MAX_CHECKPOINTS) {
+                throw new Error(`Workspace checkpoint limit is ${MAX_CHECKPOINTS}. Delete an older checkpoint first.`);
+            }
+            const checkpointId = `cp_${randomBytes(5).toString("hex")}`;
+            const ref = checkpointRef(id, checkpointId);
+            const snapshot = await createWorkingTreeSnapshot(repository.gitRoot);
+            const checkpoint = {
+                id: checkpointId,
+                name: checkpointName,
+                createdAt: this.now().toISOString(),
+                commit: snapshot.commit,
+                baseHead: snapshot.baseHead,
+                summary: snapshot.summary,
+            };
+            await updateRef(repository.gitCommonDir, ref, checkpoint.commit, zeroOid(checkpoint.commit.length));
+            try {
+                this.writeState(id, {
+                    version: CHECKPOINT_STATE_VERSION,
+                    revision: (loaded?.revision ?? 0) + 1,
+                    gitCommonDir: repository.gitCommonDir,
+                    checkpoints: [...(loaded?.checkpoints ?? []), checkpoint],
+                });
+            }
+            catch (error) {
+                await deleteRef(repository.gitCommonDir, ref, checkpoint.commit).catch(() => undefined);
+                throw error;
+            }
+            return { ...checkpoint, summary: { ...checkpoint.summary } };
+        });
+    }
+    async list(workspaceId, workspaceRoot, input = {}) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const repository = await resolveRepository(workspaceRoot);
+        const state = this.tryReadState(id);
+        if (state)
+            await assertSameRepository(state.gitCommonDir, repository.gitCommonDir, id);
+        const offset = normalizeOffset(input.offset);
+        const limit = normalizeLimit(input.limit);
+        const checkpoints = state?.checkpoints ?? [];
+        return {
+            workspaceId: id,
+            checkpoints: checkpoints.slice(offset, offset + limit).map(cloneCheckpoint),
+            page: {
+                offset,
+                limit,
+                total: checkpoints.length,
+                hasMore: offset + limit < checkpoints.length,
+            },
+            ignoredFilesIncluded: false,
+        };
+    }
+    async inspect(workspaceId, workspaceRoot, checkpointId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const cpId = normalizeCheckpointId(checkpointId);
+        const repository = await resolveRepository(workspaceRoot);
+        const state = this.requireState(id);
+        await assertSameRepository(state.gitCommonDir, repository.gitCommonDir, id);
+        const checkpoint = requireCheckpoint(state, cpId);
+        await assertCheckpointRef(state.gitCommonDir, id, checkpoint);
+        return { workspaceId: id, checkpoint: cloneCheckpoint(checkpoint), ignoredFilesIncluded: false };
+    }
+    async preflightRestore(workspaceId, workspaceRoot, checkpointId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const cpId = normalizeCheckpointId(checkpointId);
+        const repository = await resolveRepository(workspaceRoot);
+        const state = this.requireState(id);
+        await assertSameRepository(state.gitCommonDir, repository.gitCommonDir, id);
+        const checkpoint = requireCheckpoint(state, cpId);
+        await assertCheckpointRef(state.gitCommonDir, id, checkpoint);
+        const [checkpointSnapshot, current] = await Promise.all([
+            checkpointTree(repository.gitRoot, checkpoint.commit),
+            snapshotWorkingTree(repository.gitRoot),
+        ]);
+        const restoreSummary = summarizeNumstat((await git(repository.gitRoot, [
+            "diff",
+            "--numstat",
+            "-z",
+            "--no-renames",
+            current.tree,
+            checkpointSnapshot,
+            "--",
+            ".",
+        ], { maxBuffer: 50 * 1024 * 1024 })).stdout);
+        return {
+            workspaceId: id,
+            checkpoint: cloneCheckpoint(checkpoint),
+            checkpointSnapshot,
+            currentSnapshot: current.tree,
+            restoreSummary,
+            ignoredFilesIncluded: false,
+            stagingStateRestored: false,
+        };
+    }
+    async restore(workspaceId, workspaceRoot, checkpointId, expectedCurrentSnapshot) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const cpId = normalizeCheckpointId(checkpointId);
+        const expected = normalizeSnapshotId(expectedCurrentSnapshot);
+        return this.runMutation(id, async () => {
+            const repository = await resolveRepository(workspaceRoot);
+            const state = this.requireState(id);
+            await assertSameRepository(state.gitCommonDir, repository.gitCommonDir, id);
+            const checkpoint = requireCheckpoint(state, cpId);
+            await assertCheckpointRef(state.gitCommonDir, id, checkpoint);
+            const checkpointSnapshot = await checkpointTree(repository.gitRoot, checkpoint.commit);
+            const current = await snapshotWorkingTree(repository.gitRoot);
+            assertExpectedCurrentSnapshot(expected, current.tree);
+            if (current.tree !== checkpointSnapshot) {
+                await applyTreeRestore(repository.gitRoot, current.tree, checkpointSnapshot, async () => {
+                    const immediate = await snapshotWorkingTree(repository.gitRoot);
+                    assertExpectedCurrentSnapshot(expected, immediate.tree);
+                });
+            }
+            const restored = await snapshotWorkingTree(repository.gitRoot);
+            if (restored.tree !== checkpointSnapshot) {
+                throw new Error(`Workspace checkpoint restore did not reproduce checkpoint snapshot ${checkpointSnapshot}; current snapshot is ${restored.tree}.`);
+            }
+            return {
+                workspaceId: id,
+                checkpointId: cpId,
+                restored: true,
+                checkpointSnapshot,
+                previousSnapshot: current.tree,
+                currentSnapshot: restored.tree,
+                ignoredFilesIncluded: false,
+                stagingStateRestored: false,
+            };
+        });
+    }
+    async delete(workspaceId, workspaceRoot, checkpointId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const cpId = normalizeCheckpointId(checkpointId);
+        return this.runMutation(id, async () => {
+            const repository = await resolveRepository(workspaceRoot);
+            const state = this.requireState(id);
+            await assertSameRepository(state.gitCommonDir, repository.gitCommonDir, id);
+            const checkpoint = requireCheckpoint(state, cpId);
+            const ref = checkpointRef(id, cpId);
+            await deleteRef(state.gitCommonDir, ref, checkpoint.commit);
+            try {
+                this.writeState(id, {
+                    ...state,
+                    revision: state.revision + 1,
+                    checkpoints: state.checkpoints.filter((candidate) => candidate.id !== cpId),
+                });
+            }
+            catch (error) {
+                await updateRef(state.gitCommonDir, ref, checkpoint.commit, zeroOid(checkpoint.commit.length)).catch(() => undefined);
+                throw error;
+            }
+            return { workspaceId: id, checkpointId: cpId, deleted: true };
+        });
+    }
+    async deleteWorkspace(workspaceId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        await this.runMutation(id, async () => {
+            const state = this.tryReadState(id);
+            if (!state)
+                return;
+            for (const checkpoint of state.checkpoints) {
+                await deleteRef(state.gitCommonDir, checkpointRef(id, checkpoint.id), checkpoint.commit);
+            }
+            rmSync(this.statePath(id), { force: true });
+            try {
+                rmdirSync(this.workspaceStateDir(id));
+            }
+            catch (error) {
+                if (!isErrno(error, "ENOENT") && !isErrno(error, "ENOTEMPTY") && !isErrno(error, "EEXIST")) {
+                    throw error;
+                }
+            }
+        });
+    }
+    async runMutation(workspaceId, operation) {
+        const previous = this.mutationChains.get(workspaceId) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(operation);
+        this.mutationChains.set(workspaceId, current);
+        try {
+            return await current;
+        }
+        finally {
+            if (this.mutationChains.get(workspaceId) === current)
+                this.mutationChains.delete(workspaceId);
+        }
+    }
+    requireState(workspaceId) {
+        const state = this.tryReadState(workspaceId);
+        if (!state)
+            throw new Error(`Workspace ${workspaceId} has no checkpoints.`);
+        return state;
+    }
+    tryReadState(workspaceId) {
+        let raw;
+        try {
+            raw = readFileSync(this.statePath(workspaceId));
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT"))
+                return undefined;
+            throw error;
+        }
+        if (raw.byteLength > MAX_CHECKPOINT_STATE_BYTES) {
+            throw new Error(`Workspace checkpoint state exceeds ${MAX_CHECKPOINT_STATE_BYTES} bytes.`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.toString("utf8"));
+        }
+        catch (error) {
+            throw new Error(`Workspace checkpoint state is not valid JSON: ${errorMessage(error)}`);
+        }
+        const validated = checkpointStateSchema.safeParse(parsed);
+        if (!validated.success) {
+            const details = validated.error.issues
+                .map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "state"}: ${issue.message}`)
+                .join("; ");
+            throw new Error(`Workspace checkpoint state has an unsupported or invalid format: ${details}`);
+        }
+        return cloneState(validated.data);
+    }
+    writeState(workspaceId, state) {
+        const validated = checkpointStateSchema.parse(state);
+        const serialized = `${JSON.stringify(validated, null, 2)}\n`;
+        if (Buffer.byteLength(serialized, "utf8") > MAX_CHECKPOINT_STATE_BYTES) {
+            throw new Error(`Workspace checkpoint state exceeds ${MAX_CHECKPOINT_STATE_BYTES} bytes.`);
+        }
+        const workspaceDir = this.workspaceStateDir(workspaceId);
+        mkdirSync(workspaceDir, { recursive: true, mode: 0o700 });
+        const statePath = this.statePath(workspaceId);
+        const tempPath = `${statePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+        try {
+            writeFileSync(tempPath, serialized, { mode: 0o600 });
+            renameSync(tempPath, statePath);
+        }
+        finally {
+            rmSync(tempPath, { force: true });
+        }
+    }
+    workspaceStateDir(workspaceId) {
+        return join(this.stateDir, "workspaces", workspaceId);
+    }
+    statePath(workspaceId) {
+        return join(this.workspaceStateDir(workspaceId), "checkpoints.json");
+    }
+}
+async function resolveRepository(workspaceRoot) {
+    const eligibility = await getGitEligibility(workspaceRoot);
+    if (!eligibility.ok || !eligibility.gitRoot) {
+        throw new Error(eligibility.message ?? "workspace.checkpoint requires a Git workspace with a HEAD commit.");
+    }
+    const commonDirRaw = (await git(eligibility.gitRoot, [
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-common-dir",
+    ])).stdout.trim();
+    const commonDir = await canonicalExistingPath(commonDirRaw);
+    return { gitRoot: eligibility.gitRoot, gitCommonDir: commonDir };
+}
+async function createWorkingTreeSnapshot(gitRoot) {
+    const snapshot = await snapshotWorkingTree(gitRoot);
+    const commit = (await git(gitRoot, [
+        "commit-tree",
+        snapshot.tree,
+        "-p",
+        snapshot.baseHead,
+        "-m",
+        "ForgeRelay persistent workspace checkpoint",
+    ], { env: checkpointIdentityEnv() })).stdout.trim();
+    const numstat = (await git(gitRoot, ["diff", "--numstat", "-z", snapshot.baseHead, commit], {
+        maxBuffer: 50 * 1024 * 1024,
+    })).stdout;
+    return { commit, baseHead: snapshot.baseHead, summary: summarizeNumstat(numstat) };
+}
+async function snapshotWorkingTree(gitRoot) {
+    const tempDir = await mkdtemp(join(tmpdir(), "forgerelay-checkpoint-index-"));
+    const indexPath = join(tempDir, "index");
+    const env = checkpointEnv(indexPath);
+    try {
+        await git(gitRoot, ["read-tree", "HEAD"], { env });
+        await git(gitRoot, ["add", "-A", "--", "."], { env });
+        const tree = (await git(gitRoot, ["write-tree"], { env })).stdout.trim();
+        const baseHead = (await git(gitRoot, ["rev-parse", "--verify", "HEAD^{commit}"])).stdout.trim();
+        return { tree, baseHead };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+async function checkpointTree(gitRoot, checkpointCommit) {
+    return (await git(gitRoot, ["rev-parse", "--verify", `${checkpointCommit}^{tree}`])).stdout.trim();
+}
+async function applyTreeRestore(gitRoot, currentTree, checkpointTreeId, verifyImmediatelyBeforeApply) {
+    const tempDir = await mkdtemp(join(tmpdir(), "forgerelay-checkpoint-restore-"));
+    const patchPath = join(tempDir, "restore.patch");
+    try {
+        const patch = (await git(gitRoot, [
+            "diff",
+            "--binary",
+            "--full-index",
+            "--no-renames",
+            "--no-ext-diff",
+            "--no-textconv",
+            currentTree,
+            checkpointTreeId,
+            "--",
+            ".",
+        ], { maxBuffer: 100 * 1024 * 1024 })).stdout;
+        await writeFile(patchPath, patch, { encoding: "utf8", mode: 0o600 });
+        await git(gitRoot, ["apply", "--check", "--binary", "--whitespace=nowarn", patchPath]);
+        await verifyImmediatelyBeforeApply();
+        await git(gitRoot, ["apply", "--binary", "--whitespace=nowarn", patchPath]);
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+function summarizeNumstat(output) {
+    const fields = output.split("\0").filter((field) => field.length > 0);
+    let files = 0;
+    let additions = 0;
+    let removals = 0;
+    for (let index = 0; index < fields.length;) {
+        const header = fields[index++] ?? "";
+        const parts = header.split("\t");
+        additions += parseStatNumber(parts[0]);
+        removals += parseStatNumber(parts[1]);
+        files += 1;
+        if (parts.length < 3)
+            index += 2;
+    }
+    return { files, additions, removals };
+}
+function parseStatNumber(value) {
+    if (!value || value === "-")
+        return 0;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function checkpointEnv(indexPath) {
+    return {
+        ...checkpointIdentityEnv(),
+        GIT_INDEX_FILE: indexPath,
+    };
+}
+function checkpointIdentityEnv() {
+    return {
+        GIT_AUTHOR_NAME: "ForgeRelay",
+        GIT_AUTHOR_EMAIL: "forgerelay@users.noreply.local",
+        GIT_COMMITTER_NAME: "ForgeRelay",
+        GIT_COMMITTER_EMAIL: "forgerelay@users.noreply.local",
+    };
+}
+async function updateRef(commonDir, ref, commit, oldValue) {
+    await git(commonDir, ["--git-dir", commonDir, "update-ref", ref, commit, oldValue]);
+}
+async function deleteRef(commonDir, ref, expectedCommit) {
+    await assertCheckpointRefCommit(commonDir, ref, expectedCommit);
+    await git(commonDir, ["--git-dir", commonDir, "update-ref", "-d", ref, expectedCommit]);
+}
+async function assertCheckpointRef(commonDir, workspaceId, checkpoint) {
+    await assertCheckpointRefCommit(commonDir, checkpointRef(workspaceId, checkpoint.id), checkpoint.commit);
+}
+async function assertCheckpointRefCommit(commonDir, ref, expectedCommit) {
+    let actual;
+    try {
+        actual = (await git(commonDir, ["--git-dir", commonDir, "rev-parse", "--verify", `${ref}^{commit}`])).stdout.trim();
+    }
+    catch {
+        throw new Error(`Checkpoint Git ref ${ref} is missing; refusing to mutate inconsistent checkpoint state.`);
+    }
+    if (actual !== expectedCommit) {
+        throw new Error(`Checkpoint Git ref ${ref} no longer matches its immutable checkpoint commit.`);
+    }
+}
+function checkpointRef(workspaceId, checkpointId) {
+    return `${CHECKPOINT_REF_PREFIX}/${safeWorkspaceRefSegment(workspaceId)}/${checkpointId}`;
+}
+async function assertSameRepository(stored, current, workspaceId) {
+    const [storedCanonical, currentCanonical] = await Promise.all([
+        canonicalExistingPath(stored),
+        canonicalExistingPath(current),
+    ]);
+    if (storedCanonical !== currentCanonical) {
+        throw new Error(`Workspace checkpoint repository mismatch for ${workspaceId}.`);
+    }
+}
+async function canonicalExistingPath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function normalizeWorkspaceId(workspaceId) {
+    const value = workspaceId.trim();
+    if (!/^[a-z][a-z0-9_-]{1,127}$/.test(value)) {
+        throw new Error("Workspace ID is not valid for checkpoint state.");
+    }
+    return value;
+}
+function normalizeCheckpointId(checkpointId) {
+    const value = checkpointId.trim();
+    if (!/^cp_[a-f0-9]{10}$/.test(value))
+        throw new Error(`Invalid checkpoint id ${checkpointId}.`);
+    return value;
+}
+function normalizeSnapshotId(snapshotId) {
+    const value = snapshotId.trim();
+    if (!/^[a-f0-9]{40,64}$/.test(value)) {
+        throw new Error("Workspace checkpoint snapshot identity must be a Git object id.");
+    }
+    return value;
+}
+function assertExpectedCurrentSnapshot(expected, actual) {
+    if (actual !== expected) {
+        throw new Error(`Workspace checkpoint restore refused because the current working snapshot changed: expected ${expected}, found ${actual}. Run restore.preflight again before retrying.`);
+    }
+}
+function normalizeCheckpointName(name) {
+    const value = name.trim();
+    if (!value)
+        throw new Error("Checkpoint name must not be empty.");
+    if (value.length > MAX_CHECKPOINT_NAME_LENGTH) {
+        throw new Error(`Checkpoint name must be at most ${MAX_CHECKPOINT_NAME_LENGTH} characters.`);
+    }
+    return value;
+}
+function normalizeOffset(offset) {
+    if (offset === undefined)
+        return 0;
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new Error("Checkpoint list offset must be a non-negative integer.");
+    return offset;
+}
+function normalizeLimit(limit) {
+    if (limit === undefined)
+        return 50;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+        throw new Error("Checkpoint list limit must be an integer between 1 and 100.");
+    }
+    return limit;
+}
+function requireCheckpoint(state, checkpointId) {
+    const checkpoint = state.checkpoints.find((candidate) => candidate.id === checkpointId);
+    if (!checkpoint)
+        throw new Error(`Unknown Workspace checkpoint ${checkpointId}.`);
+    return checkpoint;
+}
+function cloneCheckpoint(checkpoint) {
+    return { ...checkpoint, summary: { ...checkpoint.summary } };
+}
+function cloneState(state) {
+    return {
+        ...state,
+        checkpoints: state.checkpoints.map(cloneCheckpoint),
+    };
+}
+function zeroOid(length) {
+    return "0".repeat(length);
+}
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -52,7 +52,7 @@
     "release:push-ready": "node scripts/release/push-ready.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/workspaces/relay/tests/recovery.test.ts && tsx src/runtime/config/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/mcp/server/workspace/workspace-recovery.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/cli.test.ts",
+    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/workspaces/relay/tests/recovery.test.ts && tsx src/workspaces/relay/tests/checkpoint.test.ts && tsx src/runtime/config/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/mcp/server/workspace/workspace-recovery.test.ts && tsx src/mcp/server/workspace/workspace-checkpoint.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/ci/architecture.mjs

@@ -9,6 +9,13 @@ const MAX_DIRECT_FILES = 8;
 const MAX_DIRECT_DIRS = 8;
 const LINE_LIMIT_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".mjs", ".cjs", ".css"]);
 
+// Append-only versioned archives grow by design and must keep their canonical
+// flat paths for release tooling and stable links. They remain subject to all
+// other architecture checks, including code line limits where applicable.
+const DIRECT_FILE_LIMIT_EXEMPT_DIRS = new Set([
+  "docs/releases",
+]);
+
 // Repository-root protocol files are intentionally discoverable by Git, npm,
 // Node, Vite, contributors, and agents. Keep that conventional surface explicit
 // instead of hiding required/default-discovery files merely to satisfy a count.
@@ -67,7 +74,7 @@ const directories = new Set([...directFiles.keys(), ...directDirs.keys()]);
 for (const directory of [...directories].sort()) {
   const files = directFiles.get(directory) ?? 0;
   const dirs = directDirs.get(directory)?.size ?? 0;
-  if (directory !== "." && files > MAX_DIRECT_FILES) {
+  if (directory !== "." && !DIRECT_FILE_LIMIT_EXEMPT_DIRS.has(directory) && files > MAX_DIRECT_FILES) {
     violations.push(`${directory}: ${files} direct files > ${MAX_DIRECT_FILES}`);
   }
   if (dirs > MAX_DIRECT_DIRS) {
@@ -83,7 +90,7 @@ if (violations.length > 0) {
 
 console.log(
   `Architecture check passed: ${tracked.length} tracked files; ` +
-  `code <= ${MAX_LINES} lines; non-root directories <= ${MAX_DIRECT_FILES} files / ${MAX_DIRECT_DIRS} directories.`,
+  `code <= ${MAX_LINES} lines; bounded non-root directories <= ${MAX_DIRECT_FILES} files / ${MAX_DIRECT_DIRS} directories.`,
 );
 
 function gitTrackedFiles() {

package/scripts/release/release-gate.test.mjs

@@ -60,6 +60,12 @@ test("cross-platform cloud CI delegates to one shell-free verification entrypoin
   }
 });
 
+test("architecture gate treats the append-only release-note archive as an explicit flat-path exception", async () => {
+  const architecture = await readFile(resolve(repoRoot, "scripts/ci/architecture.mjs"), "utf8");
+  assert.match(architecture, /DIRECT_FILE_LIMIT_EXEMPT_DIRS/);
+  assert.match(architecture, /"docs\/releases"/);
+});
+
 test("release runtime and local parity share the checked-in Node contract", async () => {
   const nodeVersion = (await readFile(resolve(repoRoot, ".nvmrc"), "utf8")).trim();
   assert.equal(nodeVersion, "22.19.0");