@webpieces/tooling-common 0.0.1

package/src/state-dir.js

@@ -0,0 +1,349 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dotWebpieces = exports.DotWebpieces = exports.GitDirs = exports.AI_WRITABLE_STATE_DIRS = exports.LOGS_STATE_DIR = exports.WORKTREE_STATE_DIR = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const inversify_1 = require("inversify");
+const state_path_constants_1 = require("./state-path-constants");
+const state_dir_migration_1 = require("./state-dir-migration");
+// The per-worktree namespace inside the primary clone's `.webpieces/`. A LINKED worktree's local state
+// lives at `<primary>/.webpieces/worktrees/<worktreeName>/`; the primary clone keeps using
+// `<primary>/.webpieces/` directly, exactly as it always has.
+exports.WORKTREE_STATE_DIR = 'worktrees';
+// The ONE and ONLY directory webpieces writes observability state into — `<state>/logs/`, for the
+// primary clone and for each worktree namespace alike. There is no second state directory and no
+// split: the L1 binary's logs, the L0 sh shim's log, and the rejection DETAIL files (which are not
+// `.log`s but belong to the log that indexes them) are all here.
+//
+// It used to be two directories — `hooks/`, holding the binary's logs mixed in with dated
+// `hooks/<YYYY-MM-DD>/writeInfo-*.md` rejection details, and `logs/`, where the sh shim wrote — so
+// "where are the logs?" had two answers and neither was complete. `hooks/` is gone entirely; nothing
+// reads or writes it.
+//
+// Every writer resolves its DIRECTORY through dotWebpieces.logs()/logsFile(), so the layout cannot
+// drift apart again. What sits INSIDE it is ai-hook-rules' business (see its log-streams.ts and
+// LogStream): one directory per LAYER, and inside that one file per WRITER, named
+// <sessionId>-<agentId|coordinator>-<hook>.log — because Claude Code runs all matching PreToolUse
+// hooks IN PARALLEL and subagents/windows share a tree, so writers must never share a file.
+exports.LOGS_STATE_DIR = 'logs';
+// The leaves of `.webpieces/` that resolve through `aiWritable()` and therefore live in the WORKTREE's
+// own root rather than in the primary clone's namespace. Named here because TWO things must agree about
+// them: `aiWritable()`, which puts them there, and `StateDirMigrator`, which must NOT sweep them out
+// again (its whole job is draining `<worktree>/.webpieces` into the namespace, and these are the one
+// part of that directory that is live rather than legacy).
+exports.AI_WRITABLE_STATE_DIRS = [state_path_constants_1.PR_REVIEW_DIR];
+// git prints the shared git dir as `<primary>/.git` for a conventional clone. Anything else (a bare
+// repo, `--separate-git-dir`) is a layout we decline to derive a working tree from.
+const GIT_DIR_NAME = '.git';
+/**
+ * Data-only carrier for the two paths git is asked for. Per CLAUDE.md: classes for data.
+ *
+ * `gitDir` is the PER-WORKTREE git dir (`<primary>/.git/worktrees/<name>` in a linked worktree,
+ * `<primary>/.git` in the primary clone). `commonDir` is the SHARED one — always `<primary>/.git`.
+ * They differ if and only if this is a linked worktree; that is git's own canonical test.
+ */
+class GitDirs {
+    gitDir;
+    commonDir;
+    constructor(gitDir, commonDir) {
+        this.gitDir = gitDir;
+        this.commonDir = commonDir;
+    }
+    get isLinkedWorktree() {
+        return path.resolve(this.gitDir) !== path.resolve(this.commonDir);
+    }
+}
+exports.GitDirs = GitDirs;
+/**
+ * WHERE a piece of `.webpieces/` state belongs — the ONE resolver every reader and writer must go
+ * through, with THREE named methods because there are exactly three answers and a call site must DECLARE
+ * which one it means.
+ *
+ *   dotWebpieces.shared(dir)     → <primary>/.webpieces                    (repo-wide facts)
+ *   dotWebpieces.local(dir)      → <primary>/.webpieces/worktrees/<name>   (this worktree only, tooling-written)
+ *                                → <primary>/.webpieces                    (…in the primary clone)
+ *   dotWebpieces.aiWritable(dir) → <worktree>/.webpieces                   (this worktree only, AI-WRITTEN)
+ *                                → <primary>/.webpieces                    (…in the primary clone)
+ *
+ * ─── The bug ───────────────────────────────────────────────────────────────────────────────────────
+ * `.webpieces/` is gitignored, and it was anchored at the directory holding webpieces.config.json —
+ * which in a linked worktree is the WORKTREE. So a repo with seven worktrees had SEVEN independent
+ * copies of files that describe the WHOLE REPO. `merged-branches.json` holds verdicts for every branch
+ * AND every worktree in the repo; N copies is N divergent truths, and the guards read them as fact.
+ * Observed in the field: branch-creation-guard asserted "8 parked local branches" while
+ * `git branch --list` showed ONE — it was reading a cache written before deletions performed from a
+ * DIFFERENT worktree — and it then blocked a legitimate `git worktree add` on that fiction.
+ *
+ * ─── Why two explicit methods and not a symlink ────────────────────────────────────────────────────
+ * A `<worktree>/.webpieces` → `<primary>/…/worktrees/<name>` symlink would have left every call site
+ * untouched, which is seductive and wrong. Nothing hooks `git worktree add`, so the link needs LAZY
+ * creation that also has to handle "link already exists", "link points somewhere else", and "a real
+ * directory is already there" — invisible filesystem magic with a Windows failure mode. Worse, the safe
+ * way to write a shared file under concurrency is temp-file-then-`rename()`, and `rename(2)` acts on
+ * the PATH, not the link: it REPLACES a symlink with a real file. That silently works for one writer
+ * and diverges for everyone else — the exact bug being fixed, but invisible. An explicit call is
+ * greppable, testable, and forces each site to say which scope it means.
+ *
+ * ─── Which scope is which (the scope assignment is deliberate, not incidental) ─────────────────────
+ * shared():
+ *   • merged-branches.json — verdicts for every branch and worktree in the repo. Atomically written.
+ *   • main-sync-status.json AND main-sync.lock.json — there is one `main` and one `.git`, so there is
+ *     one refresher. A lock inside a per-worktree directory locks nothing.
+ * local():
+ *   • logs/*.log, INCLUDING branch-mutations.log. A shared append-only log genuinely corrupts:
+ *     `O_APPEND` writes are indivisible only under PIPE_BUF, which is 512 bytes on macOS, and a
+ *     `recover=git worktree add -b <branch> <abs-path> <tag>` line with real paths exceeds that. A
+ *     per-worktree log has exactly ONE writer and cannot tear, and under this layout it already
+ *     survives the worktree's deletion — recovery is one glob over
+ *     `<primary>/.webpieces/worktrees/＊/logs/branch-mutations.log`.
+ *   • merge-info/staged|merged/<branch>/ and its index.json, instruct-ai/, and every other per-tree
+ *     scratch file that the TOOLING writes.
+ * aiWritable():
+ *   • pr-review/<branch>/ — and ONLY that, today. See the section below.
+ *
+ * ─── Why aiWritable() is a third scope and not a spelling of local() ──────────────────────────────
+ * `pr-review/<branch>/` is the one state directory a CODING AGENT writes into with its own file-write
+ * tool: `summary.json` is authored by the agent running the flow, and `review-round<N>-<id>.json` by each reviewer
+ * subagent. A worktree-isolated agent may write ONLY inside its own worktree — its harness refuses any
+ * Write/Edit whose path is under the shared checkout, with "This agent is isolated in the worktree …;
+ * edit the worktree copy of this file instead". That refusal is not ours to relax.
+ *
+ * So `local()` — correct for everything the tooling writes — is UNREACHABLE for the two files the flow
+ * asks an agent to write. Stage ② printed a `<primary>/.webpieces/worktrees/<name>/pr-review/…` path,
+ * the agent's Write was refused at exactly that path, and the only way through was `cp`/`>` from Bash
+ * (which is NOT blocked, so the refusal looks arbitrary rather than structural). Three separate agents
+ * hit it, each concluded the tooling was printing a path it did not use, and each invented its own
+ * workaround. Worse, the same refusal lands on every reviewer subagent's `review-round<N>-<id>.json`, and
+ * `wp-finish-upsert-pr` REFUSES the PR while a required checklist has no verdict — so this was a
+ * correctness bug, not an ergonomics one.
+ *
+ * The invariant, stated once: ANY `.webpieces/` path an AI AGENT is instructed to WRITE must resolve
+ * inside that agent's own working tree. `aiWritable()` is that rule, made greppable. Do not add a
+ * fourth scope; do not route a tooling-written file through this one.
+ *
+ * What it costs is what `local()` bought: a `pr-review/` under the worktree dies with the worktree.
+ * That is the right trade for THIS directory and only this one — a review is spent the moment the PR is
+ * posted, and `pnpm wp-review-upsert-pr` regenerates the whole directory from git in one run. An
+ * in-flight `merge-info/staged/<branch>/` is not regenerable, which is exactly why it stays on local().
+ *
+ * ─── The boundary that must not be blurred ─────────────────────────────────────────────────────────
+ * ONLY the gitignored `.webpieces/` STATE relocates. `webpieces.config.json` is TRACKED IN GIT and is
+ * therefore part of the BRANCH: a branch may legitimately change its own rules and that must keep
+ * working. Config resolution is untouched — still per-worktree, via findConfigFile /
+ * RepoRootFinder.resolveRepoRoot. Nothing in this class reads or moves config.
+ *
+ * ─── Why `--git-dir` / `--git-common-dir`, and not one of the existing services ────────────────────
+ * They are git's own answers, from any subdirectory, in one cheap local call, with no `.git`-file
+ * parsing by hand (which gets `--separate-git-dir` and submodules wrong). Two existing mechanisms do
+ * distinguish primary from linked, and neither is the right authority here:
+ *   • `WorktreeService` answers "what worktrees exist and what do they hold" — a repo-wide ENUMERATION
+ *     (`git worktree list --porcelain`) for the caps and the reaper. Using it for a path lookup would
+ *     run an enumeration on the hook's blocking path for every state access, and it fails SOFT to `[]`,
+ *     which here would read as "there is no primary clone" on exactly the degraded repo where the
+ *     answer matters most. It also does not expose the worktree's git NAME, which is the namespace key.
+ *   • `EffectiveTreeResolver` (#524) answers "which tree does this COMMAND act on" — it takes a command
+ *     string and is a policy input to the bash guards, not a filesystem-path resolver.
+ * Both remain authoritative for their own questions. This asks the narrowest one — two path strings —
+ * and lives in rules-config, UNDER both, which is where a primitive that pr-gate, ai-hook-rules and
+ * code-rules all need has to sit.
+ *
+ * Fails CLOSED to the pre-change behaviour: when git cannot answer, every path here collapses to
+ * `<startDir-root>/.webpieces` exactly as before. Degrading to merely-suboptimal beats throwing on a
+ * hook's blocking path.
+ */
+let DotWebpieces = class DotWebpieces {
+    migrator;
+    // treeRoot → git's answer. One `git rev-parse` pair per root per process; every later path lookup
+    // in that invocation is a Map hit.
+    gitDirsByRoot = new Map();
+    // startDir → `git rev-parse --show-toplevel`, cached on the same terms as gitDirsByRoot.
+    treeRootByDir = new Map();
+    // Roots whose legacy per-worktree `.webpieces/` has already been considered for migration.
+    migrated = new Set();
+    constructor(migrator = new state_dir_migration_1.StateDirMigrator()) {
+        this.migrator = migrator;
+    }
+    /**
+     * REPO-WIDE state: `<primary>/.webpieces`. Use ONLY for facts about the repo rather than about one
+     * worktree — today that is merged-branches.json and the main-sync status + lock. Identical from
+     * every worktree, and never behind an indirection, so an atomic `rename()` into it is safe.
+     */
+    shared(startDir) {
+        return path.join(this.primaryRoot(startDir), state_path_constants_1.WEBPIECES_TMP_DIR);
+    }
+    /** A path beneath the repo-wide state dir. */
+    sharedFile(startDir, ...segments) {
+        return path.join(this.shared(startDir), ...segments);
+    }
+    /**
+     * THIS WORKTREE's private state: `<primary>/.webpieces/worktrees/<name>` for a linked worktree, and
+     * `<primary>/.webpieces` for the primary clone, which keeps its state exactly where it has always
+     * been. Fully isolated — two worktrees never write the same path, so nothing here needs a lock.
+     *
+     * The first call for a linked worktree also MIGRATES a legacy real `<worktree>/.webpieces/`
+     * directory into the namespace, so in-flight merge / pr-review state written under the old scheme
+     * (or by an older PUBLISHED build during the transition) is picked up rather than orphaned.
+     */
+    local(startDir) {
+        const dirs = this.gitDirs(startDir);
+        if (dirs === null || !dirs.isLinkedWorktree)
+            return this.shared(startDir);
+        const target = path.join(this.shared(startDir), exports.WORKTREE_STATE_DIR, path.basename(dirs.gitDir));
+        this.migrateOnce(startDir, target);
+        return target;
+    }
+    /** A path beneath this worktree's private state dir. */
+    localFile(startDir, ...segments) {
+        return path.join(this.local(startDir), ...segments);
+    }
+    /**
+     * State an AI AGENT writes with its own file-write tool: `<worktree>/.webpieces` — the worktree's
+     * OWN root, which is the only place a worktree-isolated agent is permitted to write. Identical to
+     * `shared()`/`local()` in the primary clone, so nothing changes for a repo without worktrees.
+     *
+     * See the "Why aiWritable() is a third scope" section above before adding a call site: this is for
+     * files the flow ASKS AN AGENT TO WRITE, not for tooling output that an agent merely reads.
+     */
+    aiWritable(startDir) {
+        const toplevel = this.treeRoot(startDir);
+        // Fails CLOSED to shared() when git cannot answer, on the same terms as every other path here.
+        if (toplevel === null)
+            return this.shared(startDir);
+        return path.join(toplevel, state_path_constants_1.WEBPIECES_TMP_DIR);
+    }
+    /** A path beneath the AI-writable state dir. */
+    aiWritableFile(startDir, ...segments) {
+        return path.join(this.aiWritable(startDir), ...segments);
+    }
+    /**
+     * THE log directory — `<local()>/logs` — and the only place webpieces writes a `.log` or a log's
+     * detail files, in the primary clone and in every worktree namespace alike.
+     *
+     * There is NO migration here, deliberately. A lazy once-per-process relocation of an older
+     * release's `hooks/*.log` used to run on this path, and it was itself the defect it claimed to
+     * cure: it only fires in the trees a process happens to re-enter, so it guarantees two answers to
+     * "where are the logs" indefinitely rather than converging on one. New writes go to `logs/` and
+     * nothing else; a stale `hooks/` left by an older release is inert and can be deleted by hand.
+     */
+    logs(startDir) {
+        return path.join(this.local(startDir), exports.LOGS_STATE_DIR);
+    }
+    /** A path beneath the log directory — `dotWebpieces.logsFile(root, CALLS_STREAM, writerFile)`. */
+    logsFile(startDir, ...segments) {
+        return path.join(this.logs(startDir), ...segments);
+    }
+    /** True when `startDir` sits in a LINKED worktree rather than the primary clone. */
+    isLinkedWorktree(startDir) {
+        const dirs = this.gitDirs(startDir);
+        return dirs !== null && dirs.isLinkedWorktree;
+    }
+    /**
+     * git's two dir answers for `startDir`, memoized — null when it is not a git repo / git is
+     * unavailable.
+     *
+     * PUBLIC because TREE IDENTITY is decided from these two strings and nothing else. `commonDir`
+     * is the same for every checkout of ONE repo, so `commonDir(a) === commonDir(b)` is "same repo,
+     * different placement" — the test that tells a linked worktree (ours, wherever it sits, including
+     * inside the repo at `.claude/worktrees/**`) from a nested clone under `repositories/**` (not
+     * ours). `gitDirs.isLinkedWorktree` then separates primary from linked. See
+     * `EffectiveTreeResolver.classify`, the caller that runs this on the hook's blocking path, which is
+     * why it goes through this cache rather than spawning its own `rev-parse`.
+     */
+    gitDirs(startDir) {
+        const cached = this.gitDirsByRoot.get(startDir);
+        if (cached !== undefined)
+            return cached;
+        const gitDir = this.revParse(startDir, '--git-dir');
+        const commonDir = this.revParse(startDir, '--git-common-dir');
+        const dirs = gitDir === null || commonDir === null ? null : new GitDirs(gitDir, commonDir);
+        this.gitDirsByRoot.set(startDir, dirs);
+        return dirs;
+    }
+    /**
+     * The WORKING TREE root containing `startDir` (`git rev-parse --show-toplevel`), memoized, or null
+     * when `startDir` is not in a git repo. In a linked worktree this is the WORKTREE's own root, which
+     * is exactly what a caller judging "which checkout am I standing in" needs.
+     *
+     * THE ONE tree-root resolver. There used to be three byte-identical `spawnSync … --show-toplevel`
+     * copies — this one, `RepoRootFinder`'s and `effective-tree.ts`'s — each commenting that it
+     * "mirrors" one of the others, and one of those comments was already stale. Both copies are deleted;
+     * everything that needs a tree root calls this. Do not add a fourth.
+     */
+    treeRoot(startDir) {
+        const cached = this.treeRootByDir.get(startDir);
+        if (cached !== undefined)
+            return cached;
+        // `status !== 0` IS the expected "not a repo" answer (spawnSync does not throw on a non-zero
+        // exit), so nothing here swallows a real git crash.
+        const root = this.revParse(startDir, '--show-toplevel');
+        this.treeRootByDir.set(startDir, root);
+        return root;
+    }
+    /**
+     * git's own name for this linked worktree — the basename of `<primary>/.git/worktrees/<name>`, and
+     * the namespace key under `worktrees/`. Empty for the primary clone. git's name rather than the
+     * directory's basename, so two worktrees checked out into same-named directories under different
+     * parents cannot collide.
+     */
+    worktreeName(startDir) {
+        const dirs = this.gitDirs(startDir);
+        if (dirs === null || !dirs.isLinkedWorktree)
+            return '';
+        return path.basename(dirs.gitDir);
+    }
+    /** The primary clone's root, from any worktree. Falls back to git's toplevel-less best guess. */
+    primaryRoot(startDir) {
+        const dirs = this.gitDirs(startDir);
+        if (dirs === null)
+            return startDir;
+        if (path.basename(dirs.commonDir) !== GIT_DIR_NAME)
+            return startDir;
+        const primary = path.dirname(dirs.commonDir);
+        return fs.existsSync(primary) ? primary : startDir;
+    }
+    /**
+     * The PRE-change location, `<treeRoot>/.webpieces` — what every call site used to compute. Public
+     * because the migrator and its specs must be able to name the thing being migrated FROM, and
+     * because the transition-window fallback readers need it.
+     */
+    legacyDir(treeRoot) {
+        return path.join(treeRoot, state_path_constants_1.WEBPIECES_TMP_DIR);
+    }
+    // Drain a legacy per-worktree `.webpieces/` into this worktree's namespace, at most once per tree
+    // per process. Migration is idempotent, but it touches the filesystem on the hook's blocking path.
+    migrateOnce(startDir, target) {
+        // Guard on the CHEAP key first. `local()` is called many times per invocation, and resolving the
+        // worktree toplevel costs a `git rev-parse` — doing that before the once-check would put a
+        // process spawn on the hook's blocking path for every single state-path lookup.
+        if (this.migrated.has(startDir))
+            return;
+        this.migrated.add(startDir);
+        const toplevel = this.treeRoot(startDir);
+        if (toplevel === null)
+            return;
+        this.migrator.migrate(this.legacyDir(toplevel), target, exports.AI_WRITABLE_STATE_DIRS);
+    }
+    // One `git rev-parse <flag>`, resolved to an absolute path (git prints a bare `.git`, relative to
+    // the tree, in the primary clone, and an absolute path from a linked worktree).
+    revParse(cwd, flag) {
+        const result = (0, child_process_1.spawnSync)('git', ['-C', cwd, 'rev-parse', flag], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return null;
+        const printed = (result.stdout ?? '').trim();
+        if (printed === '')
+            return null;
+        return path.resolve(cwd, printed);
+    }
+};
+exports.DotWebpieces = DotWebpieces;
+exports.DotWebpieces = DotWebpieces = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [state_dir_migration_1.StateDirMigrator])
+], DotWebpieces);
+// Process-wide instance for the many non-DI call sites (hooks, detached refreshers, wp-* bins, eslint
+// rules). Sharing one instance is what makes the git-resolution cache and the once-per-tree migration
+// worth having; inversify still injects the singleton wherever a container is in play.
+exports.dotWebpieces = new DotWebpieces();
+//# sourceMappingURL=state-dir.js.map

package/src/state-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-dir.js","sourceRoot":"","sources":["../../../../../packages/tooling/tooling-common/src/state-dir.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { PR_REVIEW_DIR, WEBPIECES_TMP_DIR } from './state-path-constants';\nimport { StateDirMigrator } from './state-dir-migration';\n\n// The per-worktree namespace inside the primary clone's `.webpieces/`. A LINKED worktree's local state\n// lives at `<primary>/.webpieces/worktrees/<worktreeName>/`; the primary clone keeps using\n// `<primary>/.webpieces/` directly, exactly as it always has.\nexport const WORKTREE_STATE_DIR = 'worktrees';\n\n// The ONE and ONLY directory webpieces writes observability state into — `<state>/logs/`, for the\n// primary clone and for each worktree namespace alike. There is no second state directory and no\n// split: the L1 binary's logs, the L0 sh shim's log, and the rejection DETAIL files (which are not\n// `.log`s but belong to the log that indexes them) are all here.\n//\n// It used to be two directories — `hooks/`, holding the binary's logs mixed in with dated\n// `hooks/<YYYY-MM-DD>/writeInfo-*.md` rejection details, and `logs/`, where the sh shim wrote — so\n// \"where are the logs?\" had two answers and neither was complete. `hooks/` is gone entirely; nothing\n// reads or writes it.\n//\n// Every writer resolves its DIRECTORY through dotWebpieces.logs()/logsFile(), so the layout cannot\n// drift apart again. What sits INSIDE it is ai-hook-rules' business (see its log-streams.ts and\n// LogStream): one directory per LAYER, and inside that one file per WRITER, named\n// <sessionId>-<agentId|coordinator>-<hook>.log — because Claude Code runs all matching PreToolUse\n// hooks IN PARALLEL and subagents/windows share a tree, so writers must never share a file.\nexport const LOGS_STATE_DIR = 'logs';\n\n// The leaves of `.webpieces/` that resolve through `aiWritable()` and therefore live in the WORKTREE's\n// own root rather than in the primary clone's namespace. Named here because TWO things must agree about\n// them: `aiWritable()`, which puts them there, and `StateDirMigrator`, which must NOT sweep them out\n// again (its whole job is draining `<worktree>/.webpieces` into the namespace, and these are the one\n// part of that directory that is live rather than legacy).\nexport const AI_WRITABLE_STATE_DIRS: readonly string[] = [PR_REVIEW_DIR];\n\n\n// git prints the shared git dir as `<primary>/.git` for a conventional clone. Anything else (a bare\n// repo, `--separate-git-dir`) is a layout we decline to derive a working tree from.\nconst GIT_DIR_NAME = '.git';\n\n/**\n * Data-only carrier for the two paths git is asked for. Per CLAUDE.md: classes for data.\n *\n * `gitDir` is the PER-WORKTREE git dir (`<primary>/.git/worktrees/<name>` in a linked worktree,\n * `<primary>/.git` in the primary clone). `commonDir` is the SHARED one — always `<primary>/.git`.\n * They differ if and only if this is a linked worktree; that is git's own canonical test.\n */\nexport class GitDirs {\n    readonly gitDir: string;\n    readonly commonDir: string;\n\n    constructor(gitDir: string, commonDir: string) {\n        this.gitDir = gitDir;\n        this.commonDir = commonDir;\n    }\n\n    get isLinkedWorktree(): boolean {\n        return path.resolve(this.gitDir) !== path.resolve(this.commonDir);\n    }\n}\n\n/**\n * WHERE a piece of `.webpieces/` state belongs — the ONE resolver every reader and writer must go\n * through, with THREE named methods because there are exactly three answers and a call site must DECLARE\n * which one it means.\n *\n *   dotWebpieces.shared(dir)     → <primary>/.webpieces                    (repo-wide facts)\n *   dotWebpieces.local(dir)      → <primary>/.webpieces/worktrees/<name>   (this worktree only, tooling-written)\n *                                → <primary>/.webpieces                    (…in the primary clone)\n *   dotWebpieces.aiWritable(dir) → <worktree>/.webpieces                   (this worktree only, AI-WRITTEN)\n *                                → <primary>/.webpieces                    (…in the primary clone)\n *\n * ─── The bug ───────────────────────────────────────────────────────────────────────────────────────\n * `.webpieces/` is gitignored, and it was anchored at the directory holding webpieces.config.json —\n * which in a linked worktree is the WORKTREE. So a repo with seven worktrees had SEVEN independent\n * copies of files that describe the WHOLE REPO. `merged-branches.json` holds verdicts for every branch\n * AND every worktree in the repo; N copies is N divergent truths, and the guards read them as fact.\n * Observed in the field: branch-creation-guard asserted \"8 parked local branches\" while\n * `git branch --list` showed ONE — it was reading a cache written before deletions performed from a\n * DIFFERENT worktree — and it then blocked a legitimate `git worktree add` on that fiction.\n *\n * ─── Why two explicit methods and not a symlink ────────────────────────────────────────────────────\n * A `<worktree>/.webpieces` → `<primary>/…/worktrees/<name>` symlink would have left every call site\n * untouched, which is seductive and wrong. Nothing hooks `git worktree add`, so the link needs LAZY\n * creation that also has to handle \"link already exists\", \"link points somewhere else\", and \"a real\n * directory is already there\" — invisible filesystem magic with a Windows failure mode. Worse, the safe\n * way to write a shared file under concurrency is temp-file-then-`rename()`, and `rename(2)` acts on\n * the PATH, not the link: it REPLACES a symlink with a real file. That silently works for one writer\n * and diverges for everyone else — the exact bug being fixed, but invisible. An explicit call is\n * greppable, testable, and forces each site to say which scope it means.\n *\n * ─── Which scope is which (the scope assignment is deliberate, not incidental) ─────────────────────\n * shared():\n *   • merged-branches.json — verdicts for every branch and worktree in the repo. Atomically written.\n *   • main-sync-status.json AND main-sync.lock.json — there is one `main` and one `.git`, so there is\n *     one refresher. A lock inside a per-worktree directory locks nothing.\n * local():\n *   • logs/*.log, INCLUDING branch-mutations.log. A shared append-only log genuinely corrupts:\n *     `O_APPEND` writes are indivisible only under PIPE_BUF, which is 512 bytes on macOS, and a\n *     `recover=git worktree add -b <branch> <abs-path> <tag>` line with real paths exceeds that. A\n *     per-worktree log has exactly ONE writer and cannot tear, and under this layout it already\n *     survives the worktree's deletion — recovery is one glob over\n *     `<primary>/.webpieces/worktrees/＊/logs/branch-mutations.log`.\n *   • merge-info/staged|merged/<branch>/ and its index.json, instruct-ai/, and every other per-tree\n *     scratch file that the TOOLING writes.\n * aiWritable():\n *   • pr-review/<branch>/ — and ONLY that, today. See the section below.\n *\n * ─── Why aiWritable() is a third scope and not a spelling of local() ──────────────────────────────\n * `pr-review/<branch>/` is the one state directory a CODING AGENT writes into with its own file-write\n * tool: `summary.json` is authored by the agent running the flow, and `review-round<N>-<id>.json` by each reviewer\n * subagent. A worktree-isolated agent may write ONLY inside its own worktree — its harness refuses any\n * Write/Edit whose path is under the shared checkout, with \"This agent is isolated in the worktree …;\n * edit the worktree copy of this file instead\". That refusal is not ours to relax.\n *\n * So `local()` — correct for everything the tooling writes — is UNREACHABLE for the two files the flow\n * asks an agent to write. Stage ② printed a `<primary>/.webpieces/worktrees/<name>/pr-review/…` path,\n * the agent's Write was refused at exactly that path, and the only way through was `cp`/`>` from Bash\n * (which is NOT blocked, so the refusal looks arbitrary rather than structural). Three separate agents\n * hit it, each concluded the tooling was printing a path it did not use, and each invented its own\n * workaround. Worse, the same refusal lands on every reviewer subagent's `review-round<N>-<id>.json`, and\n * `wp-finish-upsert-pr` REFUSES the PR while a required checklist has no verdict — so this was a\n * correctness bug, not an ergonomics one.\n *\n * The invariant, stated once: ANY `.webpieces/` path an AI AGENT is instructed to WRITE must resolve\n * inside that agent's own working tree. `aiWritable()` is that rule, made greppable. Do not add a\n * fourth scope; do not route a tooling-written file through this one.\n *\n * What it costs is what `local()` bought: a `pr-review/` under the worktree dies with the worktree.\n * That is the right trade for THIS directory and only this one — a review is spent the moment the PR is\n * posted, and `pnpm wp-review-upsert-pr` regenerates the whole directory from git in one run. An\n * in-flight `merge-info/staged/<branch>/` is not regenerable, which is exactly why it stays on local().\n *\n * ─── The boundary that must not be blurred ─────────────────────────────────────────────────────────\n * ONLY the gitignored `.webpieces/` STATE relocates. `webpieces.config.json` is TRACKED IN GIT and is\n * therefore part of the BRANCH: a branch may legitimately change its own rules and that must keep\n * working. Config resolution is untouched — still per-worktree, via findConfigFile /\n * RepoRootFinder.resolveRepoRoot. Nothing in this class reads or moves config.\n *\n * ─── Why `--git-dir` / `--git-common-dir`, and not one of the existing services ────────────────────\n * They are git's own answers, from any subdirectory, in one cheap local call, with no `.git`-file\n * parsing by hand (which gets `--separate-git-dir` and submodules wrong). Two existing mechanisms do\n * distinguish primary from linked, and neither is the right authority here:\n *   • `WorktreeService` answers \"what worktrees exist and what do they hold\" — a repo-wide ENUMERATION\n *     (`git worktree list --porcelain`) for the caps and the reaper. Using it for a path lookup would\n *     run an enumeration on the hook's blocking path for every state access, and it fails SOFT to `[]`,\n *     which here would read as \"there is no primary clone\" on exactly the degraded repo where the\n *     answer matters most. It also does not expose the worktree's git NAME, which is the namespace key.\n *   • `EffectiveTreeResolver` (#524) answers \"which tree does this COMMAND act on\" — it takes a command\n *     string and is a policy input to the bash guards, not a filesystem-path resolver.\n * Both remain authoritative for their own questions. This asks the narrowest one — two path strings —\n * and lives in rules-config, UNDER both, which is where a primitive that pr-gate, ai-hook-rules and\n * code-rules all need has to sit.\n *\n * Fails CLOSED to the pre-change behaviour: when git cannot answer, every path here collapses to\n * `<startDir-root>/.webpieces` exactly as before. Degrading to merely-suboptimal beats throwing on a\n * hook's blocking path.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class DotWebpieces {\n    // treeRoot → git's answer. One `git rev-parse` pair per root per process; every later path lookup\n    // in that invocation is a Map hit.\n    private readonly gitDirsByRoot = new Map<string, GitDirs | null>();\n    // startDir → `git rev-parse --show-toplevel`, cached on the same terms as gitDirsByRoot.\n    private readonly treeRootByDir = new Map<string, string | null>();\n    // Roots whose legacy per-worktree `.webpieces/` has already been considered for migration.\n    private readonly migrated = new Set<string>();\n\n    constructor(private readonly migrator: StateDirMigrator = new StateDirMigrator()) {}\n\n    /**\n     * REPO-WIDE state: `<primary>/.webpieces`. Use ONLY for facts about the repo rather than about one\n     * worktree — today that is merged-branches.json and the main-sync status + lock. Identical from\n     * every worktree, and never behind an indirection, so an atomic `rename()` into it is safe.\n     */\n    shared(startDir: string): string {\n        return path.join(this.primaryRoot(startDir), WEBPIECES_TMP_DIR);\n    }\n\n    /** A path beneath the repo-wide state dir. */\n    sharedFile(startDir: string, ...segments: string[]): string {\n        return path.join(this.shared(startDir), ...segments);\n    }\n\n    /**\n     * THIS WORKTREE's private state: `<primary>/.webpieces/worktrees/<name>` for a linked worktree, and\n     * `<primary>/.webpieces` for the primary clone, which keeps its state exactly where it has always\n     * been. Fully isolated — two worktrees never write the same path, so nothing here needs a lock.\n     *\n     * The first call for a linked worktree also MIGRATES a legacy real `<worktree>/.webpieces/`\n     * directory into the namespace, so in-flight merge / pr-review state written under the old scheme\n     * (or by an older PUBLISHED build during the transition) is picked up rather than orphaned.\n     */\n    local(startDir: string): string {\n        const dirs = this.gitDirs(startDir);\n        if (dirs === null || !dirs.isLinkedWorktree) return this.shared(startDir);\n\n        const target = path.join(this.shared(startDir), WORKTREE_STATE_DIR, path.basename(dirs.gitDir));\n        this.migrateOnce(startDir, target);\n        return target;\n    }\n\n    /** A path beneath this worktree's private state dir. */\n    localFile(startDir: string, ...segments: string[]): string {\n        return path.join(this.local(startDir), ...segments);\n    }\n\n    /**\n     * State an AI AGENT writes with its own file-write tool: `<worktree>/.webpieces` — the worktree's\n     * OWN root, which is the only place a worktree-isolated agent is permitted to write. Identical to\n     * `shared()`/`local()` in the primary clone, so nothing changes for a repo without worktrees.\n     *\n     * See the \"Why aiWritable() is a third scope\" section above before adding a call site: this is for\n     * files the flow ASKS AN AGENT TO WRITE, not for tooling output that an agent merely reads.\n     */\n    aiWritable(startDir: string): string {\n        const toplevel = this.treeRoot(startDir);\n        // Fails CLOSED to shared() when git cannot answer, on the same terms as every other path here.\n        if (toplevel === null) return this.shared(startDir);\n        return path.join(toplevel, WEBPIECES_TMP_DIR);\n    }\n\n    /** A path beneath the AI-writable state dir. */\n    aiWritableFile(startDir: string, ...segments: string[]): string {\n        return path.join(this.aiWritable(startDir), ...segments);\n    }\n\n    /**\n     * THE log directory — `<local()>/logs` — and the only place webpieces writes a `.log` or a log's\n     * detail files, in the primary clone and in every worktree namespace alike.\n     *\n     * There is NO migration here, deliberately. A lazy once-per-process relocation of an older\n     * release's `hooks/*.log` used to run on this path, and it was itself the defect it claimed to\n     * cure: it only fires in the trees a process happens to re-enter, so it guarantees two answers to\n     * \"where are the logs\" indefinitely rather than converging on one. New writes go to `logs/` and\n     * nothing else; a stale `hooks/` left by an older release is inert and can be deleted by hand.\n     */\n    logs(startDir: string): string {\n        return path.join(this.local(startDir), LOGS_STATE_DIR);\n    }\n\n    /** A path beneath the log directory — `dotWebpieces.logsFile(root, CALLS_STREAM, writerFile)`. */\n    logsFile(startDir: string, ...segments: string[]): string {\n        return path.join(this.logs(startDir), ...segments);\n    }\n\n    /** True when `startDir` sits in a LINKED worktree rather than the primary clone. */\n    isLinkedWorktree(startDir: string): boolean {\n        const dirs = this.gitDirs(startDir);\n        return dirs !== null && dirs.isLinkedWorktree;\n    }\n\n    /**\n     * git's two dir answers for `startDir`, memoized — null when it is not a git repo / git is\n     * unavailable.\n     *\n     * PUBLIC because TREE IDENTITY is decided from these two strings and nothing else. `commonDir`\n     * is the same for every checkout of ONE repo, so `commonDir(a) === commonDir(b)` is \"same repo,\n     * different placement\" — the test that tells a linked worktree (ours, wherever it sits, including\n     * inside the repo at `.claude/worktrees/**`) from a nested clone under `repositories/**` (not\n     * ours). `gitDirs.isLinkedWorktree` then separates primary from linked. See\n     * `EffectiveTreeResolver.classify`, the caller that runs this on the hook's blocking path, which is\n     * why it goes through this cache rather than spawning its own `rev-parse`.\n     */\n    gitDirs(startDir: string): GitDirs | null {\n        const cached = this.gitDirsByRoot.get(startDir);\n        if (cached !== undefined) return cached;\n\n        const gitDir = this.revParse(startDir, '--git-dir');\n        const commonDir = this.revParse(startDir, '--git-common-dir');\n        const dirs = gitDir === null || commonDir === null ? null : new GitDirs(gitDir, commonDir);\n        this.gitDirsByRoot.set(startDir, dirs);\n        return dirs;\n    }\n\n    /**\n     * The WORKING TREE root containing `startDir` (`git rev-parse --show-toplevel`), memoized, or null\n     * when `startDir` is not in a git repo. In a linked worktree this is the WORKTREE's own root, which\n     * is exactly what a caller judging \"which checkout am I standing in\" needs.\n     *\n     * THE ONE tree-root resolver. There used to be three byte-identical `spawnSync … --show-toplevel`\n     * copies — this one, `RepoRootFinder`'s and `effective-tree.ts`'s — each commenting that it\n     * \"mirrors\" one of the others, and one of those comments was already stale. Both copies are deleted;\n     * everything that needs a tree root calls this. Do not add a fourth.\n     */\n    treeRoot(startDir: string): string | null {\n        const cached = this.treeRootByDir.get(startDir);\n        if (cached !== undefined) return cached;\n        // `status !== 0` IS the expected \"not a repo\" answer (spawnSync does not throw on a non-zero\n        // exit), so nothing here swallows a real git crash.\n        const root = this.revParse(startDir, '--show-toplevel');\n        this.treeRootByDir.set(startDir, root);\n        return root;\n    }\n\n    /**\n     * git's own name for this linked worktree — the basename of `<primary>/.git/worktrees/<name>`, and\n     * the namespace key under `worktrees/`. Empty for the primary clone. git's name rather than the\n     * directory's basename, so two worktrees checked out into same-named directories under different\n     * parents cannot collide.\n     */\n    worktreeName(startDir: string): string {\n        const dirs = this.gitDirs(startDir);\n        if (dirs === null || !dirs.isLinkedWorktree) return '';\n        return path.basename(dirs.gitDir);\n    }\n\n    /** The primary clone's root, from any worktree. Falls back to git's toplevel-less best guess. */\n    primaryRoot(startDir: string): string {\n        const dirs = this.gitDirs(startDir);\n        if (dirs === null) return startDir;\n        if (path.basename(dirs.commonDir) !== GIT_DIR_NAME) return startDir;\n        const primary = path.dirname(dirs.commonDir);\n        return fs.existsSync(primary) ? primary : startDir;\n    }\n\n    /**\n     * The PRE-change location, `<treeRoot>/.webpieces` — what every call site used to compute. Public\n     * because the migrator and its specs must be able to name the thing being migrated FROM, and\n     * because the transition-window fallback readers need it.\n     */\n    legacyDir(treeRoot: string): string {\n        return path.join(treeRoot, WEBPIECES_TMP_DIR);\n    }\n\n    // Drain a legacy per-worktree `.webpieces/` into this worktree's namespace, at most once per tree\n    // per process. Migration is idempotent, but it touches the filesystem on the hook's blocking path.\n    private migrateOnce(startDir: string, target: string): void {\n        // Guard on the CHEAP key first. `local()` is called many times per invocation, and resolving the\n        // worktree toplevel costs a `git rev-parse` — doing that before the once-check would put a\n        // process spawn on the hook's blocking path for every single state-path lookup.\n        if (this.migrated.has(startDir)) return;\n        this.migrated.add(startDir);\n        const toplevel = this.treeRoot(startDir);\n        if (toplevel === null) return;\n        this.migrator.migrate(this.legacyDir(toplevel), target, AI_WRITABLE_STATE_DIRS);\n    }\n\n    // One `git rev-parse <flag>`, resolved to an absolute path (git prints a bare `.git`, relative to\n    // the tree, in the primary clone, and an absolute path from a linked worktree).\n    private revParse(cwd: string, flag: string): string | null {\n        const result = spawnSync('git', ['-C', cwd, 'rev-parse', flag], { encoding: 'utf8' });\n        if (result.status !== 0) return null;\n        const printed = (result.stdout ?? '').trim();\n        if (printed === '') return null;\n        return path.resolve(cwd, printed);\n    }\n}\n\n// Process-wide instance for the many non-DI call sites (hooks, detached refreshers, wp-* bins, eslint\n// rules). Sharing one instance is what makes the git-resolution cache and the once-per-tree migration\n// worth having; inversify still injects the singleton wherever a container is in play.\nexport const dotWebpieces = new DotWebpieces();\n"]}

package/src/state-path-constants.d.ts

@@ -0,0 +1,2 @@
+export declare const WEBPIECES_TMP_DIR = ".webpieces";
+export declare const PR_REVIEW_DIR = "pr-review";

package/src/state-path-constants.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PR_REVIEW_DIR = exports.WEBPIECES_TMP_DIR = void 0;
+exports.WEBPIECES_TMP_DIR = '.webpieces';
+exports.PR_REVIEW_DIR = 'pr-review';
+//# sourceMappingURL=state-path-constants.js.map

package/src/state-path-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-path-constants.js","sourceRoot":"","sources":["../../../../../packages/tooling/tooling-common/src/state-path-constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,iBAAiB,GAAG,YAAY,CAAC;AACjC,QAAA,aAAa,GAAG,WAAW,CAAC","sourcesContent":["export const WEBPIECES_TMP_DIR = '.webpieces';\nexport const PR_REVIEW_DIR = 'pr-review';\n"]}

package/src/to-error.d.ts

@@ -0,0 +1 @@
+export declare function toError(err: unknown): Error;

package/src/to-error.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toError = toError;
+// webpieces-disable no-any-unknown -- toError intentionally accepts unknown to safely convert any thrown value to Error
+function toError(err) {
+    if (err instanceof Error)
+        return err;
+    return new Error(String(err));
+}
+//# sourceMappingURL=to-error.js.map

package/src/to-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-error.js","sourceRoot":"","sources":["../../../../../packages/tooling/tooling-common/src/to-error.ts"],"names":[],"mappings":";;AACA,0BAGC;AAJD,wHAAwH;AACxH,SAAgB,OAAO,CAAC,GAAY;IAChC,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,GAAG,CAAC;IACrC,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAClC,CAAC","sourcesContent":["// webpieces-disable no-any-unknown -- toError intentionally accepts unknown to safely convert any thrown value to Error\nexport function toError(err: unknown): Error { // webpieces-disable no-function-outside-class -- existing stateless error adapter moved intact; this leaf must load without filesystem services\n    if (err instanceof Error) return err;\n    return new Error(String(err));\n}\n"]}