@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.1

package/pipeline/scripts/verify-citations.mjs

@@ -25,14 +25,34 @@
  *                       every one of them invented.
  *   --json              Machine-readable report
  *   --quiet             Exit code only
+ *   --state <path>      agent-state.json, for the unattended pre-existing check
+ *   --base <sha>        Base commit for that check. Default: state.baseline.sha,
+ *                       else the merge-base of HEAD with state.baseBranch
  *
  * Accepted shapes, detected rather than declared, so one script serves both
  * callers and neither has to say which it is:
  *   - reviewer output   `{findings: [{file, line, ...}]}`
- *   - triage output     `{accepted|deferred|rejected: [{file, line, ...}]}`
+ *   - triage output     `{accepted: [{file, line}], deferred|rejected: [{finding: {file, line}}]}`
  *   - analysis spec     `{evidence: {repoEvidence: {<repo>: {buckets: ...}}}}`
  *   - markdown          every `path/to/file.ext:123` in the prose
  *
+ * While the quality gates are active (lib/unattended.mjs, gatesActive:
+ * MULTI_AGENT_UNATTENDED=1 or a run in autopilot mode) the check goes further:
+ *
+ *   - the `finding` inside each deferred / rejected triage item is resolved too;
+ *   - a citation that carries a `quote` must match: after whitespace is
+ *     collapsed, the quote is contained in the cited line (a multi-line quote
+ *     in the lines starting there) and has at least QUOTE_MIN non-space
+ *     characters, or is the whole line. A line number with no quote only says
+ *     the line exists; the quote says what the reviewer read on it;
+ *   - every finding claimed pre-existing is checked against the base commit
+ *     (_pre-existing.mjs);
+ *   - the verdict is appended to state.gates[] as `verify-citations`
+ *     (gate-ledger.mjs), `not-applicable` when there was nothing to check.
+ *
+ * An attended run resolves `file:line` as it always did: flat findings only,
+ * quotes not read.
+ *
  * Exit codes:
  *   0   -  every citation resolved, or there were none to resolve
  *   1   -  at least one citation did not resolve
@@ -43,10 +63,12 @@
  */
 
 import { readFileSync, realpathSync, statSync } from "node:fs";
-import { resolve as resolvePath, sep } from "node:path";
+import { dirname, resolve as resolvePath, sep } from "node:path";
 import { spawnSync } from "node:child_process";
 import { runMain } from "../lib/fatal.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { checkPreExisting, resolveBase } from "./_pre-existing.mjs";
+import { gateContext, recordQuietly } from "./gate-ledger.mjs";
 
 /**
  * Reject a path before it reaches git.
@@ -145,14 +167,21 @@ export const SOURCE_EXTENSIONS = new Set([
 /**
  * Pull `{file, line}` pairs out of whatever was handed over.
  *
+ * `nested` reads the `finding` inside deferred / rejected triage items and
+ * `quotes` keeps each citation's `quote`; both are on by default. An attended
+ * run turns both off (see main), which keeps its verdicts where they were.
+ *
  * @param {string} raw
- * @returns {{file: string, line: number|null, where: string}[]}
+ * @param {{nested?: boolean, quotes?: boolean}} [opts]
+ * @returns {{file: string, line: number|null, where: string, quote?: string}[]}
  */
-export function extract(raw) {
+export function extract(raw, { nested = true, quotes = true } = {}) {
   const out = [];
-  const push = (file, line, where) => {
+  const push = (file, line, where, quote) => {
     if (typeof file === "string" && file.trim()) {
-      out.push({ file: file.trim(), line: Number.isFinite(line) ? line : null, where });
+      const c = { file: file.trim(), line: Number.isFinite(line) ? line : null, where };
+      if (quotes && typeof quote === "string" && quote.trim()) c.quote = quote;
+      out.push(c);
     }
   };
 
@@ -164,9 +193,13 @@ export function extract(raw) {
   }
 
   if (doc && typeof doc === "object") {
+    // Deferred and rejected triage items wrap the reviewer's finding as
+    // `{finding, reason}`; accepted items and reviewer findings are flat.
     for (const key of ["findings", "accepted", "deferred", "rejected"]) {
-      for (const [i, f] of (doc[key] || []).entries()) {
-        if (f && typeof f === "object") push(f.file, Number(f.line), `${key}[${i}]`);
+      for (const [i, item] of (Array.isArray(doc[key]) ? doc[key] : []).entries()) {
+        if (!item || typeof item !== "object") continue;
+        const f = nested && item.finding && typeof item.finding === "object" ? item.finding : item;
+        push(f.file, Number(f.line), `${key}[${i}]`, f.quote);
       }
     }
     const repoEvidence = doc?.evidence?.repoEvidence || doc?.analysisSpec?.evidence?.repoEvidence;
@@ -229,7 +262,7 @@ export function extract(raw) {
  * @param {string} repo
  * @param {string|null} rev
  * @param {{file: string, line: number|null}} c
- * @param {Map<string, number|null>} lineCache
+ * @param {Map<string, string[]|null>} lineCache
  * @returns {string|null} the reason it failed, or null
  */
 export function resolveOne(repo, rev, c, lineCache) {
@@ -240,22 +273,53 @@ export function resolveOne(repo, rev, c, lineCache) {
     lineCache.set(c.file, rev === null ? worktreeLines(repo, c.file) : revLines(repo, rev, c.file));
   }
 
-  const lines = lineCache.get(c.file);
+  const content = lineCache.get(c.file);
   const at = rev === null ? "in the working tree" : `at ${rev.slice(0, 12)}`;
-  if (lines === null) return `no such file ${at}`;
+  if (content === null) return `no such file ${at}`;
+  const lines = content.length;
   if (c.line === null) return null;
   if (c.line < 1) return `line ${c.line} is not a line number`;
   if (c.line > lines) return `line ${c.line} is past the end of the file (${lines} lines)`;
+  if (c.quote !== undefined && !quoteMatches(content, c.line, c.quote)) {
+    return `quote does not match line ${c.line} ${at}`;
+  }
   return null;
 }
 
+const collapse = (s) => String(s).replace(/\s+/g, " ").trim();
+
+/**
+ * Shortest quote that says what the line holds. A shorter one resolves only
+ * when it is the whole cited line: "e" is on most lines of any file.
+ */
+export const QUOTE_MIN = 8;
+
+/**
+ * True when the quote, whitespace collapsed, is inside the cited line - or,
+ * for a quote spanning N lines, inside lines line..line+N-1 joined - and has
+ * at least QUOTE_MIN non-space characters or is that whole text.
+ *
+ * @param {string[]} content  the file's lines
+ * @param {number} line  1-based
+ * @param {string} quote
+ * @returns {boolean}
+ */
+export function quoteMatches(content, line, quote) {
+  const span = String(quote).trim().split("\n").length;
+  const window = collapse(content.slice(line - 1, line - 1 + span).join("\n"));
+  const want = collapse(quote);
+  if (want === "") return true;
+  if (want.replace(/\s/g, "").length < QUOTE_MIN) return window === want;
+  return window.includes(want);
+}
+
 /**
- * Line count of a blob at a commit, or null when the path is not a file there.
+ * Lines of a blob at a commit, or null when the path is not a file there.
  *
  * @param {string} repo
  * @param {string} rev
  * @param {string} file
- * @returns {number|null}
+ * @returns {string[]|null}
  */
 function revLines(repo, rev, file) {
   const t = spawnSync("git", ["-C", repo, "cat-file", "-t", `${rev}:${file}`], {
@@ -266,11 +330,11 @@ function revLines(repo, rev, file) {
     encoding: "utf-8",
     maxBuffer: 64 * 1024 * 1024,
   });
-  return countLines(show.status === 0 ? show.stdout : "");
+  return splitLines(show.status === 0 ? show.stdout : "");
 }
 
 /**
- * Line count in the checkout, or null when there is no such file.
+ * Lines in the checkout, or null when there is no such file.
  *
  * `unsafePath` cannot see a symlink: `docs/out -> /etc` is a relative path with
  * no `..` in it, and git never followed it because git reads blobs rather than
@@ -279,7 +343,7 @@ function revLines(repo, rev, file) {
  *
  * @param {string} repo
  * @param {string} file
- * @returns {number|null}
+ * @returns {string[]|null}
  */
 function worktreeLines(repo, file) {
   let real;
@@ -293,29 +357,31 @@ function worktreeLines(repo, file) {
   if (real !== root && !real.startsWith(root + sep)) return null;
   try {
     if (!statSync(real).isFile()) return null;
-    return countLines(readFileSync(real, "utf-8"));
+    return splitLines(readFileSync(real, "utf-8"));
   } catch {
     return null;
   }
 }
 
 /**
- * A file with no trailing newline still has its last line.
+ * A file's lines. A file with no trailing newline still has its last line.
  *
  * @param {string} text
- * @returns {number}
+ * @returns {string[]}
  */
-function countLines(text) {
-  if (text.length === 0) return 0;
-  return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+function splitLines(text) {
+  if (text.length === 0) return [];
+  const lines = text.split("\n");
+  if (text.endsWith("\n")) lines.pop();
+  return lines;
 }
 
 /**
  * @param {object} params
  * @returns {{checked: number, unresolved: object[], rev: string}}
  */
-export function verify({ raw, repo, rev }) {
-  const citations = extract(raw);
+export function verify({ raw, repo, rev, gated = true }) {
+  const citations = extract(raw, { nested: gated, quotes: gated });
   const lineCache = new Map();
   const unresolved = [];
   for (const c of citations) {
@@ -325,7 +391,7 @@ export function verify({ raw, repo, rev }) {
   return { checked: citations.length, unresolved, rev };
 }
 
-const VALUE_FLAGS = new Set(["--repo", "--rev"]);
+const VALUE_FLAGS = new Set(["--repo", "--rev", "--state", "--base"]);
 
 /**
  * One pass, positionally. `argv.indexOf(a)` finds the FIRST occurrence of a
@@ -333,30 +399,27 @@ const VALUE_FLAGS = new Set(["--repo", "--rev"]);
  * target; walking the list is both simpler and correct.
  *
  * @param {string[]} argv
- * @returns {{target: string|null, repo: string|null, rev: string|null}}
+ * @returns {{target: string|null, repo: string|null, rev: string|null, state: string|null, base: string|null}}
  */
 export function parseArgs(argv) {
-  let target = null;
-  let repo = null;
-  let rev = null;
+  const v = { target: null, repo: null, rev: null, state: null, base: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (VALUE_FLAGS.has(a)) {
-      const v = argv[i + 1];
-      if (v !== undefined && !v.startsWith("--")) {
-        if (a === "--repo") repo = v;
-        else rev = v;
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        v[a.slice(2)] = next;
         i++;
       }
       continue;
     }
     if (a.startsWith("--")) continue;
-    if (target === null) target = a;
+    if (v.target === null) v.target = a;
   }
-  return { target, repo, rev };
+  return v;
 }
 
-function main() {
+async function main() {
   const argv = process.argv.slice(2);
   const parsed = parseArgs(argv);
   const target = parsed.target;
@@ -400,9 +463,51 @@ function main() {
     sha = head.stdout.trim();
   }
 
-  const report = verify({ raw, repo, rev: sha });
+  const ctx = gateContext({ statePath: parsed.state, repo });
+  const report = verify({ raw, repo, rev: sha, gated: ctx.active });
   const where = sha === null ? "in the working tree" : `at ${sha.slice(0, 12)}`;
 
+  if (ctx.active) {
+    let doc;
+    try {
+      doc = JSON.parse(raw);
+    } catch {
+      doc = null;
+    }
+    if (parsed.state && ctx.state === null) {
+      console.error(`verify-citations: cannot read ${parsed.state}`);
+      process.exit(2);
+    }
+    if (doc && typeof doc === "object") {
+      const base = resolveBase(repo, ctx.state, parsed.base);
+      report.preExisting = checkPreExisting({
+        doc,
+        repo,
+        rev: sha,
+        state: ctx.state,
+        base,
+        stateDir: ctx.statePath ? dirname(ctx.statePath) : null,
+      });
+    }
+  }
+  const preRejected = report.preExisting?.rejected.length ?? 0;
+  const failed = report.unresolved.length > 0 || preRejected > 0;
+  if (ctx.active) {
+    const nothing = report.checked === 0 && (report.preExisting?.claims ?? 0) === 0;
+    await recordQuietly(
+      "verify-citations",
+      failed ? "fail" : nothing ? "not-applicable" : "pass",
+      {
+        input: target === "-" ? "stdin" : target,
+        checked: report.checked,
+        unresolved: report.unresolved.length,
+        preExistingClaims: report.preExisting?.claims ?? 0,
+        preExistingRejected: preRejected,
+      },
+      { repo, statePath: ctx.statePath },
+    );
+  }
+
   if (json) {
     console.log(JSON.stringify(report, null, 2));
   } else if (!quiet) {
@@ -420,9 +525,17 @@ function main() {
       // is the moment someone is deciding what to do about it.
       console.log("  Re-search and correct the citation; never drop the line number to pass.");
     }
+    if (preRejected > 0) {
+      console.log(
+        `verify-citations: ${preRejected} pre-existing claim(s) not backed by the base commit:`,
+      );
+      for (const r of report.preExisting.rejected) {
+        console.log(`  ${r.where}: ${r.file}${r.line ? `:${r.line}` : ""} - ${r.reason}`);
+      }
+    }
   }
 
-  process.exit(report.unresolved.length === 0 ? 0 : 1);
+  process.exit(failed ? 1 : 0);
 }
 
 if (invokedDirectly(import.meta.url)) {

package/pipeline/scripts/verify.mjs

@@ -43,8 +43,54 @@ import { homedir } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { runMain } from "../lib/fatal.mjs";
+import { messages, outputLanguage } from "../lib/user-facing.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+// The human report renders in `prefs.global.outputLanguage`; `--json` is
+// untouched, because that half is parsed rather than read. Both languages sit
+// on one key so a wording change cannot land on only one of them.
+const REPORT = {
+  en: {
+    pkg: (version, commit, files, signature) =>
+      `package: ${version} (${commit}) - ${files} files, signature: ${signature}`,
+    unknownCommit: "commit unknown",
+    pkgClean: "  every file is as published",
+    changed: (f) => `  ! changed: ${f}`,
+    missing: (f) => `  ! missing: ${f}`,
+    more: (n) => `  ... and ${n} more files`,
+    installAbsent: (reason) => `install: ${reason}`,
+    installHeader: (trees, files) => `install: ~/.claude - ${trees} trees, ${files} files compared`,
+    presenceOnly: " (presence only: descriptions are translated at install time)",
+    treeDrift: (tree, changed, missing, how) =>
+      `  ${tree}: ${changed} differ, ${missing} missing${how}`,
+    neverWritten: (f) => `    ? ${f} (never written)`,
+    installClean: "  byte for byte with the source",
+    otherHosts: (hosts) =>
+      `  ${hosts} installed - their paths are rewritten at install time, so no byte comparison was made`,
+  },
+  tr: {
+    pkg: (version, commit, files, signature) =>
+      `paket: ${version} (${commit}) - ${files} dosya, imza: ${signature}`,
+    unknownCommit: "commit bilinmiyor",
+    pkgClean: "  butun dosyalar yayinlandigi gibi",
+    changed: (f) => `  ! degismis: ${f}`,
+    missing: (f) => `  ! eksik:    ${f}`,
+    more: (n) => `  ... ve ${n} dosya daha`,
+    installAbsent: (reason) => `kurulum: ${reason}`,
+    installHeader: (trees, files) =>
+      `kurulum: ~/.claude - ${trees} agac, ${files} dosya karsilastirildi`,
+    presenceOnly: " (yalnizca varlik: aciklamalar kurulumda cevriliyor)",
+    treeDrift: (tree, changed, missing, how) =>
+      `  ${tree}: ${changed} farkli, ${missing} eksik${how}`,
+    neverWritten: (f) => `    ? ${f} (hic yazilmamis)`,
+    installClean: "  kaynakla birebir ayni",
+    otherHosts: (hosts) =>
+      `  ${hosts} kurulu - yollari kurulumda yeniden yazildigi icin bayt karsilastirmasi yapilmadi`,
+  },
+};
+
+const say = messages(REPORT, outputLanguage());
 const MANIFEST = join(ROOT, "manifest.json");
 
 const argv = process.argv.slice(2);
@@ -255,44 +301,38 @@ async function main() {
   } else {
     if (pkg) {
       process.stdout.write(
-        `paket: ${pkg.version} (${pkg.commit?.slice(0, 12) ?? "commit bilinmiyor"}) - ${pkg.fileCount} dosya, imza: ${pkg.signature}\n`,
+        `${say.pkg(pkg.version, pkg.commit?.slice(0, 12) ?? say.unknownCommit, pkg.fileCount, pkg.signature)}\n`,
       );
-      if (!pkg.changed.length && !pkg.missing.length)
-        process.stdout.write("  butun dosyalar yayinlandigi gibi\n");
+      if (!pkg.changed.length && !pkg.missing.length) process.stdout.write(`${say.pkgClean}\n`);
       const SHOWN = 20;
-      for (const f of pkg.changed.slice(0, SHOWN)) process.stdout.write(`  ! degismis: ${f}\n`);
-      for (const f of pkg.missing.slice(0, SHOWN)) process.stdout.write(`  ! eksik:    ${f}\n`);
+      for (const f of pkg.changed.slice(0, SHOWN)) process.stdout.write(`${say.changed(f)}\n`);
+      for (const f of pkg.missing.slice(0, SHOWN)) process.stdout.write(`${say.missing(f)}\n`);
       // Counted per list against what was actually PRINTED. Subtracting a flat
       // 40 from the combined total spent a budget the lists had not used: with
       // 25 changed and 0 missing it printed 20, hid 5, and said nothing - a
       // tampered install under-reported by up to twenty files with no sign.
       const hidden =
         Math.max(0, pkg.changed.length - SHOWN) + Math.max(0, pkg.missing.length - SHOWN);
-      if (hidden > 0) process.stdout.write(`  ... ve ${hidden} dosya daha\n`);
+      if (hidden > 0) process.stdout.write(`${say.more(hidden)}\n`);
     }
     if (inst) {
-      if (!inst.present) process.stdout.write(`kurulum: ${inst.reason}\n`);
+      if (!inst.present) process.stdout.write(`${say.installAbsent(inst.reason)}\n`);
       else {
         const total = inst.trees.reduce((a, t) => a + t.files, 0);
-        process.stdout.write(
-          `kurulum: ~/.claude - ${inst.trees.length} agac, ${total} dosya karsilastirildi\n`,
-        );
+        process.stdout.write(`${say.installHeader(inst.trees.length, total)}\n`);
         for (const t of inst.trees) {
           if (!t.changed.length && !t.missing.length) continue;
-          const how =
-            t.mode === "presence" ? " (yalnizca varlik: aciklamalar kurulumda cevriliyor)" : "";
+          const how = t.mode === "presence" ? say.presenceOnly : "";
           process.stdout.write(
-            `  ${t.tree}: ${t.changed.length} farkli, ${t.missing.length} eksik${how}\n`,
+            `${say.treeDrift(t.tree, t.changed.length, t.missing.length, how)}\n`,
           );
           for (const f of [...t.changed.slice(0, 5)]) process.stdout.write(`    ! ${f}\n`);
           for (const f of [...t.missing.slice(0, 5)])
-            process.stdout.write(`    ? ${f} (hic yazilmamis)\n`);
+            process.stdout.write(`${say.neverWritten(f)}\n`);
         }
-        if (inst.ok) process.stdout.write("  kaynakla birebir ayni\n");
+        if (inst.ok) process.stdout.write(`${say.installClean}\n`);
         if (inst.otherHosts.length)
-          process.stdout.write(
-            `  ${inst.otherHosts.join(", ")} kurulu - yollari kurulumda yeniden yazildigi icin bayt karsilastirmasi yapilmadi\n`,
-          );
+          process.stdout.write(`${say.otherHosts(inst.otherHosts.join(", "))}\n`);
       }
     }
   }

package/pipeline/scripts/worktree-prepare.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+#
+# worktree-prepare.sh  -  create (or re-enter) one task worktree, healed and
+# excluded. Phase 0 Step 6b calls it once per repo; worktree-finalize.sh is its
+# counterpart at the other end of the run.
+#
+# In order, for one repo:
+#   1. heal stale admin state: a stale lock on the path is cleared and
+#      `worktree prune` drops entries whose directory is gone. A run killed
+#      mid-add leaves one behind, and the retry then fails with "already exists".
+#   2. the residue guard: lib/repo-hygiene.sh keeps .worktrees/, .pipeline/ and
+#      the loose logs out of the index through the clone-local exclude file.
+#   3. a path still registered and readable after the heal is entered and
+#      fast-forwarded, not re-added; paths are compared physically, so a path
+#      named through a symlink still matches its registration. Otherwise the
+#      worktree is added on <branch> when that branch already exists (a
+#      re-entered task keeps its commits), else `worktree add -b <branch>
+#      origin/<base>`.
+#   4. the identity, when given, is set on the worktree.
+#
+# One simple command per repo, so an unattended run can take this step under
+# the guard, which refuses shell control flow.
+#
+# Usage:
+#   worktree-prepare.sh --project <repo-root> --path <worktree> --branch <name>
+#                       --base <base-branch> [--name <git user.name>]
+#                       [--email <git user.email>]
+#
+# Output (stdout, JSON): {project, worktreePath, branch, baseBranch,
+#   action: created|reused|failed, pulled: true|false|null, error}
+#
+# Exit: 0 ready, 1 the add failed (nothing was created; the caller runs its
+#       rollback / collision flow), 2 usage.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT=""; WT=""; BRANCH=""; BASE=""; NAME=""; EMAIL=""
+
+usage() {
+  echo "usage: worktree-prepare.sh --project <repo-root> --path <worktree> --branch <name> --base <base-branch> [--name <n>] [--email <e>]" >&2
+  exit 2
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --project) [ "$#" -ge 2 ] || usage; PROJECT="$2"; shift 2 ;;
+    --path) [ "$#" -ge 2 ] || usage; WT="$2"; shift 2 ;;
+    --branch) [ "$#" -ge 2 ] || usage; BRANCH="$2"; shift 2 ;;
+    --base) [ "$#" -ge 2 ] || usage; BASE="$2"; shift 2 ;;
+    --name) [ "$#" -ge 2 ] || usage; NAME="$2"; shift 2 ;;
+    --email) [ "$#" -ge 2 ] || usage; EMAIL="$2"; shift 2 ;;
+    *) usage ;;
+  esac
+done
+[ -n "$PROJECT" ] && [ -n "$WT" ] && [ -n "$BRANCH" ] && [ -n "$BASE" ] || usage
+command -v jq >/dev/null 2>&1 || { echo "worktree-prepare: jq is required" >&2; exit 2; }
+git -C "$PROJECT" rev-parse --git-dir >/dev/null 2>&1 || {
+  echo "worktree-prepare: not a git repository: $PROJECT" >&2
+  exit 2
+}
+
+report() { # $1 action, $2 pulled (true|false|null), $3 error
+  jq -n --arg project "$PROJECT" --arg wt "$WT" --arg branch "$BRANCH" --arg base "$BASE" \
+    --arg action "$1" --argjson pulled "$2" --arg error "$3" \
+    '{project: $project, worktreePath: $wt, branch: $branch, baseBranch: $base,
+      action: $action, pulled: $pulled, error: (if $error == "" then null else $error end)}'
+}
+
+# Physical path of $1, for comparing paths that may go through a symlink.
+# A path that does not exist yet resolves through its nearest existing parent.
+canonical() {
+  local p="${1%/}" tail=""
+  [ -n "$p" ] || p="/"
+  while [ ! -d "$p" ]; do
+    tail="/$(basename "$p")$tail"
+    p=$(dirname "$p")
+  done
+  printf '%s%s\n' "$(cd -P "$p" 2>/dev/null && pwd -P)" "$tail"
+}
+
+registered() {
+  local want line
+  want=$(canonical "$WT")
+  while IFS= read -r line; do
+    case "$line" in
+      "worktree "*) [ "$(canonical "${line#worktree }")" = "$want" ] && return 0 ;;
+    esac
+  done < <(git -C "$PROJECT" worktree list --porcelain 2>/dev/null)
+  return 1
+}
+
+# Unlock before pruning: prune skips a locked entry, so a lock left by a killed
+# add would otherwise keep a missing directory registered.
+if registered; then
+  git -C "$PROJECT" worktree unlock "$WT" 2>/dev/null || true
+fi
+git -C "$PROJECT" worktree prune 2>/dev/null || true
+
+HYGIENE="$HERE/../lib/repo-hygiene.sh"
+[ -f "$HYGIENE" ] && bash "$HYGIENE" ensure "$PROJECT"
+
+set_identity() {
+  [ -n "$NAME" ] && git -C "$WT" config user.name "$NAME"
+  [ -n "$EMAIL" ] && git -C "$WT" config user.email "$EMAIL"
+  return 0
+}
+
+if registered && git -C "$WT" rev-parse --git-dir >/dev/null 2>&1; then
+  pulled=false
+  git -C "$WT" pull --ff-only -q >/dev/null 2>&1 && pulled=true
+  set_identity
+  report reused "$pulled" ""
+  exit 0
+fi
+
+if git -C "$PROJECT" show-ref --verify --quiet "refs/heads/$BRANCH"; then
+  add_args=("$WT" "$BRANCH")
+else
+  add_args=("$WT" -b "$BRANCH" "origin/$BASE")
+fi
+if ! err=$(git -C "$PROJECT" worktree add -q "${add_args[@]}" 2>&1); then
+  report failed null "$err"
+  exit 1
+fi
+set_identity
+report created null ""