@brainervirus/workit-core 7.6.0 → 8.0.0

package/src/fanout-brief.ts

@@ -0,0 +1,178 @@
+// `workit fanout brief <slice>`: the complete worker brief, rendered from the
+// plan, the standing orders in force for the fanout (`workit ledger standing`)
+// and the slice's scratch dir, so the lead passes it to the worker verbatim.
+//
+// MODE is `resume` when the branch already exists (a retry continues it),
+// else `new`; `--attempt <n>` renders one attempt of a race on its own branch
+// `<branch>-try<n>` (refused when another slice has that branch), worktree
+// `<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 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
+// the integration tip before reporting, and nothing else. It only reads, apart
+// from hiding `.workit-scratch/` in the repository's info/exclude.
+import { createHash } from "node:crypto";
+import { activeStanding, readLedger, type LedgerActor } from "./ledger";
+import { branchRef, fanoutFail, planLeads, type FanoutFile, type FanoutResult } from "./fanout";
+import {
+  SCRATCH_DIR,
+  excludeScratch,
+  findSlice,
+  listWorktrees,
+  samePath,
+  slicePath,
+} from "./fanout-worktree";
+
+export type BriefMode = "new" | "resume";
+
+export type BriefOutcome = {
+  fanout: string;
+  slice: string;
+  mode: BriefMode;
+  attempt: number | null;
+  branch: string;
+  base: string;
+  tier: string;
+  /** Absolute when the slice's worktree exists, else relative to the worker's worktree root. */
+  scratch: string;
+  session: string;
+  standing: Array<{ id: string; what: string }>;
+  text: string;
+};
+
+export const DEFAULT_TIMEBOX = "30 minutes";
+
+const REPORT = [
+  "REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,",
+  "  each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),",
+  "  anything out of scope as a follow-up, not a diff.",
+];
+
+const rules = (mode: BriefMode, branch: string, base: string): string[] => [
+  "RULES:",
+  mode === "new"
+    ? `  1. First command: \`workit git branch ${branch} --base ${base}\` (your worktree may start on another name).`
+    : `  1. First command: \`git switch ${branch}\`, then continue from its head.`,
+  '  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.',
+  "  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.",
+];
+
+/** A session id fragment that the ledger accepts ([A-Za-z0-9_.:@/+-]). */
+const sessionSafe = (text: string): string => text.replace(/[^A-Za-z0-9_.:@/+-]/gu, "-");
+
+/** The ledger's session id limit. */
+const SESSION_MAX = 128;
+
+/** `<lead>-w-<slice>[+try<n>]`, with the slice part hashed when the whole would be too long. */
+function workerSession(lead: string, slice: string, attempt: number | null): string {
+  const tail = attempt === null ? "" : `+try${attempt}`;
+  const full = `${lead}-w-${slice}${tail}`;
+  if (full.length <= SESSION_MAX) return full;
+  const digest = createHash("sha256").update(slice).digest("hex").slice(0, 12);
+  return `${lead.slice(0, SESSION_MAX - 3 - digest.length - tail.length)}-w-${digest}${tail}`;
+}
+
+export function renderBrief(
+  cwd: string,
+  plan: FanoutFile,
+  input: { slice: string; mode: BriefMode | null; attempt: number | null; actor: LedgerActor },
+): FanoutResult<BriefOutcome> {
+  const found = findSlice(plan, input.slice);
+  if (!found.ok) return found;
+  const slice = found.data;
+  const ledger = readLedger(cwd);
+  if (!ledger.ok) return fanoutFail(ledger.code, ledger.error, ledger.unblock);
+  if (!input.actor.session)
+    return fanoutFail(
+      "blocked",
+      "WORKIT_SESSION_ID is not set: worker session ids derive from the lead's",
+      "export WORKIT_SESSION_ID=<your session id>, then render the brief again",
+    );
+  const branch = input.attempt === null ? slice.branch : `${slice.branch}-try${input.attempt}`;
+  const taken = plan.slices.find((other) => other.id !== slice.id && other.branch === branch);
+  if (taken)
+    return fanoutFail(
+      "invalid_input",
+      `attempt branch ${branch} is slice ${taken.id}'s branch`,
+      "pick another --attempt number, or rename one of the branches in the plan",
+    );
+  const head = branchRef(cwd, branch);
+  const mode: BriefMode = input.mode ?? (head ? "resume" : "new");
+  if (mode === "resume" && !head)
+    return fanoutFail(
+      "not_found",
+      `MODE resume needs the branch ${branch}, which does not exist here`,
+      `workit fanout brief ${slice.id} --mode new`,
+    );
+
+  const planned = `${slicePath(cwd, slice)}${input.attempt === null ? "" : `+try${input.attempt}`}`;
+  const exists = listWorktrees(cwd).some((entry) => samePath(entry.path, planned));
+  excludeScratch(cwd);
+  const scratch = exists ? `${planned}/${SCRATCH_DIR}` : SCRATCH_DIR;
+  const scratchLine = exists
+    ? `SCRATCH: ${scratch}  (yours alone; temp files go here, never a shared path)`
+    : `SCRATCH: ${SCRATCH_DIR}/ at your worktree root (mkdir -p it; git ignores it; never a shared path)`;
+
+  const standing = activeStanding(ledger.value.rows, plan.name, planLeads(plan)).map((row) => ({
+    id: row.id,
+    what: String(row.what),
+  }));
+  const session = workerSession(sessionSafe(input.actor.session), slice.id, input.attempt);
+  const fanIn =
+    plan.fanIn === "integration"
+      ? [
+          `FAN-IN: integration branch ${plan.trunk}. Before you report, merge its tip into your branch`,
+          `  (\`git merge --no-edit ${plan.trunk}\`), resolve conflicts inside SCOPE and re-run VERIFY, so the`,
+          "  lead's merge is a fast-forward. No other merge, and no rebase, retarget or force-push.",
+        ]
+      : [
+          "FAN-IN: one PR per slice. Never rebase, retarget, merge or force-push: the lead owns topology.",
+        ];
+
+  const lines = [
+    `MODE: ${mode}${input.attempt === null ? "" : `  (race attempt ${input.attempt}: the lead keeps the attempt with the best verdict)`}`,
+    `GOAL: ${slice.goal}`,
+    `SCOPE: ${slice.scope.join(", ")}`,
+    ...(slice.owns.length ? [`  owns: ${slice.owns.join(", ")}`] : []),
+    `  branch: ${branch}   base: ${slice.base}`,
+    `CONTEXT: ${slice.context ?? "none given: read the files in SCOPE and the neighbours they import"}`,
+    ...(mode === "resume" && head
+      ? [
+          `  resume: continue ${branch} from ${head.slice(0, 12)}; read \`git log ${slice.base}..${branch}\` and \`workit ledger list --branch ${branch}\` (the last report, verdicts, rulings)`,
+        ]
+      : []),
+    "ACCEPTANCE:",
+    ...slice.acceptance.map((line) => `  - ${line}`),
+    `VERIFY: ${slice.verify.join("; ")}`,
+    `TIER: ${slice.tier}`,
+    `TIMEBOX: ${slice.timebox ?? DEFAULT_TIMEBOX}; past it without a new commit you will be replaced`,
+    scratchLine,
+    `FORBIDDEN: ${slice.forbidden.join("; ")}`,
+    ...fanIn,
+    ...REPORT,
+    "STANDING:",
+    ...(standing.length
+      ? standing.map((order) => `  - ${order.what}`)
+      : ["  - none recorded beyond this brief"]),
+    `  export WORKIT_SESSION_ID=${session}`,
+    ...rules(mode, branch, slice.base),
+  ];
+  return {
+    ok: true,
+    data: {
+      fanout: plan.name,
+      slice: slice.id,
+      mode,
+      attempt: input.attempt,
+      branch,
+      base: slice.base,
+      tier: slice.tier,
+      scratch,
+      session,
+      standing,
+      text: `${lines.join("\n")}\n`,
+    },
+  };
+}

package/src/fanout-check.ts

@@ -293,7 +293,8 @@ export function sliceLandings(
         createdFrom: sliceStart(cwd, rows, plan.name, slice),
         parentHead,
         fanout: plan.name,
-        since: plan.createdAt || null,
+        since: slice.hashSince || plan.createdAt || null,
+        sliceHash: slice.hash || null,
         rows,
       }),
     );

package/src/fanout-landed.ts

@@ -12,8 +12,10 @@
 //   commit (a squash merge that applied without the trunk touching the same
 //   lines). Anything else reads as not landed.
 // A merged PR whose branch is gone counts only when the ledger links that
-// branch to this slice (a worktree row, or a row recorded on its merged
-// head), so a reused branch name from older work is not taken for this slice.
+// branch to this slice: a worktree row made under the slice's current hash,
+// or a row recorded on its merged head since that hash was planned. A reused
+// branch name from older work, an older plan of the same name, or an earlier
+// definition of this slice never links; editing a sibling changes nothing.
 // A landing whose changed paths read on the trunk exactly as before it (a
 // revert) is not landed; the note says so.
 // The forge is asked through a breaker: after the first unavailable answer
@@ -184,24 +186,44 @@ function trunkPatchIds(ctx: LandingContext, fork: string): Set<string> {
   return ids;
 }
 
+/**
+ * Does `row` belong to the slice's current run? A worktree row made under its
+ * hash does; any other row only when recorded since that hash was planned.
+ */
+export function inSliceRun(
+  row: Record<string, unknown>,
+  slice: Pick<Slice, "hash" | "hashSince">,
+): boolean {
+  if (row.type === "fanout.worktree.created" && typeof row.sliceHash === "string" && slice.hash)
+    return row.sliceHash === slice.hash;
+  const since = Date.parse(slice.hashSince);
+  return Number.isNaN(since) || Date.parse(String(row.at)) >= since;
+}
+
 /** The ledger links `branch` to this slice: a worktree row, or a row recorded on `head`. */
 function linked(
   rows: readonly Record<string, unknown>[],
-  input: Pick<LandingInput, "fanout" | "since">,
+  input: Pick<LandingInput, "fanout" | "since" | "sliceHash">,
   slice: Pick<Slice, "id" | "branch">,
   head: string | null,
 ): boolean {
-  // Only rows from this run of the fanout: a plan of the same name made
-  // earlier must not lend its merged PRs to this one.
+  // Only rows from this run of the slice: a plan of the same name made
+  // earlier, or this slice re-planned with another definition, lends nothing.
   const since = input.since ? Date.parse(input.since) : Number.NaN;
-  return rows.some(
-    (row) =>
-      (Number.isNaN(since) || Date.parse(String(row.at)) >= since) &&
-      ((row.type === "fanout.worktree.created" &&
-        row.fanout === input.fanout &&
-        row.slice === slice.id) ||
-        (head !== null && row.branch === slice.branch && row.head === head)),
-  );
+  const recent = (row: Record<string, unknown>) =>
+    Number.isNaN(since) || Date.parse(String(row.at)) >= since;
+  return rows.some((row) => {
+    if (
+      row.type === "fanout.worktree.created" &&
+      row.fanout === input.fanout &&
+      row.slice === slice.id
+    )
+      // A row from before slice hashes falls back to its time.
+      return typeof row.sliceHash === "string" && input.sliceHash
+        ? row.sliceHash === input.sliceHash
+        : recent(row);
+    return recent(row) && head !== null && row.branch === slice.branch && row.head === head;
+  });
 }
 
 export type LandingInput = {
@@ -212,8 +234,10 @@ export type LandingInput = {
   /** Its dependency branch's tip (or merged head) for a stacked slice. */
   parentHead: string | null;
   fanout: string;
-  /** When this fanout plan was first made (FanoutFile.createdAt): older rows do not link. */
+  /** When this slice definition was first planned (Slice.hashSince): older rows do not link. */
   since: string | null;
+  /** The slice's definition hash: worktree rows link only under the same one. */
+  sliceHash: string | null;
   rows: readonly Record<string, unknown>[];
 };
 
@@ -298,7 +322,7 @@ export function sliceStart(
   cwd: string,
   rows: readonly Record<string, unknown>[],
   fanout: string,
-  slice: Pick<Slice, "id" | "branch">,
+  slice: Pick<Slice, "id" | "branch" | "hash" | "hashSince">,
 ): string | null {
   const reflog = branchCreatedAt(cwd, slice.branch);
   if (reflog) return reflog;
@@ -307,7 +331,8 @@ export function sliceStart(
       candidate.type === "fanout.worktree.created" &&
       candidate.fanout === fanout &&
       candidate.slice === slice.id &&
-      typeof candidate.baseSha === "string",
+      typeof candidate.baseSha === "string" &&
+      inSliceRun(candidate, slice),
   );
   return (row?.baseSha as string | undefined) ?? null;
 }

package/src/fanout-status.ts

@@ -20,7 +20,7 @@ import { checksState, gatingChecks, missingRequired, type ChecksState } from "./
 import type { ResolvedForge } from "./forge/resolve";
 import { checkVerdicts, readLedger, type ReadRow, type VerdictBasis } from "./ledger";
 import { sliceLandings } from "./fanout-check";
-import { forgeBreaker } from "./fanout-landed";
+import { forgeBreaker, inSliceRun } from "./fanout-landed";
 import {
   branchRef,
   fanoutFail,
@@ -123,6 +123,8 @@ function activity(cwd: string, plan: FanoutFile, slice: Slice, rows: readonly Re
     ]).stdout,
   );
   const reflog = moved ? isoOf(moved[1]) : null;
+  // Liveness reads every row on the branch or slice: re-planning a slice
+  // never makes a live worker look idle.
   const ledger = rows
     .filter(
       (row) => row.branch === slice.branch || (row.fanout === plan.name && row.slice === slice.id),
@@ -136,7 +138,8 @@ function activity(cwd: string, plan: FanoutFile, slice: Slice, rows: readonly Re
       (row) =>
         row.type === "fanout.worktree.created" &&
         row.fanout === plan.name &&
-        row.slice === slice.id,
+        row.slice === slice.id &&
+        inSliceRun(row, slice),
     ),
   };
 }
@@ -267,7 +270,8 @@ export function fanoutStatus(
         (candidate) =>
           candidate.type === "fanout.worktree.created" &&
           candidate.fanout === plan.name &&
-          candidate.slice === id,
+          candidate.slice === id &&
+          inSliceRun(candidate, byId.get(id) as Slice),
       );
       row.state = created ? "active" : "not_started";
       if (!created) spawnable.push(id);

package/src/fanout-worktree.ts

@@ -12,10 +12,17 @@
 // (`fanout.worktree.released`), refuses while it has uncommitted changes
 // unless forced, then runs `git worktree remove` (which takes the scratch dir
 // with it). The branch is kept. It only removes a worktree that `create` made
-// for this fanout, slice and path (its ledger row says so), on the slice's
-// branch or detached; never the main checkout, the one the command runs in,
-// or a worktree someone else made there, not even with --force. An empty
+// for this fanout, slice and path, on the slice's branch or detached; never
+// the main checkout, the one the command runs in, or a worktree someone else
+// made there, not even with --force. "Made by create" is exact: create writes
+// a random token into git's admin dir for the worktree
+// (`.git/worktrees/<id>/workit-fanout-token`) and records it with the admin
+// dir's id and inode; release and adopt need all three to match. A worktree
+// removed by hand and re-added at the path gets a new admin dir without the
+// token, on any filesystem (no birth time needed). A row from before the
+// token is matched by time only, so release refuses --force for it. An empty
 // directory that existed before `create` is left in place.
+import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { gitBranch } from "./git/ops";
@@ -68,7 +75,7 @@ const canonical = (target: string): string => {
   }
 };
 
-const samePath = (a: string, b: string): boolean => {
+export const samePath = (a: string, b: string): boolean => {
   const left = canonical(a);
   const right = canonical(b);
   return process.platform === "win32" || process.platform === "darwin"
@@ -82,7 +89,7 @@ const inside = (child: string, parent: string): boolean => {
 };
 
 /** `git worktree list --porcelain -z`; the first entry is the main worktree. */
-function listWorktrees(cwd: string): WorktreeEntry[] {
+export function listWorktrees(cwd: string): WorktreeEntry[] {
   const out: WorktreeEntry[] = [];
   let current: WorktreeEntry | null = null;
   for (const field of gitRun(cwd, ["worktree", "list", "--porcelain", "-z"]).stdout.split("\0")) {
@@ -98,7 +105,7 @@ function listWorktrees(cwd: string): WorktreeEntry[] {
 }
 
 /** The slice's worktree path: absolute since plan time; an older relative one is the main checkout's. */
-const slicePath = (cwd: string, slice: Slice): string =>
+export const slicePath = (cwd: string, slice: Slice): string =>
   path.isAbsolute(slice.worktree)
     ? slice.worktree
     : path.resolve(mainCheckout(cwd), slice.worktree);
@@ -110,8 +117,10 @@ const CLOCK_SLACK_MS = 2000;
  * The live `fanout.worktree.created` row for this fanout, slice and path:
  * the newest one, unless a later release removed that worktree (a row is
  * void once its worktree is gone), and only while the worktree at the path
- * is the one it recorded: git's admin dir for it (`.git/worktrees/<id>`) was
- * made no earlier than the row. Anything else is someone else's worktree.
+ * is the one it recorded. `exact`: the admin dir's token, id and inode match
+ * the row. A row without a token (written before it) matches when the admin
+ * dir is no older than the row, which a re-added worktree also passes, so it
+ * is never exact. Anything else is someone else's worktree.
  */
 function createdRow(cwd: string, plan: FanoutFile, slice: Slice, target: string) {
   const ledger = readLedger(cwd);
@@ -134,24 +143,75 @@ function createdRow(cwd: string, plan: FanoutFile, slice: Slice, target: string)
       atPath(candidate),
   );
   if (removedSince) return null;
-  const made = adminDirTime(target);
-  if (made === null || made + CLOCK_SLACK_MS < Date.parse(row.at)) return null;
-  return row;
+  const admin = adminDir(target);
+  if (!admin) return null;
+  if (typeof row.adminToken === "string")
+    return row.adminToken === admin.token && row.adminId === admin.id && row.adminIno === admin.ino
+      ? { row, exact: true }
+      : null;
+  const made = admin.birthMs ?? admin.mtimeMs;
+  if (made + CLOCK_SLACK_MS < Date.parse(row.at)) return null;
+  return { row, exact: false };
 }
 
-/** When git made the worktree's admin dir (birth time, else mtime); null when unknown. */
-function adminDirTime(worktree: string): number | null {
+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 }),
+};
+
+type AdminDir = {
+  path: string;
+  /** `<id>` of `.git/worktrees/<id>`. */
+  id: string;
+  ino: string;
+  /** The token create wrote there, or null. */
+  token: string | null;
+  birthMs: number | null;
+  mtimeMs: number;
+};
+
+/** Git's admin dir for the worktree: what tells this worktree from a later one at the path. */
+function adminDir(worktree: string): AdminDir | null {
   const dir = gitRun(worktree, ["rev-parse", "--absolute-git-dir"]);
   if (!dir.ok) return null;
+  const file = dir.stdout.trim();
+  let token: string | null = null;
+  try {
+    token = fs.readFileSync(path.join(file, TOKEN_FILE), "utf8").trim() || null;
+  } catch {
+    token = null;
+  }
+  try {
+    const stat = worktreeDeps.stat(file);
+    return {
+      path: file,
+      id: path.basename(file),
+      ino: stat.ino.toString(),
+      token,
+      birthMs: stat.birthtimeNs > 0n ? Number(stat.birthtimeMs) : null,
+      mtimeMs: Number(stat.mtimeMs),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Mark the admin dir of a worktree create just made; null when it cannot. */
+function markAdminDir(worktree: string): (AdminDir & { token: string }) | null {
+  const admin = adminDir(worktree);
+  if (!admin) return null;
+  const token = randomBytes(16).toString("hex");
   try {
-    const stat = fs.statSync(dir.stdout.trim());
-    return stat.birthtimeMs > 0 ? stat.birthtimeMs : stat.mtimeMs;
+    fs.writeFileSync(path.join(admin.path, TOKEN_FILE), `${token}\n`);
   } catch {
     return null;
   }
+  return { ...admin, token };
 }
 
-function findSlice(plan: FanoutFile, id: string): FanoutResult<Slice> {
+export function findSlice(plan: FanoutFile, id: string): FanoutResult<Slice> {
   const slice = plan.slices.find((candidate) => candidate.id === id);
   return slice
     ? { ok: true, data: slice }
@@ -163,7 +223,7 @@ function findSlice(plan: FanoutFile, id: string): FanoutResult<Slice> {
 }
 
 /** Hide the scratch dir from git status and `git add -A` in every worktree. */
-function excludeScratch(cwd: string): void {
+export function excludeScratch(cwd: string): void {
   const common = gitCommonDir(cwd);
   if (!common) return;
   const file = path.join(common, "info", "exclude");
@@ -325,6 +385,7 @@ export function createSliceWorktree(
   const scratch = ensureScratch(target);
   const head = gitRun(target, ["rev-parse", "HEAD"]).stdout.trim();
   const baseSha = mode === "new" ? head : null;
+  const admin = markAdminDir(target);
   appendObserved(cwd, {
     type: "fanout.worktree.created",
     actor: input.actor,
@@ -337,6 +398,8 @@ export function createSliceWorktree(
     head,
     dirExisted,
     planCreatedAt: plan.createdAt,
+    sliceHash: slice.hash,
+    ...(admin ? { adminId: admin.id, adminIno: admin.ino, adminToken: admin.token } : {}),
     ...(baseSha ? { baseSha } : {}),
   });
   return { ok: true, data: { ...base, scratch, head, mode, created: true, notes } };
@@ -410,13 +473,20 @@ export function releaseSliceWorktree(
       "blocked",
       `${entry.path} is on ${entry.branch.replace(/^refs\/heads\//u, "")}, not slice ${slice.id}'s ${slice.branch}; nothing was removed`,
     );
-  const made = createdRow(cwd, plan, slice, entry.path);
-  if (!made)
+  const owned = createdRow(cwd, plan, slice, entry.path);
+  if (!owned)
     return fanoutFail(
       "blocked",
       `${entry.path} was not made by workit fanout worktree create for slice ${slice.id} (no ledger row); nothing was removed`,
       `remove it yourself (git worktree remove ${entry.path}) once you know what it holds`,
     );
+  if (input.force && !owned.exact)
+    return fanoutFail(
+      "blocked",
+      `${entry.path} was created before workit recorded worktree identity, so it cannot be told from a worktree someone re-added there; --force is refused and nothing was removed`,
+      `release it without --force, or remove it yourself (git worktree remove ${entry.path}) once you know what it holds`,
+    );
+  const made = owned.row;
   out.head = entry.head;
   const status = gitRun(entry.path, [
     "status",