@brainervirus/workit-core 8.22.3 → 8.24.0

package/src/core/policy/substance.ts

@@ -0,0 +1,365 @@
+// Is a changed file cosmetic (#333, review finding mvkcoxgb)? Each side of
+// the file is reduced to its substance by a small lexer that knows the
+// file's strings and comments: comments drop out, whitespace outside strings
+// is normalized, strings stay verbatim. Equal substance on both sides is a
+// cosmetic change. The lexer fails closed: a syntax it does not know keeps
+// its comments, an indentation-sensitive or unknown type keeps all but
+// trailing whitespace, and anything it cannot read (invalid UTF-8, a NUL
+// byte, an unterminated string or comment, a regex across lines) is
+// substantive. Languages it would read wrongly stay unlexed (C-family, Rust,
+// SQL, shell, Ruby, YAML): only trailing whitespace is cosmetic there.
+
+type Syntax = {
+  /** Line comment openers. */
+  line: readonly string[];
+  /** Block comment delimiters (not nested). */
+  block: readonly (readonly [string, string])[];
+  /** String quotes with backslash escapes. */
+  quotes: string;
+  /** String quotes without escapes (TOML literal strings). */
+  literal?: string;
+  /** `"""` and `'''` strings. */
+  triple?: boolean;
+  /** JavaScript template literals with `${}` and regex literals. */
+  js?: boolean;
+  /** Go raw strings in backticks. */
+  rawBacktick?: boolean;
+  /** Strings may span lines. */
+  multiline?: boolean;
+  /** Python: an f-string with an unbalanced `{` holds a nested string this cannot read. */
+  fstring?: boolean;
+  /** CSS: an unquoted `url(` body is no string or comment this can read. */
+  cssUrl?: boolean;
+  /** Only trailing whitespace is cosmetic (indentation matters). */
+  indented?: boolean;
+};
+
+const SLASH_BLOCK = [["/*", "*/"]] as const;
+const C_LIKE: Syntax = { line: ["//"], block: SLASH_BLOCK, quotes: `"'` };
+const SYNTAXES: Record<string, Syntax> = Object.fromEntries([
+  // Not jsx or tsx: JSX text (`don't`, `</a>`) is no lexable string or regex.
+  ...["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => [ext, { ...C_LIKE, js: true }]),
+  ...["java", "kt", "kts", "scala", "swift", "dart", "groovy"].map((ext) => [
+    ext,
+    { ...C_LIKE, triple: true },
+  ]),
+  ["go", { ...C_LIKE, rawBacktick: true }],
+  ...["css", "scss", "less"].map((ext) => [
+    ext,
+    { line: [], block: SLASH_BLOCK, quotes: `"'`, cssUrl: true },
+  ]),
+  ...["py", "pyi"].map((ext) => [
+    ext,
+    { line: ["#"], block: [], quotes: `"'`, triple: true, indented: true, fstring: true },
+  ]),
+  ["toml", { line: ["#"], block: [], quotes: `"`, literal: "'", triple: true }],
+  ...["html", "htm", "xml", "svg", "xhtml"].map((ext) => [
+    ext,
+    // Text and <pre> whitespace can matter: only trailing whitespace is cosmetic.
+    { line: [], block: [["<!--", "-->"]], quotes: "", indented: true },
+  ]),
+]);
+
+/** Comments that steer a compiler, linter, bundler or runtime are code. */
+const DIRECTIVE =
+  /@ts-|eslint|prettier|biome|oxlint|istanbul|\bc8\b|\bv8\b|@jsx|@flow|@vite|webpack|__PURE__|__NO_SIDE_EFFECTS__|source(?:Mapping)?URL|^\/\s*<|go:|\+build|nolint|noqa|type:|pyright|mypy|pylint|pragma|coding[:=]|fmt:|NOSONAR|@license|@preserve|@refresh|environment|language=|cython|ruff|isort|deno-|@vitest|@jest|swiftlint|ktlint|checkstyle|suppress|nullable|#(?:end)?region/iu;
+
+const extensionOf = (file: string): string => {
+  const name = file.slice(file.lastIndexOf("/") + 1);
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+};
+
+/** CI and workflow definitions are read as written: their comments are never stripped. */
+const CI_PATH =
+  /^\.github\/|(?:^|\/)(?:\.gitlab-ci\.ya?ml|Jenkinsfile|azure-pipelines\.ya?ml|\.pre-commit-config\.ya?ml|\.circleci\/.*)$/u;
+
+/** The syntax `file` is lexed with; null keeps comments and all but trailing whitespace. */
+const syntaxOf = (file: string): Syntax | null =>
+  CI_PATH.test(file) ? null : (SYNTAXES[extensionOf(file)] ?? null);
+
+const SPACE = /[ \t\r\f\v]/u;
+const WORD = /[\w$]/u;
+const NO_SPACE_AFTER = "([{,;";
+const NO_SPACE_BEFORE = ")]},;";
+const REGEX_AFTER = "(,=:[!&|?{};+-*%<>~^";
+const REGEX_KEYWORDS = new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "case",
+  "do",
+  "else",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "throw",
+  "yield",
+  "await",
+]);
+
+type Frame = { kind: "code"; braces: number } | { kind: "template" };
+
+/**
+ * The substance of `text` for `file`: what stays after comments and
+ * insignificant whitespace are removed. Null when it cannot be read with
+ * certainty (the caller then counts the file as a behavior change).
+ */
+export function substanceOf(file: string, text: string): string | null {
+  const syntax = syntaxOf(file);
+  if (!syntax) return plainSubstance(text);
+  const markup = syntax.block.some(([open]) => open === "<!--");
+  // Markup with scripts, styles, CDATA or processing instructions holds
+  // other languages; a comment opener after anything but a tag end may sit
+  // in an attribute value.
+  if (
+    markup &&
+    (/<(?:script|style)\b|<!\[CDATA\[|<\?/iu.test(text) || /[^>\s][ \t]*<!--/u.test(text))
+  )
+    return plainSubstance(text);
+  return lex(syntax, text);
+}
+
+/** No lexer: only trailing whitespace and blank lines are cosmetic. */
+function plainSubstance(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => line.replace(/[ \t\r\f\v]+$/u, ""))
+    .filter(Boolean)
+    .join("\n");
+}
+
+function lex(syntax: Syntax, text: string): string | null {
+  const collapse = !syntax.indented;
+  let out = "";
+  let lineStart = 0;
+  /** Output before this index is string content: trailing-space trimming stops there. */
+  let kept = 0;
+  let pendingSpace = false;
+  const frames: Frame[] = [{ kind: "code", braces: 0 }];
+  let index = 0;
+
+  // A shebang line is code, read as written.
+  if (text.startsWith("#!")) {
+    const end = text.indexOf("\n");
+    out = end < 0 ? text : text.slice(0, end);
+    kept = out.length;
+    index = end < 0 ? text.length : end;
+  }
+
+  const emitCode = (chunk: string) => {
+    if (collapse && pendingSpace && out.length > lineStart) {
+      const before = out[out.length - 1];
+      if (!NO_SPACE_AFTER.includes(before) && !NO_SPACE_BEFORE.includes(chunk[0])) out += " ";
+    }
+    pendingSpace = false;
+    out += chunk;
+  };
+  const emitVerbatim = (chunk: string) => {
+    emitCode(chunk);
+    kept = out.length;
+  };
+  const newline = () => {
+    if (!collapse) {
+      let end = out.length;
+      while (end > Math.max(lineStart, kept) && SPACE.test(out[end - 1])) end -= 1;
+      out = out.slice(0, end);
+    }
+    pendingSpace = false;
+    if (out.length > lineStart) {
+      out += "\n";
+      lineStart = out.length;
+    }
+  };
+  /** Can a `/` start a regex here? After an operator or a keyword, not after a value. */
+  const regexAllowed = (): boolean => {
+    let end = out.length;
+    while (end > 0 && /\s/u.test(out[end - 1])) end -= 1;
+    if (end === 0 || REGEX_AFTER.includes(out[end - 1])) return true;
+    let start = end;
+    while (start > 0 && WORD.test(out[start - 1])) start -= 1;
+    return REGEX_KEYWORDS.has(out.slice(start, end));
+  };
+  /** Scan a quoted string from `index`; returns false when it does not close. */
+  const scanString = (quote: string, escapes: boolean, multiline: boolean): boolean => {
+    const prefix = text.slice(Math.max(0, index - 2), index).match(/[a-z]*$/iu)?.[0] ?? "";
+    const fstring = syntax.fstring === true && /f/iu.test(prefix);
+    let end = index + quote.length;
+    while (end < text.length) {
+      const char = text[end];
+      if (escapes && char === "\\") {
+        end += 2;
+        continue;
+      }
+      if (text.startsWith(quote, end)) {
+        if (fstring && unbalanced(text.slice(index + quote.length, end))) return false;
+        emitVerbatim(text.slice(index, end + quote.length));
+        index = end + quote.length;
+        return true;
+      }
+      if (char === "\n" && !multiline) return false;
+      end += 1;
+    }
+    return false;
+  };
+
+  while (index < text.length) {
+    const frame = frames[frames.length - 1];
+    const char = text[index];
+    if (frame.kind === "template") {
+      if (char === "\\") {
+        emitVerbatim(text.slice(index, index + 2));
+        index += 2;
+      } else if (char === "`") {
+        emitVerbatim(char);
+        frames.pop();
+        index += 1;
+      } else if (text.startsWith("${", index)) {
+        emitVerbatim("${");
+        frames.push({ kind: "code", braces: 0 });
+        index += 2;
+      } else {
+        // Template text, newlines included, is the string's value.
+        out += char;
+        kept = out.length;
+        index += 1;
+      }
+      continue;
+    }
+    if (char === "\n") {
+      newline();
+      index += 1;
+      continue;
+    }
+    if (SPACE.test(char)) {
+      if (collapse) pendingSpace = true;
+      else out += char;
+      index += 1;
+      continue;
+    }
+    const lineOpener = syntax.line.find((opener) => text.startsWith(opener, index));
+    if (lineOpener) {
+      const end = text.indexOf("\n", index);
+      const comment = text.slice(index, end < 0 ? text.length : end);
+      if (DIRECTIVE.test(comment.slice(lineOpener.length))) emitVerbatim(comment);
+      else pendingSpace = true;
+      index = end < 0 ? text.length : end;
+      continue;
+    }
+    const block = syntax.block.find(([open]) => text.startsWith(open, index));
+    if (block) {
+      const end = text.indexOf(block[1], index + block[0].length);
+      if (end < 0) return null;
+      const comment = text.slice(index, end + block[1].length);
+      if (DIRECTIVE.test(comment.slice(block[0].length, -block[1].length))) emitVerbatim(comment);
+      else pendingSpace = true;
+      // A newline inside the comment still ends the code line before it.
+      if (comment.includes("\n")) newline();
+      index = end + block[1].length;
+      continue;
+    }
+    if (syntax.triple && (char === '"' || char === "'") && text.startsWith(char.repeat(3), index)) {
+      if (!scanString(char.repeat(3), !syntax.literal?.includes(char), true)) return null;
+      continue;
+    }
+    if (syntax.quotes.includes(char)) {
+      if (!scanString(char, true, Boolean(syntax.multiline))) return null;
+      continue;
+    }
+    if (syntax.literal?.includes(char)) {
+      if (!scanString(char, false, false)) return null;
+      continue;
+    }
+    if (syntax.rawBacktick && char === "`") {
+      if (!scanString("`", false, true)) return null;
+      continue;
+    }
+    if (syntax.js && char === "`") {
+      emitVerbatim(char);
+      frames.push({ kind: "template" });
+      index += 1;
+      continue;
+    }
+    if (syntax.cssUrl && /^url\(\s*[^"')\s]/iu.test(text.slice(index, index + 64))) return null;
+    if (syntax.js && char === "/" && !regexAllowed() && out.trimEnd().endsWith(")")) {
+      // Division after `)` may be a regex after `if (x)`: with another `/` on
+      // the line the two readings differ on what is code, so give up.
+      const lineEnd = text.indexOf("\n", index);
+      if (text.slice(index + 1, lineEnd < 0 ? text.length : lineEnd).includes("/")) return null;
+    }
+    if (syntax.js && char === "/" && regexAllowed()) {
+      let end = index + 1;
+      let inClass = false;
+      while (end < text.length && (inClass || text[end] !== "/")) {
+        if (text[end] === "\n") return null;
+        if (text[end] === "\\") end += 1;
+        else if (text[end] === "[") inClass = true;
+        else if (text[end] === "]") inClass = false;
+        end += 1;
+      }
+      if (end >= text.length) return null;
+      emitVerbatim(text.slice(index, end + 1));
+      index = end + 1;
+      continue;
+    }
+    if (frames.length > 1 && frame.kind === "code") {
+      if (char === "{") frame.braces += 1;
+      else if (char === "}") {
+        if (frame.braces === 0) {
+          emitVerbatim(char);
+          frames.pop();
+          index += 1;
+          continue;
+        }
+        frame.braces -= 1;
+      }
+    }
+    emitCode(char);
+    index += 1;
+  }
+  if (frames.length !== 1) return null;
+  newline();
+  return out;
+}
+
+/** Does an f-string body hold a `{` that never closes, once `{{` and `}}` are set aside? */
+function unbalanced(body: string): boolean {
+  let depth = 0;
+  for (const part of body.replaceAll("{{", "").replaceAll("}}", "")) {
+    if (part === "{") depth += 1;
+    else if (part === "}") depth = Math.max(0, depth - 1);
+  }
+  return depth > 0;
+}
+
+/**
+ * A lone CR (not followed by LF), U+2028 or U+2029: some readers end a line
+ * there and others do not, so a comment can hide code from one of them.
+ */
+export function hasOpaqueLineBreak(text: string): boolean {
+  return /\r(?!\n)|[\u2028\u2029]/u.test(text);
+}
+
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** The UTF-8 text of `bytes`, or null for binary (a NUL byte) or invalid UTF-8. */
+export function textOf(bytes: Uint8Array): string | null {
+  if (bytes.includes(0)) return null;
+  try {
+    return decoder.decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/** Is the change from `before` to `after` of `file` cosmetic (equal substance)? */
+export function cosmeticChange(file: string, before: Uint8Array, after: Uint8Array): boolean {
+  const left = textOf(before);
+  const right = textOf(after);
+  if (left === null || right === null) return false;
+  if (hasOpaqueLineBreak(left) || hasOpaqueLineBreak(right)) return false;
+  const a = substanceOf(file, left);
+  return a !== null && a === substanceOf(file, right);
+}

package/src/core/workspaces.ts

@@ -142,7 +142,7 @@ const workspaceConfigSchema = z
      */
     defaultEndpoint: z.unknown().optional(),
     /** How a normal-risk behavior change is verified (S17); same rules as grants. */
-    verification: z.enum(["self", "independent"]).optional(),
+    verification: z.enum(["proportional", "self", "independent"]).optional(),
     /**
      * Who does the work (skills and `fanout plan` read it): `inline-first`
      * (default) keeps the lead working itself and refuses a slice without a

package/src/fanout-brief.ts

@@ -8,9 +8,12 @@
 // `<worktree>+try<n>` and session `<lead>-w-<slice>+try<n>`: slice ids cannot
 // contain `+`, so no attempt collides with another slice's path or session.
 // The lead's host (WORKIT_HOST, or its own session variable) picks the identity
-// and git rules: Claude Code workers use the WORKIT_SESSION_ID in their env (the lead's: SubagentStart issues ids only to judges) and plain
-// git; OpenCode, Pi and Codex workers export nothing (the host derives the id);
-// Cursor, CI and plain terminals export `<lead>-w-<slice>`.
+// rules: Claude Code workers use the WORKIT_SESSION_ID in their env (the
+// lead's: SubagentStart issues ids only to judges); OpenCode, Pi and Codex
+// workers export nothing (the host derives the id);
+// Cursor, CI and plain terminals export `<lead>-w-<slice>`. Once
+// `workit fanout worktree create` made the slice's worktree, WORKTREE and the
+// RULES name it: every git and check command runs as `workit --cwd <worktree> …`.
 // The lead must have a WORKIT_SESSION_ID: worker ids derive from it. A
 // worker id longer than the ledger's 128 characters hashes its slice part. The fan-in line follows the plan's `fanIn`:
 // one PR per slice forbids every merge; integration mode has the worker merge
@@ -64,8 +67,7 @@ const REPORT = [
  * docs/agents/hosts.md):
  *   - `issued`: Claude Code. SubagentStart issues ids only to verifiers and
  *     reviewers, so an implementer keeps the lead's WORKIT_SESSION_ID from its
- *     env; worktree isolation refuses every `workit git` form, so it uses
- *     plain git and never mints an id;
+ *     env and never mints an id;
  *   - `derived`: OpenCode, Pi, Codex. The worker's shell carries the host's own
  *     session id, which exporting WORKIT_SESSION_ID cannot replace;
  *   - `declared`: Cursor, CI, a plain terminal. Nothing vouches for an id, so
@@ -83,7 +85,7 @@ const identityOf = (host: string | null): BriefIdentity => {
 const identityLines = (identity: BriefIdentity, session: string): string[] => {
   if (identity === "issued")
     return [
-      "  Session: your env already has WORKIT_SESSION_ID (the lead's id; SubagentStart issues ids only to verifiers and reviewers). Use it as is, in your Workit-Session trailer and workit commands; never export or hand-mint one.",
+      "  Session: your env already has WORKIT_SESSION_ID (the lead's id; SubagentStart issues ids only to verifiers and reviewers). Use it as is: workit commands read it and `workit git commit` adds the Workit-Session trailer; never export or hand-mint one.",
     ];
   if (identity === "derived")
     return [
@@ -92,25 +94,28 @@ const identityLines = (identity: BriefIdentity, session: string): string[] => {
   return [`  export WORKIT_SESSION_ID=${session}`];
 };
 
+/**
+ * RULES. With the slice's worktree made (`worktree`), every git and check
+ * command names it (`workit --cwd <worktree> …`, one verb per call) and it is
+ * already on the branch; Workit's hooks keep an implementer inside it (#310).
+ */
 const rules = (
-  identity: BriefIdentity,
   mode: BriefMode,
   branch: string,
   base: string,
+  worktree: string | null,
 ): string[] => {
-  const plain = identity === "issued";
+  const workit = worktree ? `workit --cwd ${worktree}` : "workit";
   let first = `  1. First command: \`workit git branch ${branch} --base ${base}\` (your worktree may start on another name).`;
-  if (mode === "resume")
+  if (worktree)
+    first = `  1. Work only in WORKTREE, already on ${branch}${mode === "resume" ? " at its head" : ""}: edit files under it and run each git and check command against it, one verb per call (\`${workit} git commit …\`, \`${workit} check <name>\`), never \`cd … &&\` chains or \`$VAR\` paths. An implementer's change outside it is denied.`;
+  else if (mode === "resume")
     first = `  1. First command: \`git switch ${branch}\`, then continue from its head.`;
-  else if (plain)
-    first = `  1. First command: \`git fetch origin && git switch -c ${branch} origin/${base}\` (plain git: worktree isolation refuses every \`workit git\` form).`;
   return [
     "RULES:",
     first,
     '  2. Decide ambiguities yourself: `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`; stop only for an irreversible, security-sensitive or out-of-worktree action.',
-    plain
-      ? '  3. Commit with plain `git commit -m <msg> --trailer "Workit-Session: <the WORKIT_SESSION_ID in your env>" --trailer "<your host attribution trailer>" -- <paths in SCOPE>`; push only if this brief says so.'
-      : "  3. Commit with `workit git commit -m <msg> -- <paths in SCOPE>`; push only if this brief says so.",
+    `  3. Commit with \`${workit} git commit -m <msg> -- <paths in SCOPE>\`; push only if this brief says so.`,
     "  4. Never record a verdict on your own work.",
     "  5. Run tests, lint, typecheck and builds only through `workit check` (a named check, or `workit check --heavy -- <cmd>`): one machine-wide lease queues every agent, so never a hand-made flock; `workit lock status` shows who holds it.",
     "  6. A failed review gets one fix round and one recheck. Still failing: stop and report the open finding, never a third round (the lead spawns a decider). A product choice is the user's: report it, do not decide it.",
@@ -226,8 +231,11 @@ export function renderBrief(
     ...(standing.length
       ? standing.map((order) => `  - ${order.what}`)
       : ["  - none recorded beyond this brief"]),
+    exists
+      ? `WORKTREE: ${planned}  (made by \`workit fanout worktree create ${slice.id}\`; yours alone)`
+      : `WORKTREE: ${planned}  (not made yet: the lead runs \`workit fanout worktree create ${slice.id}\` before spawning, then renders this brief again)`,
     ...identityLines(identity, minted),
-    ...rules(identity, mode, branch, slice.base),
+    ...rules(mode, branch, slice.base, exists ? planned : null),
   ];
   return {
     ok: true,

package/src/fanout-worktree.ts

@@ -28,6 +28,8 @@ import path from "node:path";
 import { gitBranch } from "./git/ops";
 import { GIT_TIMEOUTS, gitCommonDir, pushRemoteName, resolveRef } from "./git/rev";
 import { appendObserved, readLedger, type LedgerActor } from "./ledger";
+import { FANOUT_TOKEN_FILE } from "./hooks/worktree-confine";
+import { linkWorktreeDependencies, type LinkedDependencies } from "./worktree-deps";
 import {
   branchRef,
   fanoutFail,
@@ -154,8 +156,6 @@ function createdRow(cwd: string, plan: FanoutFile, slice: Slice, target: string)
   return { row, exact: false };
 }
 
-const TOKEN_FILE = "workit-fanout-token";
-
 /** The filesystem calls identity relies on; tests stub them. */
 export const worktreeDeps = {
   stat: (file: string): fs.BigIntStats => fs.statSync(file, { bigint: true }),
@@ -179,7 +179,7 @@ function adminDir(worktree: string): AdminDir | null {
   const file = dir.stdout.trim();
   let token: string | null = null;
   try {
-    token = fs.readFileSync(path.join(file, TOKEN_FILE), "utf8").trim() || null;
+    token = fs.readFileSync(path.join(file, FANOUT_TOKEN_FILE), "utf8").trim() || null;
   } catch {
     token = null;
   }
@@ -204,7 +204,7 @@ function markAdminDir(worktree: string): (AdminDir & { token: string }) | null {
   if (!admin) return null;
   const token = randomBytes(16).toString("hex");
   try {
-    fs.writeFileSync(path.join(admin.path, TOKEN_FILE), `${token}\n`);
+    fs.writeFileSync(path.join(admin.path, FANOUT_TOKEN_FILE), `${token}\n`);
   } catch {
     return null;
   }
@@ -253,6 +253,8 @@ export type CreateOutcome = {
   mode: "new" | "resume";
   /** False when the worktree already existed on the slice's branch. */
   created: boolean;
+  /** node_modules linked from the main checkout (worktree-deps.ts); null when none were. */
+  dependencies: LinkedDependencies | null;
   notes: string[];
 };
 
@@ -301,6 +303,7 @@ export function createSliceWorktree(
         `remove it yourself (git worktree remove ${target}) once you know what it holds`,
       );
     excludeScratch(cwd);
+    const deps = linkWorktreeDependencies(mainCheckout(cwd), target);
     return {
       ok: true,
       data: {
@@ -309,7 +312,13 @@ export function createSliceWorktree(
         head: existing.head ?? "",
         mode: resolveRef(cwd, localRef) ? "resume" : "new",
         created: false,
-        notes: ["the worktree already exists; nothing was changed"],
+        dependencies: deps.linked,
+        notes: [
+          deps.linked
+            ? "the worktree already exists; only its missing dependencies were linked"
+            : "the worktree already exists; nothing was changed",
+          ...deps.notes,
+        ],
       },
     };
   }
@@ -383,6 +392,8 @@ export function createSliceWorktree(
   }
   excludeScratch(cwd);
   const scratch = ensureScratch(target);
+  const deps = linkWorktreeDependencies(mainCheckout(cwd), target);
+  notes.push(...deps.notes);
   const head = gitRun(target, ["rev-parse", "HEAD"]).stdout.trim();
   const baseSha = mode === "new" ? head : null;
   const admin = markAdminDir(target);
@@ -402,7 +413,10 @@ export function createSliceWorktree(
     ...(admin ? { adminId: admin.id, adminIno: admin.ino, adminToken: admin.token } : {}),
     ...(baseSha ? { baseSha } : {}),
   });
-  return { ok: true, data: { ...base, scratch, head, mode, created: true, notes } };
+  return {
+    ok: true,
+    data: { ...base, scratch, head, mode, created: true, dependencies: deps.linked, notes },
+  };
 }
 
 const worktreeFailed = (stderr: string) =>

package/src/forge/pr-ops.ts

@@ -24,6 +24,7 @@ import {
   resolveAutonomy,
   type AutonomySource,
   type DefaultEndpoint,
+  type VerificationMode,
 } from "../autonomy";
 import { branchKindOf, flowRoute, gitFlowOf, isProtectedTarget } from "../core/branch";
 import { vcsConfig } from "../core/vcs-config";
@@ -40,6 +41,8 @@ import {
   type LedgerActor,
   type VerdictCheck,
 } from "../ledger";
+import type { LaneNeed, ReviewLane } from "../core/policy/lane";
+import { laneLabel, prLaneGate } from "../core/policy/pr-lane";
 import { buildStatusDoc, selectPr, type PrStatusDoc } from "./report";
 import type { ResolvedForge } from "./resolve";
 import { failure, success, type ForgeResult, type MergeMethod, type PrRef } from "./types";
@@ -361,7 +364,22 @@ export type MergeOutcome = {
   head: string;
   method: MergeMethod;
   mergeSha: string | null;
-  verdict: { required: boolean; accepted: boolean; verdictId: string | null };
+  /**
+   * `required`: the gate asked for a verdict (false under lane none or a
+   * bypass); `accepted`: an accepted independent verdict covers the head;
+   * `verdictId`: the verdict the merge relied on (the author's own under lane
+   * self, shown as self-reviewed); `lane`/`need`: the review lane and what it
+   * asked (`need` is non-author outside `verification: proportional`).
+   */
+  verdict: {
+    required: boolean;
+    accepted: boolean;
+    verdictId: string | null;
+    review: "verified" | "self-reviewed" | "none";
+    lane: ReviewLane;
+    need: LaneNeed;
+    verification: VerificationMode;
+  };
   /** Set when `--unverified` bypassed the verdict: the reason and its ledger row. */
   unverified: { reason: string; recorded: string } | null;
   grant: { source: AutonomySource };
@@ -645,13 +663,24 @@ export async function mergePullRequest(
   const ledger = readLedger(cwd, { integrity: true });
   if (!ledger.ok) return ledger;
   const check = checkVerdicts(cwd, branch, ledger.value.rows);
-  const summary = { head: check.head, accepted: check.accepted, authors: check.authors };
-  const covered = check.head === head && check.accepted.accepted;
+  const gate = prLaneGate(cwd, check, { branch, base: doc.base, head });
+  const summary = {
+    head: check.head,
+    accepted: check.accepted,
+    authors: check.authors,
+    lane: gate.lane.lane,
+    need: gate.need,
+  };
+  // Lane none needs no verdict, so no verdict head either.
+  const covered = gate.satisfied && (gate.need === "none" || check.head === head);
   let verdict: MergeOutcome["verdict"] = {
-    required: true,
-    accepted: covered,
-    verdictId:
-      covered && typeof check.accepted.verdict?.id === "string" ? check.accepted.verdict.id : null,
+    required: gate.need !== "none",
+    accepted: check.head === head && check.accepted.accepted,
+    verdictId: covered ? gate.verdictId : null,
+    review: covered ? gate.review : "none",
+    lane: gate.lane.lane,
+    need: gate.need,
+    verification: gate.verification,
   };
   let unverified: MergeOutcome["unverified"] = null;
   // The bypass covers a missing verdict, never a rejection.
@@ -679,9 +708,9 @@ export async function mergePullRequest(
         "failed",
         `unverified_unrecorded: the --unverified bypass could not be recorded (${recorded.error}); nothing was merged`,
       );
-    verdict = { required: false, accepted: false, verdictId: null };
+    verdict = { ...verdict, required: false, accepted: false, verdictId: null, review: "none" };
     unverified = { reason, recorded: String(recorded.value.id) };
-  } else if (check.head !== head)
+  } else if (!covered && check.head !== head)
     return refuse(
       `head_mismatch: the verdict check reads ${branch} at ${check.head?.slice(0, 12) ?? "(missing)"} but ${label} is at ${head.slice(0, 12)}`,
       `git fetch && git switch ${branch} && git merge --ff-only @{u}  # then re-verify that head`,
@@ -693,12 +722,21 @@ export async function mergePullRequest(
       tamperedUnblock(cwd),
       { reason: "ledger_tampered", verdict: summary },
     );
-  else if (!covered)
+  else if (!covered) {
+    const bypassHint = grant.allowUnverified
+      ? `; or, only if the user asks to merge unverified: workit pr merge --unverified --reason "<why>"`
+      : "";
+    const lane = gate.verification === "proportional" ? `, ${laneLabel(gate)}` : "";
     return refuse(
-      `NEEDS_VERDICT: ${label} has no accepted independent verdict for ${head.slice(0, 12)} (${check.accepted.reasons.join(", ")})`,
-      `an independent session verifies the head and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${branch}${grant.allowUnverified ? `; or, only if the user asks to merge unverified: workit pr merge --unverified --reason "<why>"` : ""}`,
+      gate.need === "self"
+        ? `NEEDS_VERDICT: ${label} has no verdict for ${head.slice(0, 12)}${lane}: the author's own --self verdict is enough (${check.accepted.reasons.join(", ")})`
+        : `NEEDS_VERDICT: ${label} has no accepted independent verdict for ${head.slice(0, 12)}${lane} (${check.accepted.reasons.join(", ")})`,
+      gate.need === "self"
+        ? `after an observed passing \`workit check test\`, the author runs: workit ledger verdict tests-verified --self --how "<what you ran>" --branch ${branch} (or a verifier records one)${bypassHint}`
+        : `an independent session verifies the head and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${branch}${bypassHint}`,
       { reason: "needs_verdict", verdict: summary },
     );
+  }
 
   const squashMessage = squashMessageFor(cwd, resolved, input, doc);
   if (squashMessage && !squashMessage.ok) return squashMessage;
@@ -714,6 +752,8 @@ export async function mergePullRequest(
     base: doc.base,
     method: input.method,
     verdictId: verdict.verdictId,
+    review: verdict.review,
+    lane: verdict.lane,
     ...(unverified ? { unverified: unverified.recorded } : {}),
     grant: grant.source,
   });
@@ -747,6 +787,8 @@ export async function mergePullRequest(
     mergeSha: merged.data.mergeSha,
     method: input.method,
     verdictId: verdict.verdictId,
+    review: verdict.review,
+    lane: verdict.lane,
     ...(unverified ? { unverified: unverified.recorded } : {}),
     grant: grant.source,
     intent: intentId,