apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/workspace/comparison.js

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+import { WORKSPACE_RECORD_VERSION } from "./state.js";
+/** Upper bound on `changedPaths` carried in one comparison record. */
+export const MAX_CHANGED_PATHS = 200;
+function pathTupleKey(path) {
+    return [
+        path.path,
+        path.kind,
+        path.staged ? "s" : "",
+        path.unstaged ? "u" : "",
+        path.ignored ? "i" : "",
+        path.contentHash ?? "",
+    ].join("\u0000");
+}
+function changedPathsBetween(stored, fresh, warnings) {
+    const storedKeys = new Map();
+    for (const p of stored.paths)
+        storedKeys.set(p.path, pathTupleKey(p));
+    const freshKeys = new Map();
+    for (const p of fresh.paths)
+        freshKeys.set(p.path, pathTupleKey(p));
+    const changed = new Set();
+    for (const [path, key] of storedKeys) {
+        if (freshKeys.get(path) !== key)
+            changed.add(path);
+    }
+    for (const [path, key] of freshKeys) {
+        if (storedKeys.get(path) !== key)
+            changed.add(path);
+    }
+    const sorted = [...changed].sort();
+    if (sorted.length > MAX_CHANGED_PATHS) {
+        warnings.push(`changed path list truncated at ${MAX_CHANGED_PATHS} of ${sorted.length} entries`);
+        return sorted.slice(0, MAX_CHANGED_PATHS);
+    }
+    return sorted;
+}
+/**
+ * WS.5: compare fresh workspace state against a stored observation (spec
+ * 2026-09-01-harness-correctness-and-workspace-state.md § 3). Pure: same
+ * inputs, same outcome. `unavailable` — the workspace could not be observed
+ * now; `inconclusive` — no reliable comparison could be established, so no
+ * drift claim is made in either direction; drift is never silently hidden:
+ * an old patch is never presented as current state.
+ */
+export function compareWorkspaceObservations(stored, fresh, options = {}) {
+    const warnings = [];
+    if (!fresh || fresh.status === "failed" || fresh.status === "unsupported") {
+        return { result: "unavailable", warnings };
+    }
+    if (fresh.status === "incomplete") {
+        warnings.push("fresh observation is incomplete; comparison is not reliable");
+        return { result: "inconclusive", warnings };
+    }
+    if (stored.status === "incomplete") {
+        warnings.push("stored observation is incomplete; comparison is not reliable");
+        return { result: "inconclusive", warnings };
+    }
+    if (stored.status !== "observed") {
+        warnings.push("stored observation has no comparable baseline");
+        return { result: "inconclusive", warnings };
+    }
+    const storedBase = stored.base;
+    const freshBase = fresh.base;
+    if (!storedBase?.worktreeDigest || !freshBase?.worktreeDigest) {
+        warnings.push("worktree digest missing on one side; comparison is not reliable");
+        return { result: "inconclusive", warnings };
+    }
+    const sameIndex = (storedBase.indexDigest ?? "") === (freshBase.indexDigest ?? "");
+    const sameWorktree = storedBase.worktreeDigest === freshBase.worktreeDigest;
+    if (stored.patchArtifactRef) {
+        const probe = options.artifactProbe ?? ((p) => existsSync(p));
+        if (!probe(stored.patchArtifactRef.file)) {
+            warnings.push(`stored workspace patch artifact ${stored.patchArtifactRef.artifactId} is missing on disk`);
+        }
+    }
+    if (sameIndex && sameWorktree) {
+        return { result: "same", warnings };
+    }
+    const changedPaths = changedPathsBetween(stored, fresh, warnings);
+    return { result: "drifted", changedPaths, warnings };
+}
+/** Build the record handed to appendWorkspaceComparison. */
+export function buildWorkspaceComparison(comparedToObservationId, outcome, now = () => new Date().toISOString()) {
+    return {
+        version: WORKSPACE_RECORD_VERSION,
+        comparedAt: now(),
+        comparedToObservationId,
+        result: outcome.result,
+        changedPaths: outcome.changedPaths,
+        warnings: outcome.warnings,
+    };
+}
+//# sourceMappingURL=comparison.js.map

package/dist/core/workspace/comparison.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparison.js","sourceRoot":"","sources":["../../../src/core/workspace/comparison.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from \"node:fs\";\nimport type { WorkspaceStateComparison, WorkspaceStateRecord } from \"./state.ts\";\nimport { WORKSPACE_RECORD_VERSION } from \"./state.ts\";\n\n/** Upper bound on `changedPaths` carried in one comparison record. */\nexport const MAX_CHANGED_PATHS = 200;\n\nexport type WorkspaceComparisonOutcome = Pick<WorkspaceStateComparison, \"result\" | \"changedPaths\" | \"warnings\">;\n\nexport interface WorkspaceComparisonOptions {\n\t/** Probe for stored patch artifacts; defaults to existence on disk. */\n\tartifactProbe?: (storePath: string) => boolean;\n}\n\nfunction pathTupleKey(path: {\n\tpath: string;\n\tkind: string;\n\tstaged?: boolean;\n\tunstaged?: boolean;\n\tignored?: boolean;\n\tcontentHash?: string;\n}): string {\n\treturn [\n\t\tpath.path,\n\t\tpath.kind,\n\t\tpath.staged ? \"s\" : \"\",\n\t\tpath.unstaged ? \"u\" : \"\",\n\t\tpath.ignored ? \"i\" : \"\",\n\t\tpath.contentHash ?? \"\",\n\t].join(\"\\u0000\");\n}\n\nfunction changedPathsBetween(stored: WorkspaceStateRecord, fresh: WorkspaceStateRecord, warnings: string[]): string[] {\n\tconst storedKeys = new Map<string, string>();\n\tfor (const p of stored.paths) storedKeys.set(p.path, pathTupleKey(p));\n\tconst freshKeys = new Map<string, string>();\n\tfor (const p of fresh.paths) freshKeys.set(p.path, pathTupleKey(p));\n\n\tconst changed = new Set<string>();\n\tfor (const [path, key] of storedKeys) {\n\t\tif (freshKeys.get(path) !== key) changed.add(path);\n\t}\n\tfor (const [path, key] of freshKeys) {\n\t\tif (storedKeys.get(path) !== key) changed.add(path);\n\t}\n\tconst sorted = [...changed].sort();\n\tif (sorted.length > MAX_CHANGED_PATHS) {\n\t\twarnings.push(`changed path list truncated at ${MAX_CHANGED_PATHS} of ${sorted.length} entries`);\n\t\treturn sorted.slice(0, MAX_CHANGED_PATHS);\n\t}\n\treturn sorted;\n}\n\n/**\n * WS.5: compare fresh workspace state against a stored observation (spec\n * 2026-09-01-harness-correctness-and-workspace-state.md § 3). Pure: same\n * inputs, same outcome. `unavailable` — the workspace could not be observed\n * now; `inconclusive` — no reliable comparison could be established, so no\n * drift claim is made in either direction; drift is never silently hidden:\n * an old patch is never presented as current state.\n */\nexport function compareWorkspaceObservations(\n\tstored: WorkspaceStateRecord,\n\tfresh: WorkspaceStateRecord | undefined,\n\toptions: WorkspaceComparisonOptions = {},\n): WorkspaceComparisonOutcome {\n\tconst warnings: string[] = [];\n\n\tif (!fresh || fresh.status === \"failed\" || fresh.status === \"unsupported\") {\n\t\treturn { result: \"unavailable\", warnings };\n\t}\n\tif (fresh.status === \"incomplete\") {\n\t\twarnings.push(\"fresh observation is incomplete; comparison is not reliable\");\n\t\treturn { result: \"inconclusive\", warnings };\n\t}\n\tif (stored.status === \"incomplete\") {\n\t\twarnings.push(\"stored observation is incomplete; comparison is not reliable\");\n\t\treturn { result: \"inconclusive\", warnings };\n\t}\n\tif (stored.status !== \"observed\") {\n\t\twarnings.push(\"stored observation has no comparable baseline\");\n\t\treturn { result: \"inconclusive\", warnings };\n\t}\n\n\tconst storedBase = stored.base;\n\tconst freshBase = fresh.base;\n\tif (!storedBase?.worktreeDigest || !freshBase?.worktreeDigest) {\n\t\twarnings.push(\"worktree digest missing on one side; comparison is not reliable\");\n\t\treturn { result: \"inconclusive\", warnings };\n\t}\n\n\tconst sameIndex = (storedBase.indexDigest ?? \"\") === (freshBase.indexDigest ?? \"\");\n\tconst sameWorktree = storedBase.worktreeDigest === freshBase.worktreeDigest;\n\n\tif (stored.patchArtifactRef) {\n\t\tconst probe = options.artifactProbe ?? ((p: string) => existsSync(p));\n\t\tif (!probe(stored.patchArtifactRef.file)) {\n\t\t\twarnings.push(`stored workspace patch artifact ${stored.patchArtifactRef.artifactId} is missing on disk`);\n\t\t}\n\t}\n\n\tif (sameIndex && sameWorktree) {\n\t\treturn { result: \"same\", warnings };\n\t}\n\tconst changedPaths = changedPathsBetween(stored, fresh, warnings);\n\treturn { result: \"drifted\", changedPaths, warnings };\n}\n\n/** Shape of a persisted comparison record, minus what the caller supplies. */\nexport type WorkspaceComparisonFields = WorkspaceComparisonOutcome & {\n\tcomparedAt: string;\n\tcomparedToObservationId: string;\n\tversion: typeof WORKSPACE_RECORD_VERSION;\n};\n\n/** Build the record handed to appendWorkspaceComparison. */\nexport function buildWorkspaceComparison(\n\tcomparedToObservationId: string,\n\toutcome: WorkspaceComparisonOutcome,\n\tnow: () => string = () => new Date().toISOString(),\n): WorkspaceStateComparison {\n\treturn {\n\t\tversion: WORKSPACE_RECORD_VERSION,\n\t\tcomparedAt: now(),\n\t\tcomparedToObservationId,\n\t\tresult: outcome.result,\n\t\tchangedPaths: outcome.changedPaths,\n\t\twarnings: outcome.warnings,\n\t};\n}\n"]}

package/dist/core/workspace/git-observer.d.ts

@@ -0,0 +1,48 @@
+import { type WorkspaceStateRecord } from "./state.ts";
+export interface GitObserveOptions {
+    /** Compute per-path content hashes of present files (default true). */
+    hashPaths?: boolean;
+    /** Maximum number of reported paths (default 200). */
+    maxPaths?: number;
+    /** Skip hashing files larger than this many bytes (default 5 MiB). */
+    maxHashBytes?: number;
+    /** Per-command timeout in milliseconds (default 10 000). */
+    timeoutMs?: number;
+    /** Cancels the observation; the record reports `failed`. */
+    signal?: AbortSignal;
+    /**
+     * Repository-relative path prefixes to omit from `paths` (exact match or
+     * directory prefix). Used for harness bookkeeping that lives inside the
+     * workspace — e.g. the session directory — which is not workspace state.
+     */
+    excludePaths?: string[];
+}
+/**
+ * Observe a Git workspace without mutating it. Returns a version-1
+ * `WorkspaceStateRecord`: `unsupported` for non-Git workspaces, `failed`
+ * when git could not run or the observation was cancelled, and `incomplete`
+ * when a limit truncated the capture. `observed` never implies more than
+ * `coverage` states.
+ */
+export interface ToplevelComparison {
+    /** Whether the physically resolved workspace root sits under the toplevel. */
+    inside: boolean;
+    /** Root path relative to the toplevel; strip this prefix from porcelain paths. */
+    prefix: string;
+    /** Physically resolved toplevel; base for absolute-path work like hashing. */
+    toplevelReal: string;
+}
+/**
+ * Decide containment of the workspace root inside git's toplevel after both
+ * sides are physically resolved. Windows spellings diverge from what Node's
+ * realpath returns for the same directory (short 8.3 names, drive-letter
+ * case), so the win32 branch resolves through the native resolver, folds
+ * case for the comparison, and uses win32 path semantics. The platform and
+ * resolver are injectable so tests can exercise those branches anywhere.
+ */
+export declare function compareToplevel(workspaceRoot: string, toplevel: string, options?: {
+    platform?: NodeJS.Platform;
+    realpath?: (path: string) => string;
+}): ToplevelComparison;
+export declare function observeWorkspaceGit(workspaceRoot: string, options?: GitObserveOptions): Promise<WorkspaceStateRecord>;
+//# sourceMappingURL=git-observer.d.ts.map

package/dist/core/workspace/git-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-observer.d.ts","sourceRoot":"","sources":["../../../src/core/workspace/git-observer.ts"],"names":[],"mappings":"AAIA,OAAO,EAIN,KAAK,oBAAoB,EACzB,MAAM,YAAY,CAAC;AAoBpB,MAAM,WAAW,iBAAiB;IACjC,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAmLD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;IAChB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACpC,GACC,kBAAkB,CA2BpB;AAED,wBAAsB,mBAAmB,CACxC,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAyI/B","sourcesContent":["import { type ChildProcess, spawn } from \"node:child_process\";\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { lstatSync, readFileSync, readlinkSync, realpathSync } from \"node:fs\";\nimport { dirname, isAbsolute, win32 as pathWin32, relative, sep } from \"node:path\";\nimport {\n\tWORKSPACE_RECORD_VERSION,\n\ttype WorkspaceStateCoverage,\n\ttype WorkspaceStatePath,\n\ttype WorkspaceStateRecord,\n} from \"./state.ts\";\n\n/**\n * Read-only Git workspace observation (spec 2026-09-01-harness-correctness-\n * and-workspace-state.md § 1).\n *\n * The adapter never mutates repository state: `HEAD`, the current branch, the\n * index, the worktree, the stash, and local config are only read. Optional\n * index locks are disabled (`GIT_OPTIONAL_LOCKS=0`) so even `git status`\n * cannot refresh the on-disk index. It never walks the workspace; all path\n * knowledge comes from git. Symlinks are hashed as link text (what git\n * stores), never followed. Submodule (gitlink) paths carry no worktree hash.\n */\n\nconst DEFAULT_MAX_PATHS = 200;\nconst DEFAULT_MAX_HASH_BYTES = 5 * 1024 * 1024;\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst GIT_CONFIG = [\"-c\", \"core.autocrlf=false\", \"-c\", \"status.renames=true\"];\nconst UNMERGED_XY = new Set([\"DD\", \"AU\", \"UD\", \"UA\", \"DU\", \"AA\", \"UU\"]);\n\nexport interface GitObserveOptions {\n\t/** Compute per-path content hashes of present files (default true). */\n\thashPaths?: boolean;\n\t/** Maximum number of reported paths (default 200). */\n\tmaxPaths?: number;\n\t/** Skip hashing files larger than this many bytes (default 5 MiB). */\n\tmaxHashBytes?: number;\n\t/** Per-command timeout in milliseconds (default 10 000). */\n\ttimeoutMs?: number;\n\t/** Cancels the observation; the record reports `failed`. */\n\tsignal?: AbortSignal;\n\t/**\n\t * Repository-relative path prefixes to omit from `paths` (exact match or\n\t * directory prefix). Used for harness bookkeeping that lives inside the\n\t * workspace — e.g. the session directory — which is not workspace state.\n\t */\n\texcludePaths?: string[];\n}\n\ninterface GitRunResult {\n\tok: boolean;\n\tcode: number | null;\n\tstdout: Buffer;\n\tstderr: string;\n\ttimedOut: boolean;\n\tspawnError: boolean;\n}\n\nfunction runGit(cwd: string, args: string[], timeoutMs: number, signal?: AbortSignal): Promise<GitRunResult> {\n\treturn new Promise((resolve) => {\n\t\tlet stdout = Buffer.alloc(0);\n\t\tlet stderr = \"\";\n\t\tlet timedOut = false;\n\t\tlet settled = false;\n\t\tlet child: ChildProcess;\n\t\tconst finish = (code: number | null, spawnError: boolean) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tclearTimeout(timer);\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tresolve({\n\t\t\t\tok: !spawnError && !timedOut && code === 0,\n\t\t\t\tcode,\n\t\t\t\tstdout,\n\t\t\t\tstderr,\n\t\t\t\ttimedOut,\n\t\t\t\tspawnError,\n\t\t\t});\n\t\t};\n\t\tconst onAbort = () => {\n\t\t\tchild?.kill(\"SIGKILL\");\n\t\t};\n\t\tconst timer = setTimeout(() => {\n\t\t\ttimedOut = true;\n\t\t\tchild?.kill(\"SIGKILL\");\n\t\t}, timeoutMs);\n\t\ttry {\n\t\t\tchild = spawn(\"git\", [...GIT_CONFIG, ...args], {\n\t\t\t\tcwd,\n\t\t\t\tshell: false,\n\t\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\t\t// Observation must leave the on-disk index untouched.\n\t\t\t\tenv: { ...process.env, GIT_OPTIONAL_LOCKS: \"0\" },\n\t\t\t});\n\t\t} catch {\n\t\t\tresolve({ ok: false, code: null, stdout, stderr: \"\", timedOut: false, spawnError: true });\n\t\t\treturn;\n\t\t}\n\t\tif (signal) {\n\t\t\tif (signal.aborted) onAbort();\n\t\t\telse signal.addEventListener(\"abort\", onAbort, { once: true });\n\t\t}\n\t\tchild.stdout?.on(\"data\", (chunk: Buffer) => {\n\t\t\tstdout = Buffer.concat([stdout, chunk]);\n\t\t});\n\t\tchild.stderr?.on(\"data\", (chunk: Buffer) => {\n\t\t\tstderr += chunk.toString(\"utf-8\");\n\t\t});\n\t\tchild.on(\"error\", () => finish(null, true));\n\t\tchild.on(\"close\", (code) => finish(code, false));\n\t});\n}\n\nfunction emptyCoverage(): WorkspaceStateCoverage {\n\treturn {\n\t\ttracked: false,\n\t\tstaged: false,\n\t\tunstaged: false,\n\t\tuntracked: false,\n\t\tignored: false,\n\t\thashes: false,\n\t\tpatch: false,\n\t};\n}\n\nfunction fullCoverage(): WorkspaceStateCoverage {\n\treturn {\n\t\ttracked: true,\n\t\tstaged: true,\n\t\tunstaged: true,\n\t\tuntracked: true,\n\t\tignored: true,\n\t\thashes: true,\n\t\tpatch: false,\n\t};\n}\n\ninterface ParsedStatusPath {\n\tx: string;\n\ty: string;\n\tpath: string;\n\tpreviousPath?: string;\n}\n\nfunction parsePorcelainZ(stdout: Buffer): ParsedStatusPath[] {\n\tconst fields = stdout.toString(\"utf-8\").split(\"\\0\");\n\tconst parsed: ParsedStatusPath[] = [];\n\tlet i = 0;\n\twhile (i < fields.length) {\n\t\tconst record = fields[i++];\n\t\tif (!record || record.length < 4) continue;\n\t\tconst entry: ParsedStatusPath = { x: record[0], y: record[1], path: record.slice(3) };\n\t\tif (entry.x === \"R\" || entry.x === \"C\" || entry.y === \"R\" || entry.y === \"C\") {\n\t\t\tentry.previousPath = fields[i++];\n\t\t}\n\t\tparsed.push(entry);\n\t}\n\treturn parsed;\n}\n\nfunction classify(entry: ParsedStatusPath): {\n\tkind: WorkspaceStatePath[\"kind\"];\n\tstaged: boolean;\n\tunstaged: boolean;\n\tignored: boolean;\n} {\n\tconst { x, y } = entry;\n\tif (x === \"?\" && y === \"?\") {\n\t\treturn { kind: \"untracked\", staged: false, unstaged: false, ignored: false };\n\t}\n\tif (x === \"!\" && y === \"!\") {\n\t\treturn { kind: \"untracked\", staged: false, unstaged: false, ignored: true };\n\t}\n\tif (UNMERGED_XY.has(`${x}${y}`)) {\n\t\treturn {\n\t\t\tkind: x === \"D\" && y === \"D\" ? \"deleted\" : \"modified\",\n\t\t\tstaged: true,\n\t\t\tunstaged: true,\n\t\t\tignored: false,\n\t\t};\n\t}\n\tlet kind: WorkspaceStatePath[\"kind\"] = \"modified\";\n\tif (x === \"A\" || y === \"A\" || x === \"C\" || y === \"C\") kind = \"added\";\n\telse if (x === \"D\" || y === \"D\") kind = \"deleted\";\n\telse if (x === \"R\" || y === \"R\") kind = \"renamed\";\n\treturn {\n\t\tkind,\n\t\tstaged: x !== \" \" && x !== \"?\" && x !== \"!\",\n\t\tunstaged: y !== \" \" && y !== \"?\" && y !== \"!\",\n\t\tignored: false,\n\t};\n}\n\n/** Hash one workspace path: regular files by bytes, symlinks by link text. */\nfunction hashWorkspacePath(\n\ttoplevel: string,\n\tpath: string,\n\tmaxBytes: number,\n): { hash?: string; skipped: \"size\" | \"error\" | false } {\n\ttry {\n\t\tconst full = `${toplevel}/${path}`;\n\t\tconst stat = lstatSync(full);\n\t\tif (stat.isFile()) {\n\t\t\tif (stat.size > maxBytes) return { skipped: \"size\" };\n\t\t\treturn { hash: `sha256:${createHash(\"sha256\").update(readFileSync(full)).digest(\"hex\")}`, skipped: false };\n\t\t}\n\t\tif (stat.isSymbolicLink()) {\n\t\t\treturn {\n\t\t\t\thash: `sha256:${createHash(\"sha256\").update(readlinkSync(full)).digest(\"hex\")}`,\n\t\t\t\tskipped: false,\n\t\t\t};\n\t\t}\n\t\t// Directories (submodule gitlinks) have no worktree content to hash;\n\t\t// that is expected, not a coverage gap.\n\t\tif (stat.isDirectory()) return { skipped: false };\n\t\treturn { skipped: \"error\" };\n\t} catch {\n\t\treturn { skipped: \"error\" };\n\t}\n}\n\nfunction prefixRelative(prefix: string, path: string): string {\n\tif (prefix === \"\" || prefix === \".\") return path;\n\treturn `${prefix}/${path}`;\n}\n\n/**\n * Observe a Git workspace without mutating it. Returns a version-1\n * `WorkspaceStateRecord`: `unsupported` for non-Git workspaces, `failed`\n * when git could not run or the observation was cancelled, and `incomplete`\n * when a limit truncated the capture. `observed` never implies more than\n * `coverage` states.\n */\nexport interface ToplevelComparison {\n\t/** Whether the physically resolved workspace root sits under the toplevel. */\n\tinside: boolean;\n\t/** Root path relative to the toplevel; strip this prefix from porcelain paths. */\n\tprefix: string;\n\t/** Physically resolved toplevel; base for absolute-path work like hashing. */\n\ttoplevelReal: string;\n}\n\n/**\n * Decide containment of the workspace root inside git's toplevel after both\n * sides are physically resolved. Windows spellings diverge from what Node's\n * realpath returns for the same directory (short 8.3 names, drive-letter\n * case), so the win32 branch resolves through the native resolver, folds\n * case for the comparison, and uses win32 path semantics. The platform and\n * resolver are injectable so tests can exercise those branches anywhere.\n */\nexport function compareToplevel(\n\tworkspaceRoot: string,\n\ttoplevel: string,\n\toptions?: {\n\t\tplatform?: NodeJS.Platform;\n\t\trealpath?: (path: string) => string;\n\t},\n): ToplevelComparison {\n\tconst platform = options?.platform ?? process.platform;\n\tconst isWin32 = platform === \"win32\";\n\tconst realpath =\n\t\toptions?.realpath ??\n\t\t(isWin32\n\t\t\t? (p: string) => {\n\t\t\t\t\ttry {\n\t\t\t\t\t\treturn realpathSync.native(p);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\treturn realpathSync(p);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t: realpathSync);\n\tconst rootReal = realpath(workspaceRoot);\n\tconst toplevelReal = realpath(toplevel);\n\tconst pathMod = isWin32 ? pathWin32 : { relative, sep, dirname };\n\tconst fold = (p: string) => (isWin32 ? p.toLowerCase() : p);\n\tconst prefix = pathMod.relative(toplevelReal, rootReal);\n\tconst inside = !(prefix === \"..\" || prefix.startsWith(`..${pathMod.sep}`) || isAbsolute(prefix));\n\tif (isWin32 && inside) {\n\t\t// Recompute the strip prefix under case folding so a divergent drive or\n\t\t// directory case still yields the clean \"\" or relative form.\n\t\tconst folded = pathMod.relative(fold(toplevelReal), fold(rootReal));\n\t\treturn { inside, prefix: folded, toplevelReal };\n\t}\n\treturn { inside, prefix, toplevelReal };\n}\n\nexport async function observeWorkspaceGit(\n\tworkspaceRoot: string,\n\toptions?: GitObserveOptions,\n): Promise<WorkspaceStateRecord> {\n\tconst maxPaths = options?.maxPaths ?? DEFAULT_MAX_PATHS;\n\tconst maxHashBytes = options?.maxHashBytes ?? DEFAULT_MAX_HASH_BYTES;\n\tconst timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\tconst hashPaths = options?.hashPaths ?? true;\n\tconst signal = options?.signal;\n\tconst excludePaths = (options?.excludePaths ?? [])\n\t\t.map((p) => p.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\").replace(/\\/+$/, \"\"))\n\t\t.filter((p) => p.length > 0);\n\tconst isExcluded = (repoPath: string): boolean =>\n\t\texcludePaths.some((ex) => repoPath === ex || repoPath.startsWith(`${ex}/`));\n\n\tconst warnings: string[] = [];\n\tconst failed = (message: string): WorkspaceStateRecord => ({\n\t\tversion: WORKSPACE_RECORD_VERSION,\n\t\tobservationId: randomUUID(),\n\t\tstatus: \"failed\",\n\t\tbackend: \"git\",\n\t\tworkspaceRoot,\n\t\tcapturedAt: new Date().toISOString(),\n\t\tcoverage: emptyCoverage(),\n\t\tpaths: [],\n\t\twarnings: [message],\n\t});\n\n\tif (signal?.aborted) {\n\t\treturn failed(\"workspace observation cancelled\");\n\t}\n\n\tconst head = await runGit(workspaceRoot, [\"rev-parse\", \"--show-toplevel\"], timeoutMs, signal);\n\tif (head.spawnError) return failed(\"git could not be executed\");\n\tif (head.timedOut) return failed(\"workspace observation timed out\");\n\tif (signal?.aborted) return failed(\"workspace observation cancelled\");\n\tif (!head.ok) {\n\t\tif (/not a git repository/i.test(head.stderr) || head.code === 128) {\n\t\t\treturn {\n\t\t\t\t...failed(\"not a git repository\"),\n\t\t\t\tstatus: \"unsupported\",\n\t\t\t};\n\t\t}\n\t\treturn failed(\"git rev-parse failed\");\n\t}\n\t// git resolves the toplevel physically (macOS /tmp -> /private/tmp,\n\t// Windows drive-letter case and short names), so containment is decided\n\t// through compareToplevel; otherwise a divergent spelling of the same\n\t// directory would fail the observation or corrupt every reported path.\n\tconst toplevel = head.stdout.toString(\"utf-8\").trim();\n\tconst comparison = compareToplevel(workspaceRoot, toplevel);\n\tif (!comparison.inside) {\n\t\treturn failed(\"workspace root is outside the repository toplevel\");\n\t}\n\tconst insidePrefix = comparison.prefix;\n\n\tconst headCommit = await runGit(workspaceRoot, [\"rev-parse\", \"--verify\", \"HEAD\"], timeoutMs, signal);\n\tconst mergeHead = await runGit(workspaceRoot, [\"rev-parse\", \"-q\", \"--verify\", \"MERGE_HEAD\"], timeoutMs, signal);\n\tif (signal?.aborted) return failed(\"workspace observation cancelled\");\n\tif (mergeHead.ok) warnings.push(\"merge in progress\");\n\tconst branch = await runGit(workspaceRoot, [\"branch\", \"--show-current\"], timeoutMs, signal);\n\n\tconst headCommitValue = headCommit.ok ? headCommit.stdout.toString(\"utf-8\").trim() : undefined;\n\tif (!headCommit.ok) warnings.push(\"unborn HEAD (no commits)\");\n\tconst branchValue = branch.ok ? branch.stdout.toString(\"utf-8\").trim() : \"\";\n\tif (branchValue === \"\") warnings.push(\"detached HEAD\");\n\n\t// Index baseline.\n\tconst index = await runGit(workspaceRoot, [\"ls-files\", \"--stage\", \"-z\"], timeoutMs, signal);\n\tif (!index.ok) return failed(\"git ls-files failed\");\n\tconst indexDigest = `sha256:${createHash(\"sha256\").update(index.stdout).digest(\"hex\")}`;\n\n\t// Staged / unstaged / untracked / ignored change sets.\n\tconst status = await runGit(\n\t\tworkspaceRoot,\n\t\t[\"status\", \"--porcelain\", \"-z\", \"--untracked-files=all\", \"--ignored=matching\"],\n\t\ttimeoutMs,\n\t\tsignal,\n\t);\n\tif (!status.ok) return failed(\"git status failed\");\n\n\tconst paths: WorkspaceStatePath[] = [];\n\tlet truncated = false;\n\tlet skippedHashes = 0;\n\tfor (const entry of parsePorcelainZ(status.stdout)) {\n\t\tif (isExcluded(entry.path) || (entry.previousPath !== undefined && isExcluded(entry.previousPath))) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (paths.length >= maxPaths) {\n\t\t\ttruncated = true;\n\t\t\twarnings.push(`path list truncated at ${maxPaths} paths`);\n\t\t\tbreak;\n\t\t}\n\t\tconst { kind, staged, unstaged, ignored } = classify(entry);\n\t\tconst workspacePath: WorkspaceStatePath = {\n\t\t\tpath: prefixRelative(insidePrefix, entry.path),\n\t\t\tkind,\n\t\t\tstaged,\n\t\t\tunstaged,\n\t\t\t...(ignored ? { ignored: true } : {}),\n\t\t\t...(entry.previousPath ? { previousPath: prefixRelative(insidePrefix, entry.previousPath) } : {}),\n\t\t};\n\t\tif (hashPaths && kind !== \"deleted\") {\n\t\t\tconst { hash, skipped } = hashWorkspacePath(comparison.toplevelReal, entry.path, maxHashBytes);\n\t\t\tif (hash) workspacePath.contentHash = hash;\n\t\t\telse if (skipped) skippedHashes++;\n\t\t}\n\t\tpaths.push(workspacePath);\n\t}\n\tif (skippedHashes > 0) warnings.push(`content hashing skipped for ${skippedHashes} path(s)`);\n\n\t// Digest over exactly the paths this record includes, so a later\n\t// comparison can cheaply detect that the covered state moved.\n\tconst digestInput = paths\n\t\t.map(\n\t\t\t(p) =>\n\t\t\t\t`${p.path}\\0${p.kind}\\0${p.staged ? \"S\" : \"\"}${p.unstaged ? \"U\" : \"\"}${p.ignored ? \"I\" : \"\"}\\0${p.contentHash ?? \"\"}\\n`,\n\t\t)\n\t\t.sort()\n\t\t.join(\"\");\n\n\treturn {\n\t\tversion: WORKSPACE_RECORD_VERSION,\n\t\tobservationId: randomUUID(),\n\t\tstatus: truncated || skippedHashes > 0 ? \"incomplete\" : \"observed\",\n\t\tbackend: \"git\",\n\t\tworkspaceRoot,\n\t\tcapturedAt: new Date().toISOString(),\n\t\t// `hashes` reflects the configured policy: a disabled hash pass is a\n\t\t// coverage statement, not an incomplete capture.\n\t\tcoverage: { ...fullCoverage(), hashes: hashPaths },\n\t\tbase: {\n\t\t\t...(headCommitValue ? { headCommit: headCommitValue } : {}),\n\t\t\t...(branchValue ? { branch: branchValue } : {}),\n\t\t\tindexDigest,\n\t\t\t...(truncated ? {} : { worktreeDigest: `sha256:${createHash(\"sha256\").update(digestInput).digest(\"hex\")}` }),\n\t\t},\n\t\tpaths,\n\t\twarnings,\n\t};\n}\n"]}

package/dist/core/workspace/git-observer.js

@@ -0,0 +1,346 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, win32 as pathWin32, relative, sep } from "node:path";
+import { WORKSPACE_RECORD_VERSION, } from "./state.js";
+/**
+ * Read-only Git workspace observation (spec 2026-09-01-harness-correctness-
+ * and-workspace-state.md § 1).
+ *
+ * The adapter never mutates repository state: `HEAD`, the current branch, the
+ * index, the worktree, the stash, and local config are only read. Optional
+ * index locks are disabled (`GIT_OPTIONAL_LOCKS=0`) so even `git status`
+ * cannot refresh the on-disk index. It never walks the workspace; all path
+ * knowledge comes from git. Symlinks are hashed as link text (what git
+ * stores), never followed. Submodule (gitlink) paths carry no worktree hash.
+ */
+const DEFAULT_MAX_PATHS = 200;
+const DEFAULT_MAX_HASH_BYTES = 5 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const GIT_CONFIG = ["-c", "core.autocrlf=false", "-c", "status.renames=true"];
+const UNMERGED_XY = new Set(["DD", "AU", "UD", "UA", "DU", "AA", "UU"]);
+function runGit(cwd, args, timeoutMs, signal) {
+    return new Promise((resolve) => {
+        let stdout = Buffer.alloc(0);
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        let child;
+        const finish = (code, spawnError) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            resolve({
+                ok: !spawnError && !timedOut && code === 0,
+                code,
+                stdout,
+                stderr,
+                timedOut,
+                spawnError,
+            });
+        };
+        const onAbort = () => {
+            child?.kill("SIGKILL");
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child?.kill("SIGKILL");
+        }, timeoutMs);
+        try {
+            child = spawn("git", [...GIT_CONFIG, ...args], {
+                cwd,
+                shell: false,
+                stdio: ["ignore", "pipe", "pipe"],
+                // Observation must leave the on-disk index untouched.
+                env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+            });
+        }
+        catch {
+            resolve({ ok: false, code: null, stdout, stderr: "", timedOut: false, spawnError: true });
+            return;
+        }
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort, { once: true });
+        }
+        child.stdout?.on("data", (chunk) => {
+            stdout = Buffer.concat([stdout, chunk]);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf-8");
+        });
+        child.on("error", () => finish(null, true));
+        child.on("close", (code) => finish(code, false));
+    });
+}
+function emptyCoverage() {
+    return {
+        tracked: false,
+        staged: false,
+        unstaged: false,
+        untracked: false,
+        ignored: false,
+        hashes: false,
+        patch: false,
+    };
+}
+function fullCoverage() {
+    return {
+        tracked: true,
+        staged: true,
+        unstaged: true,
+        untracked: true,
+        ignored: true,
+        hashes: true,
+        patch: false,
+    };
+}
+function parsePorcelainZ(stdout) {
+    const fields = stdout.toString("utf-8").split("\0");
+    const parsed = [];
+    let i = 0;
+    while (i < fields.length) {
+        const record = fields[i++];
+        if (!record || record.length < 4)
+            continue;
+        const entry = { x: record[0], y: record[1], path: record.slice(3) };
+        if (entry.x === "R" || entry.x === "C" || entry.y === "R" || entry.y === "C") {
+            entry.previousPath = fields[i++];
+        }
+        parsed.push(entry);
+    }
+    return parsed;
+}
+function classify(entry) {
+    const { x, y } = entry;
+    if (x === "?" && y === "?") {
+        return { kind: "untracked", staged: false, unstaged: false, ignored: false };
+    }
+    if (x === "!" && y === "!") {
+        return { kind: "untracked", staged: false, unstaged: false, ignored: true };
+    }
+    if (UNMERGED_XY.has(`${x}${y}`)) {
+        return {
+            kind: x === "D" && y === "D" ? "deleted" : "modified",
+            staged: true,
+            unstaged: true,
+            ignored: false,
+        };
+    }
+    let kind = "modified";
+    if (x === "A" || y === "A" || x === "C" || y === "C")
+        kind = "added";
+    else if (x === "D" || y === "D")
+        kind = "deleted";
+    else if (x === "R" || y === "R")
+        kind = "renamed";
+    return {
+        kind,
+        staged: x !== " " && x !== "?" && x !== "!",
+        unstaged: y !== " " && y !== "?" && y !== "!",
+        ignored: false,
+    };
+}
+/** Hash one workspace path: regular files by bytes, symlinks by link text. */
+function hashWorkspacePath(toplevel, path, maxBytes) {
+    try {
+        const full = `${toplevel}/${path}`;
+        const stat = lstatSync(full);
+        if (stat.isFile()) {
+            if (stat.size > maxBytes)
+                return { skipped: "size" };
+            return { hash: `sha256:${createHash("sha256").update(readFileSync(full)).digest("hex")}`, skipped: false };
+        }
+        if (stat.isSymbolicLink()) {
+            return {
+                hash: `sha256:${createHash("sha256").update(readlinkSync(full)).digest("hex")}`,
+                skipped: false,
+            };
+        }
+        // Directories (submodule gitlinks) have no worktree content to hash;
+        // that is expected, not a coverage gap.
+        if (stat.isDirectory())
+            return { skipped: false };
+        return { skipped: "error" };
+    }
+    catch {
+        return { skipped: "error" };
+    }
+}
+function prefixRelative(prefix, path) {
+    if (prefix === "" || prefix === ".")
+        return path;
+    return `${prefix}/${path}`;
+}
+/**
+ * Decide containment of the workspace root inside git's toplevel after both
+ * sides are physically resolved. Windows spellings diverge from what Node's
+ * realpath returns for the same directory (short 8.3 names, drive-letter
+ * case), so the win32 branch resolves through the native resolver, folds
+ * case for the comparison, and uses win32 path semantics. The platform and
+ * resolver are injectable so tests can exercise those branches anywhere.
+ */
+export function compareToplevel(workspaceRoot, toplevel, options) {
+    const platform = options?.platform ?? process.platform;
+    const isWin32 = platform === "win32";
+    const realpath = options?.realpath ??
+        (isWin32
+            ? (p) => {
+                try {
+                    return realpathSync.native(p);
+                }
+                catch {
+                    return realpathSync(p);
+                }
+            }
+            : realpathSync);
+    const rootReal = realpath(workspaceRoot);
+    const toplevelReal = realpath(toplevel);
+    const pathMod = isWin32 ? pathWin32 : { relative, sep, dirname };
+    const fold = (p) => (isWin32 ? p.toLowerCase() : p);
+    const prefix = pathMod.relative(toplevelReal, rootReal);
+    const inside = !(prefix === ".." || prefix.startsWith(`..${pathMod.sep}`) || isAbsolute(prefix));
+    if (isWin32 && inside) {
+        // Recompute the strip prefix under case folding so a divergent drive or
+        // directory case still yields the clean "" or relative form.
+        const folded = pathMod.relative(fold(toplevelReal), fold(rootReal));
+        return { inside, prefix: folded, toplevelReal };
+    }
+    return { inside, prefix, toplevelReal };
+}
+export async function observeWorkspaceGit(workspaceRoot, options) {
+    const maxPaths = options?.maxPaths ?? DEFAULT_MAX_PATHS;
+    const maxHashBytes = options?.maxHashBytes ?? DEFAULT_MAX_HASH_BYTES;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const hashPaths = options?.hashPaths ?? true;
+    const signal = options?.signal;
+    const excludePaths = (options?.excludePaths ?? [])
+        .map((p) => p.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, ""))
+        .filter((p) => p.length > 0);
+    const isExcluded = (repoPath) => excludePaths.some((ex) => repoPath === ex || repoPath.startsWith(`${ex}/`));
+    const warnings = [];
+    const failed = (message) => ({
+        version: WORKSPACE_RECORD_VERSION,
+        observationId: randomUUID(),
+        status: "failed",
+        backend: "git",
+        workspaceRoot,
+        capturedAt: new Date().toISOString(),
+        coverage: emptyCoverage(),
+        paths: [],
+        warnings: [message],
+    });
+    if (signal?.aborted) {
+        return failed("workspace observation cancelled");
+    }
+    const head = await runGit(workspaceRoot, ["rev-parse", "--show-toplevel"], timeoutMs, signal);
+    if (head.spawnError)
+        return failed("git could not be executed");
+    if (head.timedOut)
+        return failed("workspace observation timed out");
+    if (signal?.aborted)
+        return failed("workspace observation cancelled");
+    if (!head.ok) {
+        if (/not a git repository/i.test(head.stderr) || head.code === 128) {
+            return {
+                ...failed("not a git repository"),
+                status: "unsupported",
+            };
+        }
+        return failed("git rev-parse failed");
+    }
+    // git resolves the toplevel physically (macOS /tmp -> /private/tmp,
+    // Windows drive-letter case and short names), so containment is decided
+    // through compareToplevel; otherwise a divergent spelling of the same
+    // directory would fail the observation or corrupt every reported path.
+    const toplevel = head.stdout.toString("utf-8").trim();
+    const comparison = compareToplevel(workspaceRoot, toplevel);
+    if (!comparison.inside) {
+        return failed("workspace root is outside the repository toplevel");
+    }
+    const insidePrefix = comparison.prefix;
+    const headCommit = await runGit(workspaceRoot, ["rev-parse", "--verify", "HEAD"], timeoutMs, signal);
+    const mergeHead = await runGit(workspaceRoot, ["rev-parse", "-q", "--verify", "MERGE_HEAD"], timeoutMs, signal);
+    if (signal?.aborted)
+        return failed("workspace observation cancelled");
+    if (mergeHead.ok)
+        warnings.push("merge in progress");
+    const branch = await runGit(workspaceRoot, ["branch", "--show-current"], timeoutMs, signal);
+    const headCommitValue = headCommit.ok ? headCommit.stdout.toString("utf-8").trim() : undefined;
+    if (!headCommit.ok)
+        warnings.push("unborn HEAD (no commits)");
+    const branchValue = branch.ok ? branch.stdout.toString("utf-8").trim() : "";
+    if (branchValue === "")
+        warnings.push("detached HEAD");
+    // Index baseline.
+    const index = await runGit(workspaceRoot, ["ls-files", "--stage", "-z"], timeoutMs, signal);
+    if (!index.ok)
+        return failed("git ls-files failed");
+    const indexDigest = `sha256:${createHash("sha256").update(index.stdout).digest("hex")}`;
+    // Staged / unstaged / untracked / ignored change sets.
+    const status = await runGit(workspaceRoot, ["status", "--porcelain", "-z", "--untracked-files=all", "--ignored=matching"], timeoutMs, signal);
+    if (!status.ok)
+        return failed("git status failed");
+    const paths = [];
+    let truncated = false;
+    let skippedHashes = 0;
+    for (const entry of parsePorcelainZ(status.stdout)) {
+        if (isExcluded(entry.path) || (entry.previousPath !== undefined && isExcluded(entry.previousPath))) {
+            continue;
+        }
+        if (paths.length >= maxPaths) {
+            truncated = true;
+            warnings.push(`path list truncated at ${maxPaths} paths`);
+            break;
+        }
+        const { kind, staged, unstaged, ignored } = classify(entry);
+        const workspacePath = {
+            path: prefixRelative(insidePrefix, entry.path),
+            kind,
+            staged,
+            unstaged,
+            ...(ignored ? { ignored: true } : {}),
+            ...(entry.previousPath ? { previousPath: prefixRelative(insidePrefix, entry.previousPath) } : {}),
+        };
+        if (hashPaths && kind !== "deleted") {
+            const { hash, skipped } = hashWorkspacePath(comparison.toplevelReal, entry.path, maxHashBytes);
+            if (hash)
+                workspacePath.contentHash = hash;
+            else if (skipped)
+                skippedHashes++;
+        }
+        paths.push(workspacePath);
+    }
+    if (skippedHashes > 0)
+        warnings.push(`content hashing skipped for ${skippedHashes} path(s)`);
+    // Digest over exactly the paths this record includes, so a later
+    // comparison can cheaply detect that the covered state moved.
+    const digestInput = paths
+        .map((p) => `${p.path}\0${p.kind}\0${p.staged ? "S" : ""}${p.unstaged ? "U" : ""}${p.ignored ? "I" : ""}\0${p.contentHash ?? ""}\n`)
+        .sort()
+        .join("");
+    return {
+        version: WORKSPACE_RECORD_VERSION,
+        observationId: randomUUID(),
+        status: truncated || skippedHashes > 0 ? "incomplete" : "observed",
+        backend: "git",
+        workspaceRoot,
+        capturedAt: new Date().toISOString(),
+        // `hashes` reflects the configured policy: a disabled hash pass is a
+        // coverage statement, not an incomplete capture.
+        coverage: { ...fullCoverage(), hashes: hashPaths },
+        base: {
+            ...(headCommitValue ? { headCommit: headCommitValue } : {}),
+            ...(branchValue ? { branch: branchValue } : {}),
+            indexDigest,
+            ...(truncated ? {} : { worktreeDigest: `sha256:${createHash("sha256").update(digestInput).digest("hex")}` }),
+        },
+        paths,
+        warnings,
+    };
+}
+//# sourceMappingURL=git-observer.js.map

package/dist/core/workspace/git-observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-observer.js","sourceRoot":"","sources":["../../../src/core/workspace/git-observer.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ChildProcess, spawn } from \"node:child_process\";\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { lstatSync, readFileSync, readlinkSync, realpathSync } from \"node:fs\";\nimport { dirname, isAbsolute, win32 as pathWin32, relative, sep } from \"node:path\";\nimport {\n\tWORKSPACE_RECORD_VERSION,\n\ttype WorkspaceStateCoverage,\n\ttype WorkspaceStatePath,\n\ttype WorkspaceStateRecord,\n} from \"./state.ts\";\n\n/**\n * Read-only Git workspace observation (spec 2026-09-01-harness-correctness-\n * and-workspace-state.md § 1).\n *\n * The adapter never mutates repository state: `HEAD`, the current branch, the\n * index, the worktree, the stash, and local config are only read. Optional\n * index locks are disabled (`GIT_OPTIONAL_LOCKS=0`) so even `git status`\n * cannot refresh the on-disk index. It never walks the workspace; all path\n * knowledge comes from git. Symlinks are hashed as link text (what git\n * stores), never followed. Submodule (gitlink) paths carry no worktree hash.\n */\n\nconst DEFAULT_MAX_PATHS = 200;\nconst DEFAULT_MAX_HASH_BYTES = 5 * 1024 * 1024;\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst GIT_CONFIG = [\"-c\", \"core.autocrlf=false\", \"-c\", \"status.renames=true\"];\nconst UNMERGED_XY = new Set([\"DD\", \"AU\", \"UD\", \"UA\", \"DU\", \"AA\", \"UU\"]);\n\nexport interface GitObserveOptions {\n\t/** Compute per-path content hashes of present files (default true). */\n\thashPaths?: boolean;\n\t/** Maximum number of reported paths (default 200). */\n\tmaxPaths?: number;\n\t/** Skip hashing files larger than this many bytes (default 5 MiB). */\n\tmaxHashBytes?: number;\n\t/** Per-command timeout in milliseconds (default 10 000). */\n\ttimeoutMs?: number;\n\t/** Cancels the observation; the record reports `failed`. */\n\tsignal?: AbortSignal;\n\t/**\n\t * Repository-relative path prefixes to omit from `paths` (exact match or\n\t * directory prefix). Used for harness bookkeeping that lives inside the\n\t * workspace — e.g. the session directory — which is not workspace state.\n\t */\n\texcludePaths?: string[];\n}\n\ninterface GitRunResult {\n\tok: boolean;\n\tcode: number | null;\n\tstdout: Buffer;\n\tstderr: string;\n\ttimedOut: boolean;\n\tspawnError: boolean;\n}\n\nfunction runGit(cwd: string, args: string[], timeoutMs: number, signal?: AbortSignal): Promise<GitRunResult> {\n\treturn new Promise((resolve) => {\n\t\tlet stdout = Buffer.alloc(0);\n\t\tlet stderr = \"\";\n\t\tlet timedOut = false;\n\t\tlet settled = false;\n\t\tlet child: ChildProcess;\n\t\tconst finish = (code: number | null, spawnError: boolean) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tclearTimeout(timer);\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tresolve({\n\t\t\t\tok: !spawnError && !timedOut && code === 0,\n\t\t\t\tcode,\n\t\t\t\tstdout,\n\t\t\t\tstderr,\n\t\t\t\ttimedOut,\n\t\t\t\tspawnError,\n\t\t\t});\n\t\t};\n\t\tconst onAbort = () => {\n\t\t\tchild?.kill(\"SIGKILL\");\n\t\t};\n\t\tconst timer = setTimeout(() => {\n\t\t\ttimedOut = true;\n\t\t\tchild?.kill(\"SIGKILL\");\n\t\t}, timeoutMs);\n\t\ttry {\n\t\t\tchild = spawn(\"git\", [...GIT_CONFIG, ...args], {\n\t\t\t\tcwd,\n\t\t\t\tshell: false,\n\t\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\t\t// Observation must leave the on-disk index untouched.\n\t\t\t\tenv: { ...process.env, GIT_OPTIONAL_LOCKS: \"0\" },\n\t\t\t});\n\t\t} catch {\n\t\t\tresolve({ ok: false, code: null, stdout, stderr: \"\", timedOut: false, spawnError: true });\n\t\t\treturn;\n\t\t}\n\t\tif (signal) {\n\t\t\tif (signal.aborted) onAbort();\n\t\t\telse signal.addEventListener(\"abort\", onAbort, { once: true });\n\t\t}\n\t\tchild.stdout?.on(\"data\", (chunk: Buffer) => {\n\t\t\tstdout = Buffer.concat([stdout, chunk]);\n\t\t});\n\t\tchild.stderr?.on(\"data\", (chunk: Buffer) => {\n\t\t\tstderr += chunk.toString(\"utf-8\");\n\t\t});\n\t\tchild.on(\"error\", () => finish(null, true));\n\t\tchild.on(\"close\", (code) => finish(code, false));\n\t});\n}\n\nfunction emptyCoverage(): WorkspaceStateCoverage {\n\treturn {\n\t\ttracked: false,\n\t\tstaged: false,\n\t\tunstaged: false,\n\t\tuntracked: false,\n\t\tignored: false,\n\t\thashes: false,\n\t\tpatch: false,\n\t};\n}\n\nfunction fullCoverage(): WorkspaceStateCoverage {\n\treturn {\n\t\ttracked: true,\n\t\tstaged: true,\n\t\tunstaged: true,\n\t\tuntracked: true,\n\t\tignored: true,\n\t\thashes: true,\n\t\tpatch: false,\n\t};\n}\n\ninterface ParsedStatusPath {\n\tx: string;\n\ty: string;\n\tpath: string;\n\tpreviousPath?: string;\n}\n\nfunction parsePorcelainZ(stdout: Buffer): ParsedStatusPath[] {\n\tconst fields = stdout.toString(\"utf-8\").split(\"\\0\");\n\tconst parsed: ParsedStatusPath[] = [];\n\tlet i = 0;\n\twhile (i < fields.length) {\n\t\tconst record = fields[i++];\n\t\tif (!record || record.length < 4) continue;\n\t\tconst entry: ParsedStatusPath = { x: record[0], y: record[1], path: record.slice(3) };\n\t\tif (entry.x === \"R\" || entry.x === \"C\" || entry.y === \"R\" || entry.y === \"C\") {\n\t\t\tentry.previousPath = fields[i++];\n\t\t}\n\t\tparsed.push(entry);\n\t}\n\treturn parsed;\n}\n\nfunction classify(entry: ParsedStatusPath): {\n\tkind: WorkspaceStatePath[\"kind\"];\n\tstaged: boolean;\n\tunstaged: boolean;\n\tignored: boolean;\n} {\n\tconst { x, y } = entry;\n\tif (x === \"?\" && y === \"?\") {\n\t\treturn { kind: \"untracked\", staged: false, unstaged: false, ignored: false };\n\t}\n\tif (x === \"!\" && y === \"!\") {\n\t\treturn { kind: \"untracked\", staged: false, unstaged: false, ignored: true };\n\t}\n\tif (UNMERGED_XY.has(`${x}${y}`)) {\n\t\treturn {\n\t\t\tkind: x === \"D\" && y === \"D\" ? \"deleted\" : \"modified\",\n\t\t\tstaged: true,\n\t\t\tunstaged: true,\n\t\t\tignored: false,\n\t\t};\n\t}\n\tlet kind: WorkspaceStatePath[\"kind\"] = \"modified\";\n\tif (x === \"A\" || y === \"A\" || x === \"C\" || y === \"C\") kind = \"added\";\n\telse if (x === \"D\" || y === \"D\") kind = \"deleted\";\n\telse if (x === \"R\" || y === \"R\") kind = \"renamed\";\n\treturn {\n\t\tkind,\n\t\tstaged: x !== \" \" && x !== \"?\" && x !== \"!\",\n\t\tunstaged: y !== \" \" && y !== \"?\" && y !== \"!\",\n\t\tignored: false,\n\t};\n}\n\n/** Hash one workspace path: regular files by bytes, symlinks by link text. */\nfunction hashWorkspacePath(\n\ttoplevel: string,\n\tpath: string,\n\tmaxBytes: number,\n): { hash?: string; skipped: \"size\" | \"error\" | false } {\n\ttry {\n\t\tconst full = `${toplevel}/${path}`;\n\t\tconst stat = lstatSync(full);\n\t\tif (stat.isFile()) {\n\t\t\tif (stat.size > maxBytes) return { skipped: \"size\" };\n\t\t\treturn { hash: `sha256:${createHash(\"sha256\").update(readFileSync(full)).digest(\"hex\")}`, skipped: false };\n\t\t}\n\t\tif (stat.isSymbolicLink()) {\n\t\t\treturn {\n\t\t\t\thash: `sha256:${createHash(\"sha256\").update(readlinkSync(full)).digest(\"hex\")}`,\n\t\t\t\tskipped: false,\n\t\t\t};\n\t\t}\n\t\t// Directories (submodule gitlinks) have no worktree content to hash;\n\t\t// that is expected, not a coverage gap.\n\t\tif (stat.isDirectory()) return { skipped: false };\n\t\treturn { skipped: \"error\" };\n\t} catch {\n\t\treturn { skipped: \"error\" };\n\t}\n}\n\nfunction prefixRelative(prefix: string, path: string): string {\n\tif (prefix === \"\" || prefix === \".\") return path;\n\treturn `${prefix}/${path}`;\n}\n\n/**\n * Observe a Git workspace without mutating it. Returns a version-1\n * `WorkspaceStateRecord`: `unsupported` for non-Git workspaces, `failed`\n * when git could not run or the observation was cancelled, and `incomplete`\n * when a limit truncated the capture. `observed` never implies more than\n * `coverage` states.\n */\nexport interface ToplevelComparison {\n\t/** Whether the physically resolved workspace root sits under the toplevel. */\n\tinside: boolean;\n\t/** Root path relative to the toplevel; strip this prefix from porcelain paths. */\n\tprefix: string;\n\t/** Physically resolved toplevel; base for absolute-path work like hashing. */\n\ttoplevelReal: string;\n}\n\n/**\n * Decide containment of the workspace root inside git's toplevel after both\n * sides are physically resolved. Windows spellings diverge from what Node's\n * realpath returns for the same directory (short 8.3 names, drive-letter\n * case), so the win32 branch resolves through the native resolver, folds\n * case for the comparison, and uses win32 path semantics. The platform and\n * resolver are injectable so tests can exercise those branches anywhere.\n */\nexport function compareToplevel(\n\tworkspaceRoot: string,\n\ttoplevel: string,\n\toptions?: {\n\t\tplatform?: NodeJS.Platform;\n\t\trealpath?: (path: string) => string;\n\t},\n): ToplevelComparison {\n\tconst platform = options?.platform ?? process.platform;\n\tconst isWin32 = platform === \"win32\";\n\tconst realpath =\n\t\toptions?.realpath ??\n\t\t(isWin32\n\t\t\t? (p: string) => {\n\t\t\t\t\ttry {\n\t\t\t\t\t\treturn realpathSync.native(p);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\treturn realpathSync(p);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t: realpathSync);\n\tconst rootReal = realpath(workspaceRoot);\n\tconst toplevelReal = realpath(toplevel);\n\tconst pathMod = isWin32 ? pathWin32 : { relative, sep, dirname };\n\tconst fold = (p: string) => (isWin32 ? p.toLowerCase() : p);\n\tconst prefix = pathMod.relative(toplevelReal, rootReal);\n\tconst inside = !(prefix === \"..\" || prefix.startsWith(`..${pathMod.sep}`) || isAbsolute(prefix));\n\tif (isWin32 && inside) {\n\t\t// Recompute the strip prefix under case folding so a divergent drive or\n\t\t// directory case still yields the clean \"\" or relative form.\n\t\tconst folded = pathMod.relative(fold(toplevelReal), fold(rootReal));\n\t\treturn { inside, prefix: folded, toplevelReal };\n\t}\n\treturn { inside, prefix, toplevelReal };\n}\n\nexport async function observeWorkspaceGit(\n\tworkspaceRoot: string,\n\toptions?: GitObserveOptions,\n): Promise<WorkspaceStateRecord> {\n\tconst maxPaths = options?.maxPaths ?? DEFAULT_MAX_PATHS;\n\tconst maxHashBytes = options?.maxHashBytes ?? DEFAULT_MAX_HASH_BYTES;\n\tconst timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\tconst hashPaths = options?.hashPaths ?? true;\n\tconst signal = options?.signal;\n\tconst excludePaths = (options?.excludePaths ?? [])\n\t\t.map((p) => p.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\").replace(/\\/+$/, \"\"))\n\t\t.filter((p) => p.length > 0);\n\tconst isExcluded = (repoPath: string): boolean =>\n\t\texcludePaths.some((ex) => repoPath === ex || repoPath.startsWith(`${ex}/`));\n\n\tconst warnings: string[] = [];\n\tconst failed = (message: string): WorkspaceStateRecord => ({\n\t\tversion: WORKSPACE_RECORD_VERSION,\n\t\tobservationId: randomUUID(),\n\t\tstatus: \"failed\",\n\t\tbackend: \"git\",\n\t\tworkspaceRoot,\n\t\tcapturedAt: new Date().toISOString(),\n\t\tcoverage: emptyCoverage(),\n\t\tpaths: [],\n\t\twarnings: [message],\n\t});\n\n\tif (signal?.aborted) {\n\t\treturn failed(\"workspace observation cancelled\");\n\t}\n\n\tconst head = await runGit(workspaceRoot, [\"rev-parse\", \"--show-toplevel\"], timeoutMs, signal);\n\tif (head.spawnError) return failed(\"git could not be executed\");\n\tif (head.timedOut) return failed(\"workspace observation timed out\");\n\tif (signal?.aborted) return failed(\"workspace observation cancelled\");\n\tif (!head.ok) {\n\t\tif (/not a git repository/i.test(head.stderr) || head.code === 128) {\n\t\t\treturn {\n\t\t\t\t...failed(\"not a git repository\"),\n\t\t\t\tstatus: \"unsupported\",\n\t\t\t};\n\t\t}\n\t\treturn failed(\"git rev-parse failed\");\n\t}\n\t// git resolves the toplevel physically (macOS /tmp -> /private/tmp,\n\t// Windows drive-letter case and short names), so containment is decided\n\t// through compareToplevel; otherwise a divergent spelling of the same\n\t// directory would fail the observation or corrupt every reported path.\n\tconst toplevel = head.stdout.toString(\"utf-8\").trim();\n\tconst comparison = compareToplevel(workspaceRoot, toplevel);\n\tif (!comparison.inside) {\n\t\treturn failed(\"workspace root is outside the repository toplevel\");\n\t}\n\tconst insidePrefix = comparison.prefix;\n\n\tconst headCommit = await runGit(workspaceRoot, [\"rev-parse\", \"--verify\", \"HEAD\"], timeoutMs, signal);\n\tconst mergeHead = await runGit(workspaceRoot, [\"rev-parse\", \"-q\", \"--verify\", \"MERGE_HEAD\"], timeoutMs, signal);\n\tif (signal?.aborted) return failed(\"workspace observation cancelled\");\n\tif (mergeHead.ok) warnings.push(\"merge in progress\");\n\tconst branch = await runGit(workspaceRoot, [\"branch\", \"--show-current\"], timeoutMs, signal);\n\n\tconst headCommitValue = headCommit.ok ? headCommit.stdout.toString(\"utf-8\").trim() : undefined;\n\tif (!headCommit.ok) warnings.push(\"unborn HEAD (no commits)\");\n\tconst branchValue = branch.ok ? branch.stdout.toString(\"utf-8\").trim() : \"\";\n\tif (branchValue === \"\") warnings.push(\"detached HEAD\");\n\n\t// Index baseline.\n\tconst index = await runGit(workspaceRoot, [\"ls-files\", \"--stage\", \"-z\"], timeoutMs, signal);\n\tif (!index.ok) return failed(\"git ls-files failed\");\n\tconst indexDigest = `sha256:${createHash(\"sha256\").update(index.stdout).digest(\"hex\")}`;\n\n\t// Staged / unstaged / untracked / ignored change sets.\n\tconst status = await runGit(\n\t\tworkspaceRoot,\n\t\t[\"status\", \"--porcelain\", \"-z\", \"--untracked-files=all\", \"--ignored=matching\"],\n\t\ttimeoutMs,\n\t\tsignal,\n\t);\n\tif (!status.ok) return failed(\"git status failed\");\n\n\tconst paths: WorkspaceStatePath[] = [];\n\tlet truncated = false;\n\tlet skippedHashes = 0;\n\tfor (const entry of parsePorcelainZ(status.stdout)) {\n\t\tif (isExcluded(entry.path) || (entry.previousPath !== undefined && isExcluded(entry.previousPath))) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (paths.length >= maxPaths) {\n\t\t\ttruncated = true;\n\t\t\twarnings.push(`path list truncated at ${maxPaths} paths`);\n\t\t\tbreak;\n\t\t}\n\t\tconst { kind, staged, unstaged, ignored } = classify(entry);\n\t\tconst workspacePath: WorkspaceStatePath = {\n\t\t\tpath: prefixRelative(insidePrefix, entry.path),\n\t\t\tkind,\n\t\t\tstaged,\n\t\t\tunstaged,\n\t\t\t...(ignored ? { ignored: true } : {}),\n\t\t\t...(entry.previousPath ? { previousPath: prefixRelative(insidePrefix, entry.previousPath) } : {}),\n\t\t};\n\t\tif (hashPaths && kind !== \"deleted\") {\n\t\t\tconst { hash, skipped } = hashWorkspacePath(comparison.toplevelReal, entry.path, maxHashBytes);\n\t\t\tif (hash) workspacePath.contentHash = hash;\n\t\t\telse if (skipped) skippedHashes++;\n\t\t}\n\t\tpaths.push(workspacePath);\n\t}\n\tif (skippedHashes > 0) warnings.push(`content hashing skipped for ${skippedHashes} path(s)`);\n\n\t// Digest over exactly the paths this record includes, so a later\n\t// comparison can cheaply detect that the covered state moved.\n\tconst digestInput = paths\n\t\t.map(\n\t\t\t(p) =>\n\t\t\t\t`${p.path}\\0${p.kind}\\0${p.staged ? \"S\" : \"\"}${p.unstaged ? \"U\" : \"\"}${p.ignored ? \"I\" : \"\"}\\0${p.contentHash ?? \"\"}\\n`,\n\t\t)\n\t\t.sort()\n\t\t.join(\"\");\n\n\treturn {\n\t\tversion: WORKSPACE_RECORD_VERSION,\n\t\tobservationId: randomUUID(),\n\t\tstatus: truncated || skippedHashes > 0 ? \"incomplete\" : \"observed\",\n\t\tbackend: \"git\",\n\t\tworkspaceRoot,\n\t\tcapturedAt: new Date().toISOString(),\n\t\t// `hashes` reflects the configured policy: a disabled hash pass is a\n\t\t// coverage statement, not an incomplete capture.\n\t\tcoverage: { ...fullCoverage(), hashes: hashPaths },\n\t\tbase: {\n\t\t\t...(headCommitValue ? { headCommit: headCommitValue } : {}),\n\t\t\t...(branchValue ? { branch: branchValue } : {}),\n\t\t\tindexDigest,\n\t\t\t...(truncated ? {} : { worktreeDigest: `sha256:${createHash(\"sha256\").update(digestInput).digest(\"hex\")}` }),\n\t\t},\n\t\tpaths,\n\t\twarnings,\n\t};\n}\n"]}

package/dist/core/workspace/projection.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceStateRecord } from "./state.ts";
+export declare function formatWorkspaceProjection(record: WorkspaceStateRecord): string;
+//# sourceMappingURL=projection.d.ts.map

package/dist/core/workspace/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../src/core/workspace/projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAyB3E,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAiC9E","sourcesContent":["import type { WorkspaceStatePath, WorkspaceStateRecord } from \"./state.ts\";\n\n/**\n * Bounded, model-facing projection of a workspace observation (spec\n * 2026-09-01-harness-correctness-and-workspace-state.md § 3): status, base\n * identity, grouped paths, coverage/incomplete notices. Never hashes, never\n * artifact bytes, never absolute workspace paths.\n */\n\nconst MAX_PATHS_PER_GROUP = 20;\nconst HEAD_ABBREV = 7;\n\nfunction groupLabel(path: WorkspaceStatePath): string {\n\tif (path.ignored) return \"ignored\";\n\tconst flags = [path.staged ? \"staged\" : \"\", path.unstaged ? \"unstaged\" : \"\"].filter(Boolean).join(\" + \");\n\treturn flags ? `${path.kind} (${flags})` : path.kind;\n}\n\nfunction pathLabel(path: WorkspaceStatePath): string {\n\tif (path.kind === \"renamed\" && path.previousPath) {\n\t\treturn `${path.previousPath} -> ${path.path}`;\n\t}\n\treturn path.path;\n}\n\nexport function formatWorkspaceProjection(record: WorkspaceStateRecord): string {\n\tconst headerParts = [`Workspace: ${record.status}`];\n\tif (record.base?.branch) headerParts.push(`branch ${record.base.branch}`);\n\tif (record.base?.headCommit) headerParts.push(`HEAD ${record.base.headCommit.slice(0, HEAD_ABBREV)}`);\n\tconst lines: string[] = [headerParts.join(\" · \")];\n\n\tif (record.status === \"unsupported\") {\n\t\tlines.push(\"No workspace adapter applies to this workspace; treat the workspace as unknown.\");\n\t} else if (record.status === \"failed\") {\n\t\tlines.push(\"Workspace capture failed; treat this snapshot as absent, not as current.\");\n\t} else if (record.status === \"incomplete\") {\n\t\tlines.push(\"Configured limits prevented a complete capture; treat this snapshot as partial.\");\n\t}\n\n\tconst groups = new Map<string, string[]>();\n\tfor (const path of record.paths) {\n\t\tconst label = groupLabel(path);\n\t\tconst group = groups.get(label) ?? [];\n\t\tgroup.push(pathLabel(path));\n\t\tgroups.set(label, group);\n\t}\n\tconst labels = [...groups.keys()].sort();\n\tfor (const label of labels) {\n\t\tconst paths = groups.get(label)!;\n\t\tconst shown = paths.slice(0, MAX_PATHS_PER_GROUP);\n\t\tconst rest = paths.length - shown.length;\n\t\tlines.push(`${label}: ${shown.join(\", \")}${rest > 0 ? `, and ${rest} more` : \"\"}`);\n\t}\n\n\tif (record.warnings.length > 0) {\n\t\tlines.push(`Workspace notices: ${record.warnings.join(\"; \")}`);\n\t}\n\treturn lines.join(\"\\n\");\n}\n"]}