@webpieces/tooling-common 0.0.1

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@webpieces/tooling-common",
+  "version": "0.0.1",
+  "description": "Generic atomic files, errors, harness paths, and repository state paths.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json",
+    "./to-error": "./src/to-error.js"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/tooling/tooling-common"
+  },
+  "dependencies": {
+    "inversify": "7.10.4",
+    "reflect-metadata": "0.2.2",
+    "tslib": "2.8.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./src/index.d.ts"
+}

package/src/atomic-file.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Crash-safe / concurrency-safe file writes for the SHARED `.webpieces/` state dir.
+ *
+ * WHY this exists: once `.webpieces/` is shared by every linked worktree (see SharedStateDir), files
+ * that used to have exactly ONE writer per worktree now have N concurrent writers across the repo —
+ * seven agents, one `merged-branches.json`. A plain `fs.writeFileSync` TRUNCATES first and then writes,
+ * so a reader that opens the file in that window reads a truncated or half-written document and its
+ * `JSON.parse` throws. That is not theoretical: it is exactly the failure PR #526 had to paper over
+ * from the READER side for webpieces.config.json (retry a transient parse failure). This fixes the
+ * WRITER side, which is where it actually belongs — a reader retry cannot help a reader that is handed
+ * a syntactically VALID prefix of a JSON document.
+ *
+ * The fix is write-to-temp-then-`rename()`. POSIX `rename(2)` within a single directory is atomic: a
+ * concurrent reader sees either the entire old file or the entire new one, never a mix, and never a
+ * zero-length file. The temp file MUST be created in the SAME directory as the destination, otherwise
+ * the rename crosses a filesystem boundary, degrades to copy+unlink, and loses the atomicity.
+ *
+ * NOT everything should come through here. Append-only logs (`branch-mutations.log`,
+ * `guard-*.log`) are already concurrency-safe by a different mechanism — `fs.appendFileSync` opens
+ * with O_APPEND and issues ONE `write(2)` per record, which POSIX guarantees not to interleave for
+ * writes under PIPE_BUF. Routing an append through a rename would be strictly WORSE: it would make
+ * concurrent appenders clobber each other's lines wholesale.
+ */
+export declare class AtomicFile {
+    private sequence;
+    /**
+     * Write `contents` to `absPath` so that no concurrent reader can ever observe a partial file.
+     * Creates the parent directory. Throws only if the write itself genuinely failed (disk full,
+     * permissions) — callers that must not fail wrap this.
+     */
+    writeAtomic(absPath: string, contents: string): void;
+    /** `writeAtomic` of a pretty-printed JSON document, trailing newline included. */
+    writeJsonAtomic(absPath: string, value: object): void;
+    /**
+     * Atomic write, SKIPPED when the file already holds exactly `contents`. Returns true when it wrote.
+     *
+     * This is the instruct-ai regeneration case: every `wp-*` command rewrites the same generated docs,
+     * and with a shared `.webpieces/` those rewrites now overlap across worktrees. Identical content is
+     * the overwhelmingly common case, so the cheapest correct answer is to not write at all; when the
+     * content genuinely changed, the write is atomic so a concurrent reader never sees a half-doc.
+     */
+    writeIfChanged(absPath: string, contents: string): boolean;
+    private alreadyHolds;
+    private tempPathFor;
+    private discard;
+}

package/src/atomic-file.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtomicFile = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const inversify_1 = require("inversify");
+const to_error_1 = require("./to-error");
+/**
+ * Crash-safe / concurrency-safe file writes for the SHARED `.webpieces/` state dir.
+ *
+ * WHY this exists: once `.webpieces/` is shared by every linked worktree (see SharedStateDir), files
+ * that used to have exactly ONE writer per worktree now have N concurrent writers across the repo —
+ * seven agents, one `merged-branches.json`. A plain `fs.writeFileSync` TRUNCATES first and then writes,
+ * so a reader that opens the file in that window reads a truncated or half-written document and its
+ * `JSON.parse` throws. That is not theoretical: it is exactly the failure PR #526 had to paper over
+ * from the READER side for webpieces.config.json (retry a transient parse failure). This fixes the
+ * WRITER side, which is where it actually belongs — a reader retry cannot help a reader that is handed
+ * a syntactically VALID prefix of a JSON document.
+ *
+ * The fix is write-to-temp-then-`rename()`. POSIX `rename(2)` within a single directory is atomic: a
+ * concurrent reader sees either the entire old file or the entire new one, never a mix, and never a
+ * zero-length file. The temp file MUST be created in the SAME directory as the destination, otherwise
+ * the rename crosses a filesystem boundary, degrades to copy+unlink, and loses the atomicity.
+ *
+ * NOT everything should come through here. Append-only logs (`branch-mutations.log`,
+ * `guard-*.log`) are already concurrency-safe by a different mechanism — `fs.appendFileSync` opens
+ * with O_APPEND and issues ONE `write(2)` per record, which POSIX guarantees not to interleave for
+ * writes under PIPE_BUF. Routing an append through a rename would be strictly WORSE: it would make
+ * concurrent appenders clobber each other's lines wholesale.
+ */
+let AtomicFile = class AtomicFile {
+    // Distinguishes temp files written by the same process within the same millisecond. Combined with
+    // the pid this makes the temp name unique across every concurrent writer of a shared file.
+    sequence = 0;
+    /**
+     * Write `contents` to `absPath` so that no concurrent reader can ever observe a partial file.
+     * Creates the parent directory. Throws only if the write itself genuinely failed (disk full,
+     * permissions) — callers that must not fail wrap this.
+     */
+    writeAtomic(absPath, contents) {
+        const dir = path.dirname(absPath);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmpPath = this.tempPathFor(absPath);
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.writeFileSync(tmpPath, contents);
+            fs.renameSync(tmpPath, absPath);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            this.discard(tmpPath);
+            throw new Error(`Failed atomic write of ${absPath}: ${error.message}`, { cause: error });
+        }
+    }
+    /** `writeAtomic` of a pretty-printed JSON document, trailing newline included. */
+    writeJsonAtomic(absPath, value) {
+        this.writeAtomic(absPath, JSON.stringify(value, null, 2) + '\n');
+    }
+    /**
+     * Atomic write, SKIPPED when the file already holds exactly `contents`. Returns true when it wrote.
+     *
+     * This is the instruct-ai regeneration case: every `wp-*` command rewrites the same generated docs,
+     * and with a shared `.webpieces/` those rewrites now overlap across worktrees. Identical content is
+     * the overwhelmingly common case, so the cheapest correct answer is to not write at all; when the
+     * content genuinely changed, the write is atomic so a concurrent reader never sees a half-doc.
+     */
+    writeIfChanged(absPath, contents) {
+        if (this.alreadyHolds(absPath, contents))
+            return false;
+        this.writeAtomic(absPath, contents);
+        return true;
+    }
+    // True when the file exists and its bytes already equal `contents`. Any read failure answers false
+    // (rewrite it) — "cannot read the current content" must never read as "it is already correct".
+    alreadyHolds(absPath, contents) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            if (!fs.existsSync(absPath))
+                return false;
+            return fs.readFileSync(absPath, 'utf8') === contents;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return false;
+        }
+    }
+    // A sibling of the destination (same directory ⇒ same filesystem ⇒ the rename stays atomic), named
+    // so a crash leaves an obviously-temporary dotfile rather than something mistaken for real state.
+    tempPathFor(absPath) {
+        this.sequence += 1;
+        const stamp = `${String(process.pid)}-${String(Date.now())}-${String(this.sequence)}`;
+        return path.join(path.dirname(absPath), `.${path.basename(absPath)}.tmp-${stamp}`);
+    }
+    // Best-effort removal of an abandoned temp file. A failure here is not worth reporting over the
+    // original write failure that caused it.
+    discard(tmpPath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            if (fs.existsSync(tmpPath))
+                fs.unlinkSync(tmpPath);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+};
+exports.AtomicFile = AtomicFile;
+exports.AtomicFile = AtomicFile = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], AtomicFile);
+//# sourceMappingURL=atomic-file.js.map

package/src/atomic-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-file.js","sourceRoot":"","sources":["../../../../../packages/tooling/tooling-common/src/atomic-file.ts"],"names":[],"mappings":";;;;AAAA,+CAAyB;AACzB,mDAA6B;AAC7B,yCAA2D;AAE3D,yCAAqC;AAErC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEI,IAAM,UAAU,GAAhB,MAAM,UAAU;IACnB,kGAAkG;IAClG,2FAA2F;IACnF,QAAQ,GAAW,CAAC,CAAC;IAE7B;;;;OAIG;IACH,WAAW,CAAC,OAAe,EAAE,QAAgB;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAClC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC1C,8DAA8D;QAC9D,IAAI,CAAC;YACD,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YACpC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,0BAA0B,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7F,CAAC;IACL,CAAC;IAED,kFAAkF;IAClF,eAAe,CAAC,OAAe,EAAE,KAAa;QAC1C,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;OAOG;IACH,cAAc,CAAC,OAAe,EAAE,QAAgB;QAC5C,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QACvD,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,mGAAmG;IACnG,+FAA+F;IACvF,YAAY,CAAC,OAAe,EAAE,QAAgB;QAClD,8DAA8D;QAC9D,IAAI,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC1C,OAAO,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,QAAQ,CAAC;QACzD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,KAAK,KAAK,CAAC;YACX,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;IAED,mGAAmG;IACnG,kGAAkG;IAC1F,WAAW,CAAC,OAAe;QAC/B,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnB,MAAM,KAAK,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,gGAAgG;IAChG,yCAAyC;IACjC,OAAO,CAAC,OAAe;QAC3B,8DAA8D;QAC9D,IAAI,CAAC;YACD,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,KAAK,KAAK,CAAC;QACf,CAAC;IACL,CAAC;CACJ,CAAA;AA7EY,gCAAU;qBAAV,UAAU;IADtB,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;GAC5B,UAAU,CA6EtB","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { toError } from './to-error';\n\n/**\n * Crash-safe / concurrency-safe file writes for the SHARED `.webpieces/` state dir.\n *\n * WHY this exists: once `.webpieces/` is shared by every linked worktree (see SharedStateDir), files\n * that used to have exactly ONE writer per worktree now have N concurrent writers across the repo —\n * seven agents, one `merged-branches.json`. A plain `fs.writeFileSync` TRUNCATES first and then writes,\n * so a reader that opens the file in that window reads a truncated or half-written document and its\n * `JSON.parse` throws. That is not theoretical: it is exactly the failure PR #526 had to paper over\n * from the READER side for webpieces.config.json (retry a transient parse failure). This fixes the\n * WRITER side, which is where it actually belongs — a reader retry cannot help a reader that is handed\n * a syntactically VALID prefix of a JSON document.\n *\n * The fix is write-to-temp-then-`rename()`. POSIX `rename(2)` within a single directory is atomic: a\n * concurrent reader sees either the entire old file or the entire new one, never a mix, and never a\n * zero-length file. The temp file MUST be created in the SAME directory as the destination, otherwise\n * the rename crosses a filesystem boundary, degrades to copy+unlink, and loses the atomicity.\n *\n * NOT everything should come through here. Append-only logs (`branch-mutations.log`,\n * `guard-*.log`) are already concurrency-safe by a different mechanism — `fs.appendFileSync` opens\n * with O_APPEND and issues ONE `write(2)` per record, which POSIX guarantees not to interleave for\n * writes under PIPE_BUF. Routing an append through a rename would be strictly WORSE: it would make\n * concurrent appenders clobber each other's lines wholesale.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class AtomicFile {\n    // Distinguishes temp files written by the same process within the same millisecond. Combined with\n    // the pid this makes the temp name unique across every concurrent writer of a shared file.\n    private sequence: number = 0;\n\n    /**\n     * Write `contents` to `absPath` so that no concurrent reader can ever observe a partial file.\n     * Creates the parent directory. Throws only if the write itself genuinely failed (disk full,\n     * permissions) — callers that must not fail wrap this.\n     */\n    writeAtomic(absPath: string, contents: string): void {\n        const dir = path.dirname(absPath);\n        fs.mkdirSync(dir, { recursive: true });\n        const tmpPath = this.tempPathFor(absPath);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.writeFileSync(tmpPath, contents);\n            fs.renameSync(tmpPath, absPath);\n        } catch (err: unknown) {\n            const error = toError(err);\n            this.discard(tmpPath);\n            throw new Error(`Failed atomic write of ${absPath}: ${error.message}`, { cause: error });\n        }\n    }\n\n    /** `writeAtomic` of a pretty-printed JSON document, trailing newline included. */\n    writeJsonAtomic(absPath: string, value: object): void {\n        this.writeAtomic(absPath, JSON.stringify(value, null, 2) + '\\n');\n    }\n\n    /**\n     * Atomic write, SKIPPED when the file already holds exactly `contents`. Returns true when it wrote.\n     *\n     * This is the instruct-ai regeneration case: every `wp-*` command rewrites the same generated docs,\n     * and with a shared `.webpieces/` those rewrites now overlap across worktrees. Identical content is\n     * the overwhelmingly common case, so the cheapest correct answer is to not write at all; when the\n     * content genuinely changed, the write is atomic so a concurrent reader never sees a half-doc.\n     */\n    writeIfChanged(absPath: string, contents: string): boolean {\n        if (this.alreadyHolds(absPath, contents)) return false;\n        this.writeAtomic(absPath, contents);\n        return true;\n    }\n\n    // True when the file exists and its bytes already equal `contents`. Any read failure answers false\n    // (rewrite it) — \"cannot read the current content\" must never read as \"it is already correct\".\n    private alreadyHolds(absPath: string, contents: string): boolean {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (!fs.existsSync(absPath)) return false;\n            return fs.readFileSync(absPath, 'utf8') === contents;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return false;\n        }\n    }\n\n    // A sibling of the destination (same directory ⇒ same filesystem ⇒ the rename stays atomic), named\n    // so a crash leaves an obviously-temporary dotfile rather than something mistaken for real state.\n    private tempPathFor(absPath: string): string {\n        this.sequence += 1;\n        const stamp = `${String(process.pid)}-${String(Date.now())}-${String(this.sequence)}`;\n        return path.join(path.dirname(absPath), `.${path.basename(absPath)}.tmp-${stamp}`);\n    }\n\n    // Best-effort removal of an abandoned temp file. A failure here is not worth reporting over the\n    // original write failure that caused it.\n    private discard(tmpPath: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n}\n"]}

package/src/claude-config-dir.d.ts

@@ -0,0 +1,62 @@
+/**
+ * THE ONE PLACE THAT KNOWS WHERE CLAUDE CODE KEEPS ITS ON-DISK STATE.
+ *
+ * ─── WHY THIS FILE EXISTS ────────────────────────────────────────────────────────────────────────
+ * `~/.claude` is a DEFAULT, not the location. Claude Code relocates the whole tree when
+ * `$CLAUDE_CONFIG_DIR` is set, and three modules in this package read that tree: reviewer provenance
+ * (`subagent-provenance.ts`), the audit record (`review-provenance.ts`) and the worktree-reap veto
+ * (`harness-agent-activity.ts`). Only the third one resolved it correctly; the other two joined
+ * `os.homedir()` with a hardcoded `'.claude'`.
+ *
+ * The consequence was not a degraded answer, it was a HARD BLOCK with no user-side workaround: on a
+ * machine with `CLAUDE_CONFIG_DIR=~/.claude-work`, provenance found zero transcripts — not the
+ * reviewers', not even the main agent's — so `wp-finish-upsert-pr` refused every PR whose reviewers
+ * had genuinely run and genuinely passed, and the refusal blamed the reviewers' cwd. The audit record
+ * it wrote said `mainTranscript: ""`, which is the field that settles it: the main transcript is found
+ * by session id alone, with no cwd, branch or stamping involved, so an empty one can ONLY mean the
+ * lookup ROOT was wrong. Re-spawning cannot fix a wrong root, and the only escape was a symlink into
+ * `~/.claude` — i.e. hand-placing evidence inside a verification gate's own evidence tree.
+ *
+ * So the resolution lives here once, and the three modules call it. A second copy is how the first one
+ * got out of step.
+ *
+ * ─── WHY BOTH ROOTS ARE SEARCHED ─────────────────────────────────────────────────────────────────
+ * `$CLAUDE_CONFIG_DIR` is a property of the PROCESS, and the process that runs `wp-finish-upsert-pr`
+ * is not the process that wrote the transcripts. A shell launched before the variable was exported —
+ * or a hook, or a `pnpm` script whose env was sanitized — reads the transcripts of a session that had
+ * it set while itself having it unset, and vice versa. Resolving to exactly ONE root makes the check
+ * depend on env agreement between two unrelated processes, which is a fact nobody can verify and
+ * nobody can repair from inside the flow.
+ *
+ * Searching both is cheap (a `readdir` of a directory that usually does not exist) and it only ever
+ * ADDS candidate trees. It cannot weaken the integrity property either: every root yields the same
+ * harness-written `spawnDepth` / `isSidechain` / branch evidence, so a transcript found under the
+ * second root is no more forgeable than one found under the first.
+ *
+ * Shaped like {@link ClaudeEnv} in `claude-env.ts` — an injectable class plus one process-wide
+ * instance — because `no-function-outside-class` is on: module-scope helpers are not a shape this repo
+ * writes, whatever their arity.
+ */
+/** The env var Claude Code exports when its config tree has been relocated. */
+export declare const CLAUDE_CONFIG_DIR_ENV = "CLAUDE_CONFIG_DIR";
+export declare class ClaudeConfigDir {
+    /** The raw `$CLAUDE_CONFIG_DIR` value, or '' when it is not set. For DIAGNOSTICS, never for joining. */
+    configuredDir(): string;
+    /** Claude Code's config tree: `$CLAUDE_CONFIG_DIR` when set, else `~/.claude`. */
+    root(): string;
+    /**
+     * Every config tree worth searching: the configured one FIRST, then `~/.claude` when it is a
+     * different directory. See the both-roots note above for why this is a list and not one answer.
+     */
+    roots(): string[];
+    /**
+     * `<config>/projects` for every root {@link roots} names, in the same order — where per-project
+     * session state and transcripts live.
+     *
+     * There is deliberately NO singular `projectsRoot()` beside this. Searching exactly one root is
+     * precisely the defect #963 was, so an exported spelling that returns the one-root answer would make
+     * the broken thing the shorter thing to type, in the one file that exists to prevent it.
+     */
+    projectsRoots(): string[];
+}
+export declare const claudeConfigDir: ClaudeConfigDir;

package/src/claude-config-dir.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeConfigDir = exports.ClaudeConfigDir = exports.CLAUDE_CONFIG_DIR_ENV = void 0;
+const tslib_1 = require("tslib");
+const os = tslib_1.__importStar(require("os"));
+const path = tslib_1.__importStar(require("path"));
+const inversify_1 = require("inversify");
+/**
+ * THE ONE PLACE THAT KNOWS WHERE CLAUDE CODE KEEPS ITS ON-DISK STATE.
+ *
+ * ─── WHY THIS FILE EXISTS ────────────────────────────────────────────────────────────────────────
+ * `~/.claude` is a DEFAULT, not the location. Claude Code relocates the whole tree when
+ * `$CLAUDE_CONFIG_DIR` is set, and three modules in this package read that tree: reviewer provenance
+ * (`subagent-provenance.ts`), the audit record (`review-provenance.ts`) and the worktree-reap veto
+ * (`harness-agent-activity.ts`). Only the third one resolved it correctly; the other two joined
+ * `os.homedir()` with a hardcoded `'.claude'`.
+ *
+ * The consequence was not a degraded answer, it was a HARD BLOCK with no user-side workaround: on a
+ * machine with `CLAUDE_CONFIG_DIR=~/.claude-work`, provenance found zero transcripts — not the
+ * reviewers', not even the main agent's — so `wp-finish-upsert-pr` refused every PR whose reviewers
+ * had genuinely run and genuinely passed, and the refusal blamed the reviewers' cwd. The audit record
+ * it wrote said `mainTranscript: ""`, which is the field that settles it: the main transcript is found
+ * by session id alone, with no cwd, branch or stamping involved, so an empty one can ONLY mean the
+ * lookup ROOT was wrong. Re-spawning cannot fix a wrong root, and the only escape was a symlink into
+ * `~/.claude` — i.e. hand-placing evidence inside a verification gate's own evidence tree.
+ *
+ * So the resolution lives here once, and the three modules call it. A second copy is how the first one
+ * got out of step.
+ *
+ * ─── WHY BOTH ROOTS ARE SEARCHED ─────────────────────────────────────────────────────────────────
+ * `$CLAUDE_CONFIG_DIR` is a property of the PROCESS, and the process that runs `wp-finish-upsert-pr`
+ * is not the process that wrote the transcripts. A shell launched before the variable was exported —
+ * or a hook, or a `pnpm` script whose env was sanitized — reads the transcripts of a session that had
+ * it set while itself having it unset, and vice versa. Resolving to exactly ONE root makes the check
+ * depend on env agreement between two unrelated processes, which is a fact nobody can verify and
+ * nobody can repair from inside the flow.
+ *
+ * Searching both is cheap (a `readdir` of a directory that usually does not exist) and it only ever
+ * ADDS candidate trees. It cannot weaken the integrity property either: every root yields the same
+ * harness-written `spawnDepth` / `isSidechain` / branch evidence, so a transcript found under the
+ * second root is no more forgeable than one found under the first.
+ *
+ * Shaped like {@link ClaudeEnv} in `claude-env.ts` — an injectable class plus one process-wide
+ * instance — because `no-function-outside-class` is on: module-scope helpers are not a shape this repo
+ * writes, whatever their arity.
+ */
+/** The env var Claude Code exports when its config tree has been relocated. */
+exports.CLAUDE_CONFIG_DIR_ENV = 'CLAUDE_CONFIG_DIR';
+let ClaudeConfigDir = class ClaudeConfigDir {
+    /** The raw `$CLAUDE_CONFIG_DIR` value, or '' when it is not set. For DIAGNOSTICS, never for joining. */
+    configuredDir() {
+        return (process.env[exports.CLAUDE_CONFIG_DIR_ENV] ?? '').trim();
+    }
+    /** Claude Code's config tree: `$CLAUDE_CONFIG_DIR` when set, else `~/.claude`. */
+    root() {
+        const configured = this.configuredDir();
+        return configured !== '' ? configured : path.join(os.homedir(), '.claude');
+    }
+    /**
+     * Every config tree worth searching: the configured one FIRST, then `~/.claude` when it is a
+     * different directory. See the both-roots note above for why this is a list and not one answer.
+     */
+    roots() {
+        const configured = this.root();
+        const fallback = path.join(os.homedir(), '.claude');
+        return path.resolve(configured) === path.resolve(fallback) ? [configured] : [configured, fallback];
+    }
+    /**
+     * `<config>/projects` for every root {@link roots} names, in the same order — where per-project
+     * session state and transcripts live.
+     *
+     * There is deliberately NO singular `projectsRoot()` beside this. Searching exactly one root is
+     * precisely the defect #963 was, so an exported spelling that returns the one-root answer would make
+     * the broken thing the shorter thing to type, in the one file that exists to prevent it.
+     */
+    projectsRoots() {
+        return this.roots().map((root) => path.join(root, 'projects'));
+    }
+};
+exports.ClaudeConfigDir = ClaudeConfigDir;
+exports.ClaudeConfigDir = ClaudeConfigDir = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], ClaudeConfigDir);
+// Process-wide instance for the many non-DI call sites (hooks, wp-* bins); inversify still injects the
+// singleton wherever a container is in play. Same arrangement as `claudeEnv`.
+exports.claudeConfigDir = new ClaudeConfigDir();
+//# sourceMappingURL=claude-config-dir.js.map

package/src/claude-config-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-config-dir.js","sourceRoot":"","sources":["../../../../../packages/tooling/tooling-common/src/claude-config-dir.ts"],"names":[],"mappings":";;;;AAAA,+CAAyB;AACzB,mDAA6B;AAC7B,yCAA2D;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,+EAA+E;AAClE,QAAA,qBAAqB,GAAG,mBAAmB,CAAC;AAGlD,IAAM,eAAe,GAArB,MAAM,eAAe;IACxB,wGAAwG;IACxG,aAAa;QACT,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,6BAAqB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7D,CAAC;IAED,kFAAkF;IAClF,IAAI;QACA,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACxC,OAAO,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IAC/E,CAAC;IAED;;;OAGG;IACH,KAAK;QACD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACvG,CAAC;IAED;;;;;;;OAOG;IACH,aAAa;QACT,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IACnF,CAAC;CACJ,CAAA;AAjCY,0CAAe;0BAAf,eAAe;IAD3B,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;GAC5B,eAAe,CAiC3B;AAED,uGAAuG;AACvG,8EAA8E;AACjE,QAAA,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC","sourcesContent":["import * as os from 'os';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\n/**\n * THE ONE PLACE THAT KNOWS WHERE CLAUDE CODE KEEPS ITS ON-DISK STATE.\n *\n * ─── WHY THIS FILE EXISTS ────────────────────────────────────────────────────────────────────────\n * `~/.claude` is a DEFAULT, not the location. Claude Code relocates the whole tree when\n * `$CLAUDE_CONFIG_DIR` is set, and three modules in this package read that tree: reviewer provenance\n * (`subagent-provenance.ts`), the audit record (`review-provenance.ts`) and the worktree-reap veto\n * (`harness-agent-activity.ts`). Only the third one resolved it correctly; the other two joined\n * `os.homedir()` with a hardcoded `'.claude'`.\n *\n * The consequence was not a degraded answer, it was a HARD BLOCK with no user-side workaround: on a\n * machine with `CLAUDE_CONFIG_DIR=~/.claude-work`, provenance found zero transcripts — not the\n * reviewers', not even the main agent's — so `wp-finish-upsert-pr` refused every PR whose reviewers\n * had genuinely run and genuinely passed, and the refusal blamed the reviewers' cwd. The audit record\n * it wrote said `mainTranscript: \"\"`, which is the field that settles it: the main transcript is found\n * by session id alone, with no cwd, branch or stamping involved, so an empty one can ONLY mean the\n * lookup ROOT was wrong. Re-spawning cannot fix a wrong root, and the only escape was a symlink into\n * `~/.claude` — i.e. hand-placing evidence inside a verification gate's own evidence tree.\n *\n * So the resolution lives here once, and the three modules call it. A second copy is how the first one\n * got out of step.\n *\n * ─── WHY BOTH ROOTS ARE SEARCHED ─────────────────────────────────────────────────────────────────\n * `$CLAUDE_CONFIG_DIR` is a property of the PROCESS, and the process that runs `wp-finish-upsert-pr`\n * is not the process that wrote the transcripts. A shell launched before the variable was exported —\n * or a hook, or a `pnpm` script whose env was sanitized — reads the transcripts of a session that had\n * it set while itself having it unset, and vice versa. Resolving to exactly ONE root makes the check\n * depend on env agreement between two unrelated processes, which is a fact nobody can verify and\n * nobody can repair from inside the flow.\n *\n * Searching both is cheap (a `readdir` of a directory that usually does not exist) and it only ever\n * ADDS candidate trees. It cannot weaken the integrity property either: every root yields the same\n * harness-written `spawnDepth` / `isSidechain` / branch evidence, so a transcript found under the\n * second root is no more forgeable than one found under the first.\n *\n * Shaped like {@link ClaudeEnv} in `claude-env.ts` — an injectable class plus one process-wide\n * instance — because `no-function-outside-class` is on: module-scope helpers are not a shape this repo\n * writes, whatever their arity.\n */\n\n/** The env var Claude Code exports when its config tree has been relocated. */\nexport const CLAUDE_CONFIG_DIR_ENV = 'CLAUDE_CONFIG_DIR';\n\n@injectable(bindingScopeValues.Singleton)\nexport class ClaudeConfigDir {\n    /** The raw `$CLAUDE_CONFIG_DIR` value, or '' when it is not set. For DIAGNOSTICS, never for joining. */\n    configuredDir(): string {\n        return (process.env[CLAUDE_CONFIG_DIR_ENV] ?? '').trim();\n    }\n\n    /** Claude Code's config tree: `$CLAUDE_CONFIG_DIR` when set, else `~/.claude`. */\n    root(): string {\n        const configured = this.configuredDir();\n        return configured !== '' ? configured : path.join(os.homedir(), '.claude');\n    }\n\n    /**\n     * Every config tree worth searching: the configured one FIRST, then `~/.claude` when it is a\n     * different directory. See the both-roots note above for why this is a list and not one answer.\n     */\n    roots(): string[] {\n        const configured = this.root();\n        const fallback = path.join(os.homedir(), '.claude');\n        return path.resolve(configured) === path.resolve(fallback) ? [configured] : [configured, fallback];\n    }\n\n    /**\n     * `<config>/projects` for every root {@link roots} names, in the same order — where per-project\n     * session state and transcripts live.\n     *\n     * There is deliberately NO singular `projectsRoot()` beside this. Searching exactly one root is\n     * precisely the defect #963 was, so an exported spelling that returns the one-root answer would make\n     * the broken thing the shorter thing to type, in the one file that exists to prevent it.\n     */\n    projectsRoots(): string[] {\n        return this.roots().map((root: string): string => path.join(root, 'projects'));\n    }\n}\n\n// Process-wide instance for the many non-DI call sites (hooks, wp-* bins); inversify still injects the\n// singleton wherever a container is in play. Same arrangement as `claudeEnv`.\nexport const claudeConfigDir = new ClaudeConfigDir();\n"]}

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from './atomic-file';
+export * from './state-dir';
+export * from './state-dir-migration';
+export * from './inform-ai-error';
+export * from './claude-config-dir';
+export * from './state-path-constants';

package/src/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./atomic-file"), exports);
+tslib_1.__exportStar(require("./state-dir"), exports);
+tslib_1.__exportStar(require("./state-dir-migration"), exports);
+tslib_1.__exportStar(require("./inform-ai-error"), exports);
+tslib_1.__exportStar(require("./claude-config-dir"), exports);
+tslib_1.__exportStar(require("./state-path-constants"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/tooling-common/src/index.ts"],"names":[],"mappings":";;;AAAA,wDAA8B;AAC9B,sDAA4B;AAC5B,gEAAsC;AACtC,4DAAkC;AAClC,8DAAoC;AACpC,iEAAuC","sourcesContent":["export * from './atomic-file';\nexport * from './state-dir';\nexport * from './state-dir-migration';\nexport * from './inform-ai-error';\nexport * from './claude-config-dir';\nexport * from './state-path-constants';\n"]}

package/src/inform-ai-error.d.ts

@@ -0,0 +1,6 @@
+export declare class InformAiError extends Error {
+    cause?: Error;
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}

package/src/inform-ai-error.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InformAiError = void 0;
+class InformAiError extends Error {
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.name = 'InformAiError';
+        this.cause = options?.cause;
+    }
+}
+exports.InformAiError = InformAiError;
+//# sourceMappingURL=inform-ai-error.js.map

package/src/inform-ai-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inform-ai-error.js","sourceRoot":"","sources":["../../../../../packages/tooling/tooling-common/src/inform-ai-error.ts"],"names":[],"mappings":";;;AAAA,MAAa,aAAc,SAAQ,KAAK;IAC3B,KAAK,CAAS;IAEvB,YAAY,OAAe,EAAE,OAA2B;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;IAChC,CAAC;CACJ;AARD,sCAQC","sourcesContent":["export class InformAiError extends Error {\n    override cause?: Error;\n\n    constructor(message: string, options?: { cause?: Error }) {\n        super(message);\n        this.name = 'InformAiError';\n        this.cause = options?.cause;\n    }\n}\n"]}

package/src/state-dir-migration.d.ts

@@ -0,0 +1,79 @@
+/**
+ * What a migration did. Data-only (per CLAUDE.md: classes for data, explicit construction).
+ *
+ * `kept` is the important half: an entry that could NOT be moved because the destination already holds
+ * something at that path. Nothing in `kept` is ever deleted — it stays where it is, for a human.
+ */
+export declare class StateMigrationReport {
+    moved: string[];
+    kept: string[];
+    get movedAnything(): boolean;
+}
+/**
+ * Moves a LEGACY per-worktree `.webpieces/` REAL DIRECTORY into the worktree's namespace inside the
+ * primary clone (`<primary>/.webpieces/worktrees/<name>/`).
+ *
+ * NO SYMLINK IS EVER CREATED in its place — an earlier draft of this design planned one and this
+ * comment still said so, which is worse than silence: it told the reader to expect an indirection
+ * that does not exist. `DotWebpieces` resolves the namespace path EXPLICITLY (see its "Why two
+ * explicit methods and not a symlink" section, which records why the link was rejected: lazy creation
+ * with three failure modes, a Windows hazard, and `rename(2)` silently REPLACING the link). After a
+ * migration the legacy `<worktree>/.webpieces/` is simply gone; nothing takes its place.
+ *
+ * WHY it must exist: those directories hold REAL in-flight state — above all a half-finished 3-point
+ * merge under `merge-info/staged/<branch>/`. The first invocation under the new scheme must not orphan
+ * them; a merge an agent is standing in the middle of is not recoverable by re-running anything.
+ *
+ * WHAT IT MUST NOT TOUCH: the `keepInPlace` leaves — `pr-review/` today. Those are not legacy at all;
+ * `DotWebpieces.aiWritable()` resolves them to the worktree root ON PURPOSE, because that is the only
+ * directory a worktree-isolated coding agent is permitted to write into. Draining one would delete the
+ * live review directory out from under the agent writing it.
+ *
+ * WHY a plain move suffices: the destination namespace is created FOR this worktree, so it is empty in
+ * the ordinary case and the whole tree moves in one `rename`. Where something is already there (a
+ * repeat run, or an old PUBLISHED build having written to the legacy path again mid-transition), we
+ * descend and move only what is free.
+ *
+ * SAFETY RULE, absolute: this never deletes or overwrites anything that holds content. If a
+ * destination path is occupied, the legacy copy is LEFT WHERE IT IS and reported loudly on stderr.
+ * Empty directories are removed as they drain, which is how a fully-migrated legacy `.webpieces/`
+ * disappears on its own and lets the symlink be created.
+ *
+ * It is also the answer to the PUBLISHED-vs-LOCAL transition window. The `wp-*` bins and the hooks run
+ * the PUBLISHED package, so for a while some invocations still create a REAL `<worktree>/.webpieces`
+ * directory. Because this runs on the first state-dir resolution of EVERY new-code process, anything an
+ * old-code invocation deposited is swept into the worktree namespace before any reader looks — and a
+ * reader running old code finds it through the symlink either way. The two schemes converge instead of
+ * splitting; nothing is lost in either direction.
+ */
+export declare class StateDirMigrator {
+    /**
+     * Drain `legacyDir` into `targetDir`. A no-op when they are the same directory or when the legacy
+     * dir does not exist / is not a real directory (a symlink means migration already happened).
+     *
+     * `keepInPlace` names the TOP-LEVEL leaves of `legacyDir` that are NOT legacy — the ones
+     * `DotWebpieces.aiWritable()` deliberately resolves to the worktree's own root because a
+     * worktree-isolated coding agent cannot write anywhere else (today: `pr-review/`). Sweeping those
+     * into the namespace would move a live directory out from under the agent that is mid-way through
+     * writing it, so they are skipped and NOT reported as kept — nothing about them is unresolved.
+     */
+    migrate(legacyDir: string, targetDir: string, keepInPlace: readonly string[]): StateMigrationReport;
+    /**
+     * Move everything under `<legacyRoot>/<relative>` to `<targetRoot>/<relative>`.
+     *
+     * A whole subtree whose destination is free moves in ONE `rename` — which is what keeps an
+     * in-flight `merge-info/staged/<branch>/` intact rather than copying it file by file and risking a
+     * half-moved merge. Only when the destination is an existing DIRECTORY do we descend and consider
+     * its children individually.
+     *
+     * `keepInPlace` is consulted at the TOP LEVEL only (`relative === ''`), because that is the scope
+     * `DotWebpieces.aiWritable()` assigns: a whole leaf of `.webpieces/` either lives in the worktree or
+     * it does not. A nested `pr-review/` under some other home is ordinary legacy state.
+     */
+    private drain;
+    private relocate;
+    private isRealDirectory;
+    private removeIfEmpty;
+    private announce;
+    private warn;
+}