@akira-tl/forgerelay 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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

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

@@ -2,16 +2,18 @@
 
 `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.2 surface
+## v0.9.3 surface
 
-Supported operations are deliberately limited to:
+Supported operations are:
 
 - `create` — create a named immutable checkpoint of the current Git-visible working tree.
-- `list` — return bounded checkpoint metadata, newest identity preserved in creation order.
+- `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 **not** part of v0.9.2. Do not emulate restore with checkout/reset or other destructive Git commands unless the user separately and explicitly asks for such Git work outside this Capability.
+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
 
@@ -53,6 +55,35 @@ Use `inspect` only after selecting an id:
 
 `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:

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

@@ -13,6 +13,15 @@ export const workspaceCheckpointInputSchema = z.discriminatedUnion("operation",
         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}$/),

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

@@ -308,7 +308,7 @@ export function createCapabilityRegistry(dependencies) {
         ...(dependencies.workspaceCheckpoint
             ? [{
                     name: "workspace.checkpoint",
-                    description: "Create, list, inspect, or delete immutable Git-backed checkpoints owned by the current persistent Workspace.",
+                    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",

package/dist/server.js

@@ -156,6 +156,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         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) };
                 }

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

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
-import { mkdtemp, realpath, rm } from "node:fs/promises";
+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";
@@ -117,6 +117,73 @@ export class WorkspaceCheckpointStore {
         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);
@@ -247,6 +314,21 @@ async function resolveRepository(workspaceRoot) {
     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);
@@ -255,18 +337,35 @@ async function createWorkingTreeSnapshot(gitRoot) {
         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();
-        const commit = (await git(gitRoot, [
-            "commit-tree",
-            tree,
-            "-p",
-            baseHead,
-            "-m",
-            "ForgeRelay persistent workspace checkpoint",
-        ], { env })).stdout.trim();
-        const numstat = (await git(gitRoot, ["diff", "--numstat", "-z", baseHead, commit], {
-            maxBuffer: 50 * 1024 * 1024,
-        })).stdout;
-        return { commit, baseHead, summary: summarizeNumstat(numstat) };
+        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 });
@@ -296,7 +395,12 @@ function parseStatNumber(value) {
 }
 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",
@@ -358,6 +462,18 @@ function normalizeCheckpointId(checkpointId) {
         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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",

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");