obsidian-lean-coder 0.0.0-stage → 0.1.1

package/dist/git/checkpoint.js

@@ -0,0 +1,123 @@
+/**
+ * Safe Git checkpoint commits (OLC-051, enforces the OLC-050 decision).
+ *
+ * Flow: validate identity → normalize owned paths → refuse when an owned
+ * path is already staged → byte-compare every owned file against the
+ * caller-supplied write-time snapshot (any difference = someone else
+ * touched it → abort, zero git mutation) → `git add -- <owned paths>` →
+ * re-verify staged bytes against the snapshots (race guard; reset ours on
+ * mismatch) → `git commit -- <owned paths>` (pathspec, so foreign staged
+ * changes on other paths survive untouched) → append the checkpoint record
+ * (with commit SHA) to `tasks/<taskId>/checkpoint.md` in the vault.
+ *
+ * Banned from this flow, always: `git add .` / `git add -A`, plain
+ * `git commit` without a pathspec, and `git add -p`.
+ *
+ * MVP limits: owned paths must currently exist as files (file deletions by
+ * OLC are not checkpointable yet); snapshots are UTF-8 strings.
+ */
+import { readFileSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { validateIdentity } from "../core/project-identity.js";
+import { assertContextCurrent } from "../validation/index.js";
+import { parseFrontmatter, readVaultDoc, renderTemplate, resolveVaultDoc, writeVaultDoc, } from "../vault/index.js";
+import { git, gitRaw, inspectTree } from "./inspection.js";
+export class CheckpointError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CheckpointError";
+        this.code = code;
+    }
+}
+function normalizeOwned(repoRoot, ownedPaths) {
+    return ownedPaths.map((p) => {
+        const abs = resolve(repoRoot, p);
+        const rel = relative(repoRoot, abs);
+        if (rel === "" || rel === "." || rel.startsWith(`..${sep}`) || rel === "..") {
+            throw new CheckpointError("PATH_OUTSIDE_REPO", `Refused checkpoint path ${JSON.stringify(p)}: it is not inside the repository ${repoRoot}. ` +
+                "Checkpoint only stages repo-relative owned paths.");
+        }
+        return rel.split(sep).join("/");
+    });
+}
+/**
+ * Append a checkpoint-template entry to `tasks/<taskId>/checkpoint.md`.
+ * First call writes the full template; later calls append the body after `---`.
+ * Returns the vault-absolute record path. Exported for reuse by `restore.ts`.
+ */
+export function appendCheckpointRecord(vaultRoot, projectId, taskId, vars) {
+    const entry = renderTemplate("checkpoint", vars);
+    const recordPath = resolveVaultDoc(vaultRoot, projectId, "tasks", taskId, "checkpoint.md");
+    let record;
+    try {
+        const existing = readVaultDoc(recordPath);
+        record = `${existing.replace(/\s+$/, "")}\n\n---\n\n${parseFrontmatter(entry).body}`;
+    }
+    catch {
+        record = entry;
+    }
+    writeVaultDoc(recordPath, record, { overwrite: true });
+    return recordPath;
+}
+export function createCheckpoint(input) {
+    const identity = input.session
+        ? assertContextCurrent({ projectRoot: input.projectRoot, config: input.config, session: input.session })
+        : validateIdentity(input.projectRoot, input.config);
+    const { repoRoot, branch, vaultRoot, projectId } = identity;
+    const owned = normalizeOwned(repoRoot, input.ownedPaths);
+    const before = inspectTree(repoRoot);
+    const prestaged = before.staged.filter((p) => owned.includes(p));
+    if (prestaged.length > 0) {
+        throw new CheckpointError("OWNED_PATH_PRESTAGED", `Refusing checkpoint: owned path(s) already staged by someone else: ${prestaged.join(", ")}. ` +
+            "Unstage them or confirm who staged what before retrying — OLC stages only what it verified itself.");
+    }
+    for (const rel of owned) {
+        const abs = resolve(repoRoot, rel);
+        const expected = input.snapshots[rel];
+        let actual;
+        try {
+            actual = readFileSync(abs, "utf8");
+        }
+        catch {
+            throw new CheckpointError("MISSING_OWNED_FILE", `Refusing checkpoint: owned file ${rel} cannot be read (deleted or moved since OLC wrote it?). ` +
+                "Confirm the current tree state before retrying.");
+        }
+        if (expected === undefined || actual !== expected) {
+            throw new CheckpointError("FOREIGN_EDIT", `Refusing checkpoint: owned file ${rel} no longer matches what OLC wrote ` +
+                "(edited by someone/something else, or no snapshot was recorded). " +
+                "Ask the user how to proceed — OLC never commits mixed ownership.");
+        }
+    }
+    const pending = git(repoRoot, ["status", "--porcelain=v1", "-uall", "--", ...owned]);
+    if (pending === "") {
+        return { status: "clean", branch, head: before.head };
+    }
+    git(repoRoot, ["add", "--", ...owned]);
+    const cached = git(repoRoot, ["diff", "--cached", "--name-only", "--", ...owned]);
+    const cachedSet = new Set(cached === "" ? [] : cached.split("\n"));
+    for (const rel of owned) {
+        if (!cachedSet.has(rel))
+            continue;
+        const stagedBytes = gitRaw(repoRoot, ["show", `:${rel}`]).toString("utf8");
+        if (stagedBytes !== input.snapshots[rel]) {
+            git(repoRoot, ["reset", "-q", "--", ...owned]);
+            throw new CheckpointError("FOREIGN_EDIT", `Refusing checkpoint: staged content of ${rel} changed between verification and staging (race detected). ` +
+                "Our staged copy was reset; worktree untouched. Ask the user how to proceed.");
+        }
+    }
+    const committedPaths = [...cachedSet].filter((p) => owned.includes(p)).sort();
+    const date = input.date ?? new Date().toISOString();
+    const message = `olc checkpoint: ${input.taskId}\n\n${input.summary}`;
+    git(repoRoot, ["commit", "-m", message, "--", ...owned]);
+    const sha = git(repoRoot, ["rev-parse", "HEAD"]);
+    const recordPath = appendCheckpointRecord(vaultRoot, projectId, input.taskId, {
+        task_id: input.taskId,
+        project_id: projectId,
+        commit_sha: sha,
+        date,
+        summary: input.summary,
+        verification: input.verification ?? "(no verification recorded)",
+    });
+    return { status: "committed", branch, sha, committedPaths, recordPath };
+}

package/dist/git/inspection.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Git tree inspection for OLC checkpoints (OLC-051).
+ *
+ * Read-only helpers: parse `git status --porcelain` without touching the
+ * index or worktree. The mutating checkpoint flow lives in `checkpoint.ts`
+ * and must follow the OLC-050 decision (explicit paths only, abort on
+ * ambiguity — never `git add .`, plain `git commit`, or `git add -p`).
+ */
+export declare class GitError extends Error {
+    readonly code: "GIT_FAILED";
+    constructor(message: string);
+}
+/** Run git and return stdout (trailing whitespace only trimmed). */
+export declare function git(repoRoot: string, args: string[]): string;
+/** Run git and return raw stdout bytes (for byte-exact content comparison). */
+export declare function gitRaw(repoRoot: string, args: string[]): Buffer;
+export interface PorcelainSets {
+    /** Paths with staged (index) changes. */
+    staged: string[];
+    /** Paths with unstaged (worktree) changes. */
+    unstaged: string[];
+    /** Untracked paths. */
+    untracked: string[];
+}
+/**
+ * Parse `git status --porcelain=v1` output (pure, no I/O).
+ * Rename entries (`R  old -> new`) resolve to the new path.
+ */
+export declare function parsePorcelain(output: string): PorcelainSets;
+export interface TreeState extends PorcelainSets {
+    branch: string;
+    head: string;
+}
+/** Read-only snapshot of branch, HEAD, and porcelain status. */
+export declare function inspectTree(repoRoot: string): TreeState;

package/dist/git/inspection.js

@@ -0,0 +1,78 @@
+/**
+ * Git tree inspection for OLC checkpoints (OLC-051).
+ *
+ * Read-only helpers: parse `git status --porcelain` without touching the
+ * index or worktree. The mutating checkpoint flow lives in `checkpoint.ts`
+ * and must follow the OLC-050 decision (explicit paths only, abort on
+ * ambiguity — never `git add .`, plain `git commit`, or `git add -p`).
+ */
+import { execFileSync } from "node:child_process";
+import { resolveBranch } from "../core/project-identity.js";
+export class GitError extends Error {
+    code;
+    constructor(message) {
+        super(message);
+        this.name = "GitError";
+        this.code = "GIT_FAILED";
+    }
+}
+/** Run git and return stdout (trailing whitespace only trimmed). */
+export function git(repoRoot, args) {
+    try {
+        return execFileSync("git", args, {
+            cwd: repoRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).replace(/\s+$/, "");
+    }
+    catch (error) {
+        const detail = error.stderr ?? error.message;
+        throw new GitError(`git ${args.join(" ")} failed in ${repoRoot}: ${String(detail).trim()}. Is git installed and the repository intact?`);
+    }
+}
+/** Run git and return raw stdout bytes (for byte-exact content comparison). */
+export function gitRaw(repoRoot, args) {
+    try {
+        return execFileSync("git", args, { cwd: repoRoot, stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch (error) {
+        const detail = error.stderr ?? error.message;
+        throw new GitError(`git ${args.join(" ")} failed in ${repoRoot}: ${String(detail).trim()}. Is git installed and the repository intact?`);
+    }
+}
+/**
+ * Parse `git status --porcelain=v1` output (pure, no I/O).
+ * Rename entries (`R  old -> new`) resolve to the new path.
+ */
+export function parsePorcelain(output) {
+    const staged = [];
+    const unstaged = [];
+    const untracked = [];
+    for (const rawLine of output.split("\n")) {
+        const line = rawLine.replace(/\s+$/, "");
+        if (line === "")
+            continue;
+        const x = line[0];
+        const y = line[1];
+        let path = line.slice(3);
+        const arrow = path.indexOf(" -> ");
+        if (arrow !== -1)
+            path = path.slice(arrow + 4);
+        if (x === "?" && y === "?") {
+            untracked.push(path);
+            continue;
+        }
+        if (x !== " " && x !== "?" && x !== "!")
+            staged.push(path);
+        if (y !== " " && y !== "?" && y !== "!")
+            unstaged.push(path);
+    }
+    return { staged, unstaged, untracked };
+}
+/** Read-only snapshot of branch, HEAD, and porcelain status. */
+export function inspectTree(repoRoot) {
+    const branch = resolveBranch(repoRoot);
+    const head = git(repoRoot, ["rev-parse", "HEAD"]);
+    const { staged, unstaged, untracked } = parsePorcelain(git(repoRoot, ["status", "--porcelain=v1", "-uall"]));
+    return { branch, head, staged, unstaged, untracked };
+}

package/dist/git/policy.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Pre-switch and task-final checkpoint policy (OLC-053).
+ *
+ * Thin policy over OLC-051 `createCheckpoint`:
+ * - `milestone` / `explicit` / `pre-switch`: delegate directly. Unchanged
+ *   owned files return `clean` (no commit, no record), so repeated triggers
+ *   never stack empty commits.
+ * - `task-final`: the final checkpoint of a verified task. Created only when
+ *   safe: verification fully passed AND the task registry already shows
+ *   `review` (i.e. OLC-041 `completeTaskWithVerification` ran). Anything
+ *   else returns `not-ready` / `verify-failed` with zero git mutation.
+ *
+ * A commit is never treated as task completion: every result carries
+ * `needsUserConfirmation`, and the registry status is left untouched
+ * (closing the task stays a user-confirmed OLC-033 transition).
+ *
+ * Checkpoint safety aborts (`CheckpointError`: foreign edit, pre-staged
+ * owned paths, paths outside the repo) propagate to the caller unchanged.
+ */
+import type { ResolvedConfig } from "../config/index.js";
+import { type VerifyOutcome } from "../verify/index.js";
+import { type CheckpointResult } from "./checkpoint.js";
+export type CheckpointTrigger = "milestone" | "explicit" | "pre-switch" | "task-final";
+export interface CheckpointPolicyInput {
+    /** Any directory inside the project (identity resolution starts here). */
+    projectRoot: string;
+    config: ResolvedConfig;
+    taskId: string;
+    trigger: CheckpointTrigger;
+    /** Repo-relative paths OLC owns for this checkpoint (files must exist). */
+    ownedPaths: string[];
+    /** Write-time content snapshot per repo-relative owned path. */
+    snapshots: Record<string, string>;
+    /** Custom summary; defaults to a trigger-specific message. */
+    message?: string;
+    /**
+     * Required for `task-final`: the verification outcome that must have
+     * fully passed. Omitted or failing outcome → no checkpoint is created.
+     */
+    verifyOutcome?: VerifyOutcome;
+    /** Defaults to current time (pass explicit dates in tests). */
+    date?: string;
+}
+export type PolicyResult = (Extract<CheckpointResult, {
+    status: "committed";
+}> & {
+    needsUserConfirmation: boolean;
+}) | (Extract<CheckpointResult, {
+    status: "clean";
+}> & {
+    needsUserConfirmation: boolean;
+}) | {
+    status: "not-ready";
+    reason: string;
+} | {
+    status: "verify-failed";
+    report: string;
+    escalated: string[];
+};
+/**
+ * Apply the checkpoint policy for one trigger. Returns the checkpoint
+ * outcome, or a no-mutation `not-ready` / `verify-failed` refusal.
+ * Throws `CheckpointError` / `IdentityError` exactly as `createCheckpoint`.
+ */
+export declare function maybeCheckpointPolicy(input: CheckpointPolicyInput): PolicyResult;

package/dist/git/policy.js

@@ -0,0 +1,88 @@
+/**
+ * Pre-switch and task-final checkpoint policy (OLC-053).
+ *
+ * Thin policy over OLC-051 `createCheckpoint`:
+ * - `milestone` / `explicit` / `pre-switch`: delegate directly. Unchanged
+ *   owned files return `clean` (no commit, no record), so repeated triggers
+ *   never stack empty commits.
+ * - `task-final`: the final checkpoint of a verified task. Created only when
+ *   safe: verification fully passed AND the task registry already shows
+ *   `review` (i.e. OLC-041 `completeTaskWithVerification` ran). Anything
+ *   else returns `not-ready` / `verify-failed` with zero git mutation.
+ *
+ * A commit is never treated as task completion: every result carries
+ * `needsUserConfirmation`, and the registry status is left untouched
+ * (closing the task stays a user-confirmed OLC-033 transition).
+ *
+ * Checkpoint safety aborts (`CheckpointError`: foreign edit, pre-staged
+ * owned paths, paths outside the repo) propagate to the caller unchanged.
+ */
+import { getTask } from "../tasks/index.js";
+import { formatVerifyReport } from "../verify/index.js";
+import { createCheckpoint, } from "./checkpoint.js";
+const DEFAULT_SUMMARY = {
+    milestone: "milestone checkpoint",
+    explicit: "explicit checkpoint requested",
+    "pre-switch": "checkpoint before task switch",
+    "task-final": "final checkpoint of verified task",
+};
+function oneLineVerifySummary(outcome) {
+    const total = outcome.results.length;
+    return `verification: all ${total} check(s) passed`;
+}
+/**
+ * Apply the checkpoint policy for one trigger. Returns the checkpoint
+ * outcome, or a no-mutation `not-ready` / `verify-failed` refusal.
+ * Throws `CheckpointError` / `IdentityError` exactly as `createCheckpoint`.
+ */
+export function maybeCheckpointPolicy(input) {
+    const { projectRoot, config, taskId, trigger, ownedPaths, snapshots, message, verifyOutcome, date, } = input;
+    const summary = message ?? DEFAULT_SUMMARY[trigger];
+    if (trigger === "task-final") {
+        if (!verifyOutcome) {
+            return {
+                status: "not-ready",
+                reason: "task-final checkpoint needs a verification outcome: pass verifyOutcome from verifyChecks " +
+                    "after the final checks pass. No checkpoint created.",
+            };
+        }
+        if (!verifyOutcome.ok) {
+            return {
+                status: "verify-failed",
+                report: formatVerifyReport(verifyOutcome),
+                escalated: verifyOutcome.escalated,
+            };
+        }
+        const task = getTask(config.vaultPath, config.projectId, taskId);
+        if (!task || task.status !== "review") {
+            return {
+                status: "not-ready",
+                reason: `task-final checkpoint needs task ${taskId} in "review" status ` +
+                    `(found: ${task ? `"${task.status}"` : "unregistered"}). ` +
+                    "Run completeTaskWithVerification first; the task still needs user confirmation to close. " +
+                    "No checkpoint created.",
+            };
+        }
+        const result = createCheckpoint({
+            projectRoot,
+            config,
+            taskId,
+            ownedPaths,
+            snapshots,
+            summary,
+            verification: oneLineVerifySummary(verifyOutcome),
+            date,
+        });
+        return { ...result, needsUserConfirmation: true };
+    }
+    const result = createCheckpoint({
+        projectRoot,
+        config,
+        taskId,
+        ownedPaths,
+        snapshots,
+        summary,
+        date,
+    });
+    return { ...result, needsUserConfirmation: false };
+}

package/dist/git/restore.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Safe restore-to-checkpoint (OLC-052).
+ *
+ * Restoring NEVER moves the branch backward or deletes history: the selected
+ * checkpoint's file contents are applied as a NEW commit on top of HEAD, with
+ * a traceable message. Later commits stay reachable by construction.
+ *
+ * Flow: validate identity → resolve + verify the checkpoint SHA (must be a
+ * commit AND an ancestor of HEAD) → read each intended path's bytes at that
+ * commit (a path absent there aborts — MVP never deletes/creates files on
+ * restore) → inspect the current tree and abort on ANY risk to an intended
+ * path (staged, unstaged, or untracked-same-name content would be lost) →
+ * write checkpoint bytes → `git add -- <paths>` → re-verify staged bytes
+ * (race guard; reset ours on mismatch) → `git commit -m <msg> -- <paths>`
+ * (pathspec, so foreign staged changes elsewhere survive) → append the
+ * restore record (with BOTH shas) to `tasks/<taskId>/checkpoint.md`.
+ *
+ * There is no force flag: on any risk the function aborts listing the exact
+ * paths, and the caller (build agent) surfaces that list to the user as the
+ * confirmation step. Banned here as in checkpoint.ts: `git add .` / `-A`,
+ * plain `git commit` without a pathspec, `git add -p`, `git reset --hard`,
+ * `git checkout <sha> -- .`, and any form of `git reset` to an older commit.
+ */
+import type { ResolvedConfig } from "../config/index.js";
+import { type SessionContext } from "../validation/index.js";
+export type RestoreErrorCode = "UNKNOWN_CHECKPOINT" | "NOT_ANCESTOR" | "PATH_OUTSIDE_REPO" | "PATH_NOT_IN_CHECKPOINT" | "RESTORE_PATH_PRESTAGED" | "UNSTAGED_RISK" | "UNTRACKED_RISK" | "STAGE_MISMATCH";
+export declare class RestoreError extends Error {
+    readonly code: RestoreErrorCode;
+    constructor(code: RestoreErrorCode, message: string);
+}
+export interface RestoreInput {
+    /** Any directory inside the project (identity resolution starts here). */
+    projectRoot: string;
+    config: ResolvedConfig;
+    taskId: string;
+    /** Full or abbreviated SHA of the checkpoint commit to restore. */
+    checkpointSha: string;
+    /** Repo-relative paths to restore (must all exist at the checkpoint). */
+    restorePaths: string[];
+    /** Why this restore happens (commit message + vault record). */
+    reason: string;
+    /** Defaults to current time (pass explicit dates in tests). */
+    date?: string;
+    /**
+     * Session context from `startSession`. When present the restore is also
+     * revalidated against it (vault unmounted / re-registered / branch
+     * switched between operations blocks with zero writes).
+     */
+    session?: SessionContext;
+}
+export interface RestoreResult {
+    /** "already-matches" when the tree already holds the checkpoint contents (no commit, no record). */
+    status: "restored" | "already-matches";
+    branch: string;
+    /** The verified checkpoint commit that was restored from. */
+    restoredFrom: string;
+    /** The NEW commit applying the restored contents (absent when already-matches). */
+    sha?: string;
+    restoredPaths: string[];
+    /** Vault record path (absent when already-matches — nothing to cross-reference). */
+    recordPath?: string;
+}
+export declare function restoreCheckpoint(input: RestoreInput): RestoreResult;

package/dist/git/restore.js

@@ -0,0 +1,143 @@
+/**
+ * Safe restore-to-checkpoint (OLC-052).
+ *
+ * Restoring NEVER moves the branch backward or deletes history: the selected
+ * checkpoint's file contents are applied as a NEW commit on top of HEAD, with
+ * a traceable message. Later commits stay reachable by construction.
+ *
+ * Flow: validate identity → resolve + verify the checkpoint SHA (must be a
+ * commit AND an ancestor of HEAD) → read each intended path's bytes at that
+ * commit (a path absent there aborts — MVP never deletes/creates files on
+ * restore) → inspect the current tree and abort on ANY risk to an intended
+ * path (staged, unstaged, or untracked-same-name content would be lost) →
+ * write checkpoint bytes → `git add -- <paths>` → re-verify staged bytes
+ * (race guard; reset ours on mismatch) → `git commit -m <msg> -- <paths>`
+ * (pathspec, so foreign staged changes elsewhere survive) → append the
+ * restore record (with BOTH shas) to `tasks/<taskId>/checkpoint.md`.
+ *
+ * There is no force flag: on any risk the function aborts listing the exact
+ * paths, and the caller (build agent) surfaces that list to the user as the
+ * confirmation step. Banned here as in checkpoint.ts: `git add .` / `-A`,
+ * plain `git commit` without a pathspec, `git add -p`, `git reset --hard`,
+ * `git checkout <sha> -- .`, and any form of `git reset` to an older commit.
+ */
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { validateIdentity } from "../core/project-identity.js";
+import { assertContextCurrent } from "../validation/index.js";
+import { appendCheckpointRecord } from "./checkpoint.js";
+import { GitError, git, gitRaw, inspectTree } from "./inspection.js";
+export class RestoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "RestoreError";
+        this.code = code;
+    }
+}
+function normalizeRestorePaths(repoRoot, restorePaths) {
+    return restorePaths.map((p) => {
+        const abs = resolve(repoRoot, p);
+        const rel = relative(repoRoot, abs);
+        if (rel === "" || rel === "." || rel.startsWith(`..${sep}`) || rel === "..") {
+            throw new RestoreError("PATH_OUTSIDE_REPO", `Refused restore path ${JSON.stringify(p)}: it is not inside the repository ${repoRoot}. ` +
+                "Restore only touches repo-relative paths.");
+        }
+        return rel.split(sep).join("/");
+    });
+}
+function isAncestor(repoRoot, sha) {
+    const result = spawnSync("git", ["merge-base", "--is-ancestor", sha, "HEAD"], {
+        cwd: repoRoot,
+        stdio: "ignore",
+    });
+    if (result.status === 0)
+        return true;
+    if (result.status === 1)
+        return false;
+    throw new GitError(`git merge-base --is-ancestor failed in ${repoRoot} (status ${result.status}). Is git installed and the repository intact?`);
+}
+export function restoreCheckpoint(input) {
+    const identity = input.session
+        ? assertContextCurrent({ projectRoot: input.projectRoot, config: input.config, session: input.session })
+        : validateIdentity(input.projectRoot, input.config);
+    const { repoRoot, branch, vaultRoot, projectId } = identity;
+    const paths = normalizeRestorePaths(repoRoot, input.restorePaths);
+    let full;
+    try {
+        full = git(repoRoot, ["rev-parse", "--verify", `${input.checkpointSha}^{commit}`]);
+    }
+    catch {
+        throw new RestoreError("UNKNOWN_CHECKPOINT", `Refusing restore: ${JSON.stringify(input.checkpointSha)} does not resolve to a commit in ${repoRoot}. ` +
+            "Run `git log --oneline` to find the checkpoint SHA from its record first.");
+    }
+    if (!isAncestor(repoRoot, full)) {
+        throw new RestoreError("NOT_ANCESTOR", `Refusing restore: commit ${full} is not an ancestor of HEAD. ` +
+            "OLC only restores checkpoints on the current branch history — later commits must stay reachable. " +
+            "Ask the user how to proceed.");
+    }
+    const wanted = new Map();
+    for (const rel of paths) {
+        try {
+            wanted.set(rel, gitRaw(repoRoot, ["show", `${full}:${rel}`]));
+        }
+        catch {
+            throw new RestoreError("PATH_NOT_IN_CHECKPOINT", `Refusing restore: path ${rel} does not exist at checkpoint ${full.slice(0, 12)}. ` +
+                "MVP restore never deletes or creates files — remove or create the file manually, checkpoint that, and retry.");
+        }
+    }
+    const tree = inspectTree(repoRoot);
+    const prestaged = tree.staged.filter((p) => paths.includes(p));
+    if (prestaged.length > 0) {
+        throw new RestoreError("RESTORE_PATH_PRESTAGED", `Refusing restore: path(s) already staged: ${prestaged.join(", ")}. ` +
+            "Unstaging is itself a destructive choice — confirm who staged what before retrying.");
+    }
+    const atRisk = tree.unstaged.filter((p) => paths.includes(p));
+    if (atRisk.length > 0) {
+        throw new RestoreError("UNSTAGED_RISK", `Refusing restore: uncommitted worktree changes would be lost at: ${atRisk.join(", ")}. ` +
+            "Commit or checkpoint them first, or confirm with the user that they may be discarded.");
+    }
+    const shadowed = tree.untracked.filter((p) => paths.includes(p));
+    if (shadowed.length > 0) {
+        throw new RestoreError("UNTRACKED_RISK", `Refusing restore: untracked file(s) would be overwritten at: ${shadowed.join(", ")}. ` +
+            "Move them aside or confirm with the user before retrying.");
+    }
+    for (const [rel, bytes] of wanted) {
+        writeFileSync(resolve(repoRoot, rel), bytes);
+    }
+    git(repoRoot, ["add", "--", ...paths]);
+    const stagedList = git(repoRoot, ["diff", "--cached", "--name-only", "--", ...paths]);
+    if (stagedList === "") {
+        return { status: "already-matches", branch, restoredFrom: full, restoredPaths: [...paths].sort() };
+    }
+    for (const [rel, bytes] of wanted) {
+        const stagedBytes = gitRaw(repoRoot, ["show", `:${rel}`]);
+        if (!stagedBytes.equals(bytes)) {
+            git(repoRoot, ["reset", "-q", "--", ...paths]);
+            throw new RestoreError("STAGE_MISMATCH", `Refusing restore: staged content of ${rel} changed between write and staging (race detected). ` +
+                "Our staged copy was reset; ask the user how to proceed.");
+        }
+    }
+    const short = full.slice(0, 12);
+    const date = input.date ?? new Date().toISOString();
+    const message = `olc restore: ${input.taskId} (${[...paths].sort().join(", ")}) to ${short}\n\n${input.reason}`;
+    git(repoRoot, ["commit", "-m", message, "--", ...paths]);
+    const sha = git(repoRoot, ["rev-parse", "HEAD"]);
+    const recordPath = appendCheckpointRecord(vaultRoot, projectId, input.taskId, {
+        task_id: input.taskId,
+        project_id: projectId,
+        commit_sha: sha,
+        date,
+        summary: `Restore ${[...paths].sort().join(", ")} to checkpoint ${short}: ${input.reason}`,
+        verification: `(restore of ${short}; later history preserved)`,
+    });
+    return {
+        status: "restored",
+        branch,
+        restoredFrom: full,
+        sha,
+        restoredPaths: [...paths].sort(),
+        recordPath,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OLC package entrypoint. Thin on purpose — see docs/PRD.md §8 for planned
+ * module layout (config, core, git, logging, tools, validation).
+ *
+ * The plugin default export is re-exported here (not only from
+ * `./plugin.js`) because OpenCode's npm loader resolves the package root,
+ * i.e. `dist/index.js` — without a `default` export carrying `{ id, setup }`
+ * the loader ignores the package entirely (found by OLC-071 smoke test:
+ * zero load attempts for 0.1.0). `OLC_VERSION` is only consumed inside
+ * `plugin.ts` tool `execute` (deferred to call time), so this re-export
+ * cycle is safe under ESM live bindings.
+ */
+export declare const OLC_VERSION = "0.1.1";
+export { default } from "./plugin.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * OLC package entrypoint. Thin on purpose — see docs/PRD.md §8 for planned
+ * module layout (config, core, git, logging, tools, validation).
+ *
+ * The plugin default export is re-exported here (not only from
+ * `./plugin.js`) because OpenCode's npm loader resolves the package root,
+ * i.e. `dist/index.js` — without a `default` export carrying `{ id, setup }`
+ * the loader ignores the package entirely (found by OLC-071 smoke test:
+ * zero load attempts for 0.1.0). `OLC_VERSION` is only consumed inside
+ * `plugin.ts` tool `execute` (deferred to call time), so this re-export
+ * cycle is safe under ESM live bindings.
+ */
+export const OLC_VERSION = "0.1.1";
+export { default } from "./plugin.js";