@brainervirus/workit-cli 2.2.1 → 2.3.0

package/dist/index.js

@@ -73071,15 +73071,1106 @@ var init_stack = __esm(() => {
   run17 = notImplemented("stack", "S12");
 });
 
+// packages/workit-core/src/git/rev.ts
+import { spawnSync as spawnSync13 } from "node:child_process";
+import { createHash as createHash12 } from "node:crypto";
+import fs15 from "node:fs";
+import os12 from "node:os";
+import path34 from "node:path";
+function headSha(cwd) {
+  return line(git(cwd, ["rev-parse", "--verify", "-q", "HEAD^{commit}"]));
+}
+function worktreeTree(cwd, options = {}) {
+  const top = line(git(cwd, ["rev-parse", "--show-toplevel"]));
+  const indexPath = line(git(cwd, ["rev-parse", "--path-format=absolute", "--git-path", "index"]));
+  if (!top || !indexPath)
+    return null;
+  const cap = options.maxUntrackedBytes ?? MAX_UNTRACKED_BYTES;
+  const timeoutMs = options.timeoutMs ?? GIT_TIMEOUTS.worktree;
+  const scratch = fs15.mkdtempSync(path34.join(os12.tmpdir(), "workit-tree-"));
+  try {
+    const tempIndex = path34.join(scratch, "index");
+    if (fs15.existsSync(indexPath))
+      seedIndex(indexPath, tempIndex);
+    const env = { ...process.env, GIT_INDEX_FILE: tempIndex };
+    const untracked = git(top, ["ls-files", "--others", "--exclude-standard", "-z"], {
+      env,
+      timeoutMs
+    });
+    if (!untracked.ok)
+      return null;
+    const skipped = [];
+    for (const file of untracked.stdout.split("\x00").filter(Boolean)) {
+      try {
+        const stat = fs15.statSync(path34.join(top, file));
+        if (stat.isFile() && stat.size > cap)
+          skipped.push({ path: file, size: stat.size, mtimeMs: Math.trunc(stat.mtimeMs) });
+      } catch {}
+    }
+    skipped.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const added = skipped.length ? git(top, ["add", "-A", "--pathspec-from-file=-", "--pathspec-file-nul"], {
+      env,
+      timeoutMs,
+      input: [".", ...skipped.map((file) => `:(exclude,literal)${file.path}`)].join("\x00")
+    }) : git(top, ["add", "-A"], { env, timeoutMs });
+    if (!added.ok)
+      return null;
+    const tree = line(git(top, ["write-tree"], { env, timeoutMs }));
+    if (!tree)
+      return null;
+    const base = line(git(top, ["rev-parse", "--verify", "-q", "HEAD^{tree}"])) ?? emptyTree(top);
+    const key = skipped.length ? `sha256:${createHash12("sha256").update(JSON.stringify({ tree, skipped })).digest("hex")}` : tree;
+    return { tree, key, dirty: tree !== base || skipped.length > 0, skipped };
+  } finally {
+    fs15.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+function patchId(cwd, base, head) {
+  if (!safeArg(base) || !safeArg(head))
+    return null;
+  const diff = git(cwd, [
+    "diff",
+    "-U3",
+    "--diff-algorithm=myers",
+    "--indent-heuristic",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--no-renames",
+    "--full-index",
+    "--src-prefix=a/",
+    "--dst-prefix=b/",
+    `${base}...${head}`,
+    "--"
+  ]);
+  if (!diff.ok || !diff.stdout.trim())
+    return null;
+  const id = git(cwd, ["patch-id", "--stable"], { input: diff.stdout });
+  return line(id)?.split(/\s+/u)[0] ?? null;
+}
+function currentBranch2(cwd) {
+  return line(git(cwd, ["symbolic-ref", "--short", "-q", "HEAD"]));
+}
+var MAX_BUFFER, GIT_TIMEOUTS, git = (cwd, args, options = {}) => {
+  const result = spawnSync13("git", args, {
+    cwd,
+    encoding: "utf8",
+    env: options.env ?? process.env,
+    input: options.input,
+    maxBuffer: MAX_BUFFER,
+    timeout: options.timeoutMs ?? GIT_TIMEOUTS.local,
+    killSignal: "SIGKILL",
+    windowsHide: true
+  });
+  const error = result.error;
+  return {
+    ok: result.status === 0,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    timedOut: error?.code === "ETIMEDOUT"
+  };
+}, line = (run) => {
+  if (!run.ok)
+    return null;
+  const value = run.stdout.trim();
+  return value ? value : null;
+}, safeArg = (value) => value.length > 0 && !value.startsWith("-"), emptyTree = (cwd) => line(git(cwd, ["mktree"], { input: "" })), MAX_UNTRACKED_BYTES, seedIndex = (from, to) => {
+  fs15.copyFileSync(from, to);
+  const { atimeNs, mtimeNs } = fs15.statSync(from, { bigint: true });
+  const seconds = (ns) => (Number(ns / 1000n) - 1) / 1e6;
+  fs15.utimesSync(to, seconds(atimeNs), seconds(mtimeNs));
+};
+var init_rev = __esm(() => {
+  MAX_BUFFER = 256 * 1024 * 1024;
+  GIT_TIMEOUTS = { local: 20000, worktree: 120000, network: 15000 };
+  MAX_UNTRACKED_BYTES = 5 * 1024 * 1024;
+});
+
+// packages/workit-core/src/ledger.ts
+import { spawnSync as spawnSync14 } from "node:child_process";
+import { createHash as createHash13, randomBytes as randomBytes2 } from "node:crypto";
+import fs16 from "node:fs";
+import path35 from "node:path";
+function resolveCommit(cwd, ref) {
+  if (!safeRef(ref))
+    return null;
+  return git2(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]);
+}
+function branchHead(cwd, branch) {
+  if (!safeRef(branch))
+    return null;
+  return resolveCommit(cwd, `refs/heads/${branch}`) ?? resolveCommit(cwd, `refs/remotes/origin/${branch}`);
+}
+function defaultBase2(cwd) {
+  const originHead = git2(cwd, ["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"]);
+  if (originHead && resolveCommit(cwd, originHead))
+    return originHead;
+  for (const candidate of ["origin/main", "origin/master", "main", "master"])
+    if (resolveCommit(cwd, candidate))
+      return candidate;
+  return null;
+}
+function diffHash(cwd, base, head) {
+  if (!safeRef(base) || !safeRef(head))
+    return null;
+  const diff = gitRun(cwd, [
+    "diff",
+    "-U3",
+    "--diff-algorithm=myers",
+    "--indent-heuristic",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--no-renames",
+    "--full-index",
+    "--binary",
+    "--src-prefix=a/",
+    "--dst-prefix=b/",
+    `${base}...${head}`,
+    "--"
+  ], GIT_TIMEOUTS.worktree);
+  if (!diff.ok || !diff.stdout)
+    return null;
+  const hash = createHash13("sha256");
+  for (const line of diff.stdout.split(`
+`)) {
+    if (line.startsWith("index "))
+      continue;
+    hash.update(line.startsWith("@@ ") ? "@@" : line);
+    hash.update(`
+`);
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+function storeRoot(cwd) {
+  const run = gitRun(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  const common = run.stdout.trim();
+  if (run.ok && common)
+    return {
+      ok: true,
+      value: { root: path35.join(path35.resolve(cwd, common), "workit"), shared: true }
+    };
+  if (!run.ok && NOT_A_REPO.test(run.stderr))
+    return { ok: true, value: { root: path35.join(path35.resolve(cwd), ".workit"), shared: false } };
+  return err("unavailable", `cannot locate the workit store: git rev-parse failed (${run.stderr.trim().split(`
+`)[0] || "no output"})`, "fix the repository (git status should work here) or run from a non-git directory");
+}
+function ledgerPath(cwd) {
+  const root = storeRoot(cwd);
+  return root.ok ? { ok: true, value: path35.join(root.value.root, "ledger", "ledger.jsonl") } : root;
+}
+function actorFromEnv(env) {
+  const value = (key) => {
+    const raw = env[key]?.trim();
+    return raw ? raw : null;
+  };
+  return {
+    host: value("WORKIT_HOST") ?? "cli",
+    session: value("WORKIT_SESSION_ID"),
+    agentId: value("WORKIT_AGENT_ID")
+  };
+}
+function withLedgerLock(file, fn, waitMs = LOCK_WAIT_MS) {
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + waitMs;
+  let token = null;
+  for (;; ) {
+    token = ledgerLock.acquire(lock);
+    if (token)
+      break;
+    const observed = lockToken(lock);
+    const age = lockAgeMs(lock);
+    if (age !== null && age > LOCK_STALE_MS && ledgerLock.reap(lock, observed))
+      continue;
+    if (Date.now() >= deadline)
+      return null;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+  }
+  try {
+    return fn();
+  } finally {
+    ledgerLock.release(lock, token);
+  }
+}
+function appendLine(file, line, options) {
+  const write = () => {
+    const fd = fs16.openSync(file, "a+");
+    try {
+      const size = fs16.fstatSync(fd).size;
+      let fence = "";
+      if (size > 0) {
+        const last = Buffer.alloc(1);
+        fs16.readSync(fd, last, 0, 1, size - 1);
+        if (last[0] !== 10)
+          fence = `
+`;
+      }
+      const bytes = Buffer.from(fence + line);
+      const written = fs16.writeSync(fd, bytes);
+      if (written !== bytes.length)
+        return err("unavailable", `short write to ${file}: ${written} of ${bytes.length} bytes; the row is torn and will be skipped`);
+      return { ok: true, value: undefined };
+    } finally {
+      fs16.closeSync(fd);
+    }
+  };
+  try {
+    fs16.mkdirSync(path35.dirname(file), { recursive: true });
+    if (!options.forceLock && !onNetworkFs(path35.dirname(file)))
+      return write();
+    const locked = withLedgerLock(file, write);
+    return locked ?? err("busy", `ledger lock ${file}.lock is held`, "retry; remove the .lock directory if no workit process is running");
+  } catch (error) {
+    return err("unavailable", `cannot append to ${file}: ${error.message}`);
+  }
+}
+function appendRaw(cwd, row, options) {
+  const { full, line } = serialize(row, options.now ?? new Date);
+  const bytes = Buffer.byteLength(line);
+  if (bytes > MAX_LINE_BYTES)
+    return err("invalid_input", `ledger row is ${bytes} bytes; the limit is ${MAX_LINE_BYTES}. Shorten the text and pass details by --ref <path|url>`);
+  const file = ledgerPath(cwd);
+  if (!file.ok)
+    return file;
+  const written = appendLine(file.value, line, options);
+  return written.ok ? { ok: true, value: full } : written;
+}
+function appendRow(cwd, row, options = {}) {
+  if (row.observer === "workit_cli")
+    return err("invalid_input", 'observer "workit_cli" is reserved for appendObserved');
+  return appendRaw(cwd, row, options);
+}
+function supersedeAllowed(by, target) {
+  if (by.type !== target.type)
+    return `a ${by.type} row cannot supersede a ${target.type} row`;
+  if (!by.actor.session || by.actor.session !== target.actor.session)
+    return "only the session that wrote a row can supersede it";
+  if (by.type === "verdict" && by.self === true && target.self !== true)
+    return "a self verdict cannot replace an independent verdict";
+  return null;
+}
+function readLedger(cwd) {
+  const file = ledgerPath(cwd);
+  if (!file.ok)
+    return file;
+  let text = "";
+  try {
+    text = fs16.readFileSync(file.value, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return { ok: true, value: { path: file.value, rows: [], skipped: 0 } };
+    return err("unavailable", `cannot read ${file.value}: ${error.message}`);
+  }
+  const rows = [];
+  let skipped = 0;
+  for (const raw of text.split(`
+`)) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+      continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      skipped += 1;
+      continue;
+    }
+    if (!isRecord5(parsed) || !str(parsed.id) || !str(parsed.type) || !str(parsed.at)) {
+      skipped += 1;
+      continue;
+    }
+    const pr = typeof parsed.pr === "number" && Number.isInteger(parsed.pr) ? parsed.pr : undefined;
+    rows.push({
+      ...parsed,
+      v: typeof parsed.v === "number" ? parsed.v : LEDGER_VERSION,
+      id: parsed.id,
+      at: parsed.at,
+      type: parsed.type,
+      actor: normalizeActor(parsed.actor),
+      branch: str(parsed.branch),
+      head: str(parsed.head),
+      base: str(parsed.base),
+      baseSha: str(parsed.baseSha),
+      patchId: str(parsed.patchId),
+      diffHash: str(parsed.diffHash),
+      tree: str(parsed.tree),
+      dirty: typeof parsed.dirty === "boolean" ? parsed.dirty : null,
+      ...pr === undefined ? {} : { pr },
+      ...str(parsed.supersedes) ? { supersedes: parsed.supersedes } : {},
+      seq: rows.length + 1,
+      superseded: false,
+      supersedeIgnored: false
+    });
+  }
+  const byId = new Map;
+  for (const row of rows) {
+    const target = row.supersedes ? byId.get(row.supersedes) : undefined;
+    if (target && supersedeAllowed(row, target) === null)
+      target.superseded = true;
+    else if (row.supersedes)
+      row.supersedeIgnored = true;
+    if (!byId.has(row.id))
+      byId.set(row.id, row);
+  }
+  return { ok: true, value: { path: file.value, rows, skipped } };
+}
+function filterRows(rows, filter) {
+  const matched = rows.filter((row) => (filter.branch === undefined || row.branch === filter.branch) && (filter.pr === undefined || row.pr === filter.pr) && (filter.type === undefined || row.type === filter.type));
+  return filter.last === undefined ? matched : matched.slice(Math.max(0, matched.length - filter.last));
+}
+function branchForPr(cwd, rows, pr) {
+  for (let index = rows.length - 1;index >= 0; index -= 1) {
+    const row = rows[index];
+    if (row.pr === pr && row.branch && PR_ROW_TYPES.has(row.type) && row.observer === "workit_cli")
+      return { ok: true, branch: row.branch, source: "pr_row" };
+  }
+  const tips = git2(cwd, [
+    "for-each-ref",
+    "--format=%(objectname)",
+    `refs/pull/${pr}/head`,
+    `refs/merge-requests/${pr}/head`,
+    `refs/remotes/*/pull/${pr}/head`,
+    `refs/remotes/*/merge-requests/${pr}/head`
+  ]);
+  const shas = [...new Set((tips ?? "").split(`
+`).filter(Boolean))];
+  if (shas.length === 0)
+    return { ok: false, reason: "unknown", candidates: [] };
+  if (shas.length > 1)
+    return { ok: false, reason: "ambiguous", candidates: shas };
+  const branches = (git2(cwd, ["for-each-ref", "--format=%(refname:short)", "--points-at", shas[0], "refs/heads"]) ?? "").split(`
+`).filter(Boolean);
+  if (branches.length === 1)
+    return { ok: true, branch: branches[0], source: "forge_ref" };
+  return branches.length === 0 ? { ok: false, reason: "unknown", candidates: [] } : { ok: false, reason: "ambiguous", candidates: branches };
+}
+function codeKey(cwd, options = {}) {
+  const checkedOut = currentBranch2(cwd);
+  const branch = options.branch ?? checkedOut;
+  const head = branch ? branchHead(cwd, branch) : headSha(cwd);
+  const base = options.base ?? defaultBase2(cwd);
+  const baseSha = base ? resolveCommit(cwd, base) : null;
+  const onTree = branch !== null && branch === checkedOut;
+  const tree = onTree ? worktreeTree(cwd) : null;
+  return {
+    branch,
+    head,
+    base,
+    baseSha,
+    patchId: base && head ? patchId(cwd, base, head) : null,
+    diffHash: base && head ? diffHash(cwd, base, head) : null,
+    tree: tree?.key ?? null,
+    dirty: tree ? tree.dirty : null
+  };
+}
+function verdictBasis(verdict, current) {
+  if (verdict.head && verdict.head === current.head)
+    return "fresh";
+  if (verdict.patchId && verdict.patchId === current.patchId && verdict.diffHash && verdict.diffHash === current.diffHash)
+    return "carried";
+  return "stale";
+}
+function trailerSessions(cwd, base, head) {
+  if (!base || !head || !safeRef(base) || !safeRef(head))
+    return [];
+  const out = git2(cwd, [
+    "log",
+    "--format=%(trailers:key=Workit-Session,valueonly,separator=%x00)",
+    `${base}..${head}`
+  ]);
+  return (out ?? "").split(/[\0\n]/u).map((value) => value.trim()).filter(Boolean);
+}
+function authorSessions(cwd, rows, branch, range = { base: null, head: null }) {
+  const sessions = new Set;
+  for (const row of rows) {
+    if (row.branch !== branch || row.type !== "commit.recorded" && row.type !== "task.opened")
+      continue;
+    const session = str(row.session) ?? row.actor.session;
+    if (session)
+      sessions.add(session);
+  }
+  for (const session of trailerSessions(cwd, range.base, range.head))
+    sessions.add(session);
+  return sessions;
+}
+function effectiveOf(rows, authors) {
+  let effective = null;
+  for (const row of rows) {
+    if (!effective) {
+      effective = row;
+      continue;
+    }
+    const rowIndependent = independenceReasons(row, authors).length === 0;
+    const effIndependent = independenceReasons(effective, authors).length === 0;
+    if (effIndependent && !rowIndependent)
+      continue;
+    if (effIndependent && FAILING.has(String(effective.result)) && row.actor.session === effective.actor.session)
+      continue;
+    effective = row;
+  }
+  return effective;
+}
+function checkVerdicts(cwd, branch, rows) {
+  const head = branchHead(cwd, branch);
+  const fallbackBase = defaultBase2(cwd);
+  const keyCache = new Map;
+  const keyFor = (base) => {
+    if (!base || !head)
+      return { patchId: null, diffHash: null };
+    let key = keyCache.get(base);
+    if (!key) {
+      key = { patchId: patchId(cwd, base, head), diffHash: diffHash(cwd, base, head) };
+      keyCache.set(base, key);
+    }
+    return key;
+  };
+  const authors = authorSessions(cwd, rows, branch, { base: fallbackBase, head });
+  const byKind = new Map;
+  for (const row of rows)
+    if (row.branch === branch && isLiveVerdict(row)) {
+      const kind = typeof row.kind === "string" ? row.kind : "review";
+      byKind.set(kind, [...byKind.get(kind) ?? [], row]);
+    }
+  const verdicts = [];
+  for (const [kind, list] of byKind) {
+    const row = effectiveOf(list, authors);
+    if (!row)
+      continue;
+    const basis = verdictBasis(row, { head, ...keyFor(row.base ?? fallbackBase) });
+    const current = basis !== "stale";
+    const independence = independenceReasons(row, authors);
+    const reasons = [
+      ...current ? [] : ["stale"],
+      ...PASSING.has(String(row.result)) ? [] : ["not_passing"],
+      ...independence
+    ];
+    verdicts.push({
+      kind,
+      basis,
+      current,
+      independent: independence.length === 0,
+      accepted: reasons.length === 0,
+      reasons,
+      verdict: row
+    });
+  }
+  verdicts.sort((a, b) => a.verdict.seq - b.verdict.seq);
+  const newestCurrent = verdicts.findLast((entry) => entry.current) ?? verdicts.at(-1) ?? null;
+  const failing = verdicts.find((entry) => entry.current && entry.independent && FAILING.has(String(entry.verdict.result)));
+  const newestAccepted = verdicts.findLast((entry) => entry.accepted) ?? null;
+  const accepted = newestAccepted && !failing ? { accepted: true, verdict: newestAccepted.verdict, reasons: [] } : {
+    accepted: false,
+    verdict: failing?.verdict ?? null,
+    reasons: failing ? ["failing_verdict"] : newestCurrent?.reasons ?? ["no_verdict"]
+  };
+  return {
+    branch,
+    head,
+    base: newestCurrent?.verdict.base ?? fallbackBase,
+    patchId: keyFor(newestCurrent?.verdict.base ?? fallbackBase).patchId,
+    current: { basis: newestCurrent?.basis ?? "none", verdict: newestCurrent?.verdict ?? null },
+    accepted,
+    verdicts,
+    authors: [...authors].toSorted()
+  };
+}
+function checkSupersede(context, type, self2) {
+  if (!context.supersedes)
+    return { ok: true, value: undefined };
+  const ledger = readLedger(context.cwd);
+  if (!ledger.ok)
+    return ledger;
+  const target = ledger.value.rows.find((row) => row.id === context.supersedes);
+  if (!target)
+    return err("not_found", `no ledger row ${context.supersedes} to supersede`);
+  const problem = supersedeAllowed({ type, actor: context.actor, self: self2 }, target);
+  return problem ? err("invalid_input", `--supersedes: ${problem}`) : { ok: true, value: undefined };
+}
+function recordDecision(context, input) {
+  const what = required2(input.what, "<what>");
+  if (!what.ok)
+    return what;
+  const why = required2(input.why, "--why");
+  if (!why.ok)
+    return why;
+  const link = checkSupersede(context, "decision");
+  if (!link.ok)
+    return link;
+  return appendRow(context.cwd, {
+    ...common2(context, noteKey(context)),
+    type: "decision",
+    what: what.value,
+    why: why.value,
+    refs: input.refs ?? []
+  }, { now: context.now });
+}
+function recordRuling(context, input) {
+  const what = required2(input.what, "<what>");
+  if (!what.ok)
+    return what;
+  const why = required2(input.why, "--why");
+  if (!why.ok)
+    return why;
+  const cost = required2(input.costIfWrong, "--cost-if-wrong");
+  if (!cost.ok)
+    return cost;
+  const link = checkSupersede(context, "ruling");
+  if (!link.ok)
+    return link;
+  return appendRow(context.cwd, {
+    ...common2(context, noteKey(context)),
+    type: "ruling",
+    what: what.value,
+    why: why.value,
+    costIfWrong: cost.value,
+    refs: input.refs ?? []
+  }, { now: context.now });
+}
+function recordVerdict(context, input) {
+  if (!VERDICT_RESULTS.includes(input.result))
+    return err("invalid_input", `unknown verdict "${input.result}"; expected ${VERDICT_RESULTS.join("|")}`);
+  const kind = input.kind ?? "review";
+  if (!VERDICT_KINDS.includes(kind))
+    return err("invalid_input", `--kind must be ${VERDICT_KINDS.join("|")}`);
+  const surface = input.surface ?? null;
+  if (surface !== null && !VERDICT_SURFACES.includes(surface))
+    return err("invalid_input", `--surface must be ${VERDICT_SURFACES.join("|")}`);
+  const how = required2(input.how, "--how");
+  if (!how.ok)
+    return how;
+  const branch = context.branch ?? currentBranch2(context.cwd);
+  if (!branch)
+    return err("invalid_input", "HEAD is detached; name the branch the verdict is for", "pass --branch <branch>");
+  const ledger = readLedger(context.cwd);
+  if (!ledger.ok)
+    return ledger;
+  const key = codeKey(context.cwd, { branch, base: context.base });
+  if (!key.head)
+    return err("not_found", `branch "${branch}" has no commit to judge`);
+  if (key.dirty === true)
+    return err("blocked", `dirty_worktree: ${branch} has uncommitted changes, so its head is not what was judged`, "commit or stash the changes, re-check, then record the verdict");
+  const session = context.actor.session;
+  const selfReason = input.self === true ? "flag" : session ? null : "no_session";
+  const self2 = selfReason !== null;
+  if (!self2 && session && authorSessions(context.cwd, ledger.value.rows, branch, { base: key.base, head: key.head }).has(session))
+    return err("blocked", `author_verdict: session ${session} authored ${branch}; a verdict must come from a different session`, 'have a non-author session record the verdict, or pass --self (a self verdict is never accepted by merge:"verified")');
+  const link = checkSupersede(context, "verdict", self2);
+  if (!link.ok)
+    return link;
+  return appendRow(context.cwd, {
+    ...common2(context, key),
+    type: "verdict",
+    kind,
+    result: input.result,
+    how: how.value,
+    surface,
+    observer: "agent_asserted",
+    self: self2,
+    selfReason,
+    evidenceRefs: input.evidenceRefs ?? []
+  }, { now: context.now });
+}
+function recordHandoff(context, input) {
+  return appendRow(context.cwd, { ...common2(context, noteKey(context)), type: "handoff", note: input.note, next: input.next }, { now: context.now });
+}
+function rowLabels(row) {
+  const labels = [];
+  if (row.superseded)
+    labels.push("superseded");
+  if (row.supersedeIgnored || OBSERVED_ONLY.has(row.type) && row.observer !== "workit_cli")
+    labels.push("ignored");
+  if (row.type === "verdict" && row.self === true)
+    labels.push("self");
+  return labels;
+}
+function summarizeRow(row) {
+  const text = (key) => str(row[key]) ?? "";
+  let summary;
+  switch (row.type) {
+    case "decision":
+      summary = `${text("what")} (why: ${text("why")})`;
+      break;
+    case "ruling":
+      summary = `${text("what")} (why: ${text("why")}; cost if wrong: ${text("costIfWrong")})`;
+      break;
+    case "verdict":
+      summary = `${text("result")} [${text("kind") || "review"}] at ${(row.head ?? "?").slice(0, 12)}${row.self === true ? ` (self${text("selfReason") === "no_session" ? ": no session" : ""})` : ""}: ${text("how")}`;
+      break;
+    case "handoff":
+      summary = `next: ${text("next")}${text("note") ? ` (note: ${text("note")})` : ""}`;
+      break;
+    default:
+      summary = text("what") || text("name") || row.type;
+  }
+  return {
+    seq: row.seq,
+    id: row.id,
+    at: row.at,
+    type: row.type,
+    branch: row.branch,
+    summary,
+    labels: rowLabels(row)
+  };
+}
+function stackPosition(root, branch) {
+  const dir = path35.join(root, "stacks");
+  let names = [];
+  try {
+    names = fs16.readdirSync(dir).filter((name) => name.endsWith(".json"));
+  } catch {
+    return null;
+  }
+  for (const name of names.toSorted()) {
+    let parsed;
+    try {
+      parsed = JSON.parse(fs16.readFileSync(path35.join(dir, name), "utf8"));
+    } catch {
+      continue;
+    }
+    if (!isRecord5(parsed) || !Array.isArray(parsed.branches))
+      continue;
+    const branches = parsed.branches.filter(isRecord5);
+    const index = branches.findIndex((entry) => entry.branch === branch);
+    if (index < 0)
+      continue;
+    const entry = branches[index];
+    return {
+      name: str(parsed.name) ?? name.replace(/\.json$/u, ""),
+      index: index + 1,
+      size: branches.length,
+      parent: str(entry.parent),
+      pr: typeof entry.pr === "number" ? entry.pr : null
+    };
+  }
+  return null;
+}
+function buildHandoff(cwd, options = {}) {
+  const store = storeRoot(cwd);
+  if (!store.ok)
+    return store;
+  const read = readLedger(cwd);
+  if (!read.ok)
+    return read;
+  const ledger = read.value;
+  const branch = currentBranch2(cwd);
+  const head = headSha(cwd);
+  const base = defaultBase2(cwd);
+  let ahead = null;
+  let behind = null;
+  if (base && head) {
+    const counts = git2(cwd, ["rev-list", "--left-right", "--count", `${base}...HEAD`]);
+    const [left, right] = (counts ?? "").split(/\s+/u).map(Number);
+    if (Number.isFinite(left) && Number.isFinite(right)) {
+      behind = left;
+      ahead = right;
+    }
+  }
+  const mine = branch ? filterRows(ledger.rows, { branch }) : [];
+  const stack = branch ? stackPosition(store.value.root, branch) : null;
+  const pr = stack?.pr ?? mine.findLast((row) => row.pr !== undefined && PR_ROW_TYPES.has(row.type) && row.observer === "workit_cli")?.pr ?? null;
+  const check = branch ? checkVerdicts(cwd, branch, ledger.rows) : null;
+  const checkRows = mine.filter((row) => row.type === "check" && row.observer === "workit_cli" && str(row.name));
+  const latestChecks = new Map;
+  for (const row of checkRows)
+    latestChecks.set(str(row.name), row);
+  const tree = latestChecks.size ? worktreeTree(cwd)?.key ?? null : null;
+  const checks = [...latestChecks.entries()].map(([name, row]) => ({
+    name,
+    result: str(row.result),
+    fresh: tree !== null && row.tree === tree,
+    at: row.at
+  }));
+  const lastHandoffRow = mine.findLast((row) => row.type === "handoff");
+  const partial = {
+    store: { root: store.value.root, shared: store.value.shared, ledger: ledger.path },
+    branch,
+    head,
+    subject: head ? git2(cwd, ["log", "-1", "--format=%s", head]) : null,
+    base,
+    ahead,
+    behind,
+    dirty: dirtyState(cwd),
+    pr,
+    stack,
+    verdict: {
+      current: check?.current.basis ?? "none",
+      accepted: check?.accepted.accepted ?? false,
+      reasons: check?.accepted.reasons ?? ["no_verdict"],
+      verdicts: (check?.verdicts ?? []).map(({ verdict: row, ...rest }) => ({
+        ...rest,
+        summary: summarizeRow(row).summary
+      }))
+    },
+    checks,
+    rulings: mine.filter((row) => row.type === "ruling" && !row.superseded).slice(-5).map(summarizeRow),
+    recent: ledger.rows.slice(-(options.last ?? 10)).map(summarizeRow),
+    lastHandoff: lastHandoffRow ? {
+      at: lastHandoffRow.at,
+      note: str(lastHandoffRow.note),
+      next: str(lastHandoffRow.next) ?? ""
+    } : null,
+    note: options.note?.trim() || null,
+    skippedRows: ledger.skipped
+  };
+  const nextCommand = nextCommandFor(partial);
+  return {
+    ok: true,
+    value: { ...partial, nextCommand, next: options.next?.trim() || nextCommand }
+  };
+}
+var LEDGER_VERSION = 1, MAX_LINE_BYTES = 4096, VERDICT_RESULTS, PASSING, FAILING, VERDICT_KINDS, VERDICT_SURFACES, PR_ROW_TYPES, err = (code, error, unblock) => ({
+  ok: false,
+  code,
+  error,
+  ...unblock ? { unblock } : {}
+}), gitRun = (cwd, args, timeoutMs = GIT_TIMEOUTS.local) => {
+  const run = spawnSync14("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+    windowsHide: true,
+    maxBuffer: 256 * 1024 * 1024,
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: "0",
+      GIT_OPTIONAL_LOCKS: "0",
+      LC_ALL: "C",
+      LANGUAGE: "C"
+    }
+  });
+  return {
+    ok: run.status === 0,
+    stdout: run.stdout ?? "",
+    stderr: run.error ? String(run.error.message) : run.stderr ?? ""
+  };
+}, git2 = (cwd, args) => {
+  const run = gitRun(cwd, args);
+  const value = run.ok ? run.stdout.trim() : "";
+  return value ? value : null;
+}, safeRef = (value) => value.length > 0 && !value.startsWith("-"), NOT_A_REPO, newId2 = () => `${Date.now().toString(36)}-${randomBytes2(6).toString("hex")}`, NETWORK_FS_TYPES, isNetworkFsType = (type) => NETWORK_FS_TYPES.has(type >>> 0), onNetworkFs = (dir) => {
+  if (process.platform !== "linux")
+    return false;
+  try {
+    return isNetworkFsType(fs16.statfsSync(dir).type);
+  } catch {
+    return false;
+  }
+}, LOCK_WAIT_MS = 5000, LOCK_STALE_MS = 30000, LOCK_OWNER = "owner", lockToken = (lock) => {
+  try {
+    return fs16.readFileSync(path35.join(lock, LOCK_OWNER), "utf8");
+  } catch {
+    return null;
+  }
+}, lockAgeMs = (lock) => {
+  for (const target of [path35.join(lock, LOCK_OWNER), lock]) {
+    try {
+      return Date.now() - fs16.statSync(target).mtimeMs;
+    } catch {}
+  }
+  return null;
+}, ledgerLock, serialize = (row, now) => {
+  const full = { v: LEDGER_VERSION, id: newId2(), at: now.toISOString(), ...row };
+  return { full, line: `${JSON.stringify(full)}
+` };
+}, isRecord5 = (value) => typeof value === "object" && value !== null && !Array.isArray(value), str = (value) => typeof value === "string" ? value : null, normalizeActor = (value) => {
+  const actor = isRecord5(value) ? value : {};
+  return {
+    host: str(actor.host) ?? "unknown",
+    session: str(actor.session),
+    agentId: str(actor.agentId)
+  };
+}, isLiveVerdict = (row) => row.type === "verdict" && typeof row.result === "string" && !row.superseded, independenceReasons = (row, authors) => {
+  const reasons = [];
+  if (!row.actor.session)
+    reasons.push("no_session");
+  else if (authors.has(row.actor.session))
+    reasons.push("author_session");
+  if (row.self === true && !reasons.includes("no_session"))
+    reasons.push("self");
+  return reasons;
+}, common2 = (context, key) => ({
+  ...key,
+  actor: context.actor,
+  ...context.pr === undefined ? {} : { pr: context.pr },
+  ...context.supersedes ? { supersedes: context.supersedes } : {}
+}), noteKey = (context) => {
+  const branch = context.branch ?? currentBranch2(context.cwd);
+  return {
+    branch,
+    head: branch ? branchHead(context.cwd, branch) : headSha(context.cwd),
+    base: null,
+    baseSha: null,
+    patchId: null,
+    diffHash: null,
+    tree: null,
+    dirty: null
+  };
+}, required2 = (value, flag) => {
+  const text = value?.trim();
+  return text ? { ok: true, value: text } : err("invalid_input", `${flag} is required`);
+}, OBSERVED_ONLY, MAX_DIRTY_PATHS = 10, dirtyState = (cwd) => {
+  const run = gitRun(cwd, ["status", "--porcelain=v1", "-z", "--untracked-files=normal"], GIT_TIMEOUTS.worktree);
+  if (!run.ok)
+    return { dirty: false, files: 0, paths: [] };
+  const paths = [];
+  const entries = run.stdout.split("\x00");
+  for (let index = 0;index < entries.length; index += 1) {
+    const entry = entries[index];
+    if (entry.length < 4)
+      continue;
+    paths.push(entry.slice(3));
+    if (entry[0] === "R" || entry[0] === "C")
+      index += 1;
+  }
+  return { dirty: paths.length > 0, files: paths.length, paths: paths.slice(0, MAX_DIRTY_PATHS) };
+}, nextCommandFor = (brief) => {
+  const branchFlag = brief.branch ? ` --branch ${brief.branch}` : "";
+  const verify = `workit ledger verdict verified${branchFlag} --how "<method and evidence>"  (from a session that did not author the branch, with WORKIT_SESSION_ID set)`;
+  if (!brief.head)
+    return "make the first commit on this branch, then: workit handoff";
+  if (brief.dirty.dirty)
+    return `commit or stash the ${brief.dirty.files} changed file(s), then: workit handoff`;
+  const stale = brief.checks.find((check) => !check.fresh);
+  if (stale)
+    return `workit check ${stale.name}`;
+  const { verdict } = brief;
+  if (verdict.reasons.includes("failing_verdict"))
+    return `fix what the failing verdict found, then get a new independent verdict: ${verify}`;
+  if (!verdict.accepted)
+    return verify;
+  return brief.pr === null ? "workit pr create" : `workit pr status --pr ${brief.pr}`;
+};
+var init_ledger = __esm(() => {
+  init_rev();
+  VERDICT_RESULTS = [
+    "verified",
+    "tests-verified",
+    "type-check-only",
+    "blocked",
+    "failed"
+  ];
+  PASSING = new Set(["verified", "tests-verified", "type-check-only"]);
+  FAILING = new Set(["failed", "blocked"]);
+  VERDICT_KINDS = ["unit", "live", "perf", "review"];
+  VERDICT_SURFACES = ["ui", "cli", "api"];
+  PR_ROW_TYPES = new Set(["pr.created", "pr.status"]);
+  NOT_A_REPO = /not a git repository \(or any (of the parent directories|parent up to)/u;
+  NETWORK_FS_TYPES = new Set([
+    26985,
+    20859,
+    4266872130,
+    4283649346,
+    1702057286,
+    1397113167,
+    12805120,
+    16914839,
+    1196443219,
+    198183888
+  ]);
+  ledgerLock = {
+    acquire(lock) {
+      try {
+        fs16.mkdirSync(lock);
+      } catch (error) {
+        if (error.code === "EEXIST")
+          return null;
+        throw error;
+      }
+      const token = `${process.pid}-${randomBytes2(8).toString("hex")}`;
+      fs16.writeFileSync(path35.join(lock, LOCK_OWNER), token);
+      return token;
+    },
+    release(lock, token) {
+      if (lockToken(lock) !== token)
+        return false;
+      const tomb = `${lock}.release-${randomBytes2(6).toString("hex")}`;
+      try {
+        fs16.renameSync(lock, tomb);
+      } catch {
+        return false;
+      }
+      if (lockToken(tomb) !== token) {
+        try {
+          fs16.renameSync(tomb, lock);
+        } catch {}
+        return false;
+      }
+      fs16.rmSync(tomb, { recursive: true, force: true });
+      return true;
+    },
+    token: lockToken,
+    reap(lock, observed) {
+      const tomb = `${lock}.reap-${randomBytes2(6).toString("hex")}`;
+      try {
+        fs16.renameSync(lock, tomb);
+      } catch {
+        return false;
+      }
+      if (lockToken(tomb) === observed) {
+        fs16.rmSync(tomb, { recursive: true, force: true });
+        return true;
+      }
+      try {
+        fs16.renameSync(tomb, lock);
+      } catch {
+        fs16.rmSync(tomb, { recursive: true, force: true });
+      }
+      return false;
+    }
+  };
+  OBSERVED_ONLY = new Set(["check", ...PR_ROW_TYPES]);
+});
+
 // packages/workit-cli/src/verbs/ledger.ts
 var exports_ledger = {};
 __export(exports_ledger, {
   run: () => run18
 });
-var run18;
-var init_ledger = __esm(() => {
-  init_stub();
-  run18 = notImplemented("ledger", "S13");
+import { parseArgs } from "node:util";
+function targetBranch(io, rows, branch, pr) {
+  if (pr !== undefined) {
+    const resolved = branchForPr(io.cwd, rows, pr);
+    if (!resolved.ok)
+      return {
+        ok: false,
+        code: "invalid_input",
+        error: resolved.reason === "ambiguous" ? `cannot resolve PR ${pr} to a branch: ambiguous (${resolved.candidates.join(", ")})` : `cannot resolve PR ${pr} to a branch: no workit pr row records it and no fetched forge ref (refs/pull/${pr}/head) points at a local branch tip`,
+        unblock: "pass --branch <branch> instead, or fetch the PR ref"
+      };
+    if (branch !== undefined && branch !== resolved.branch)
+      return {
+        ok: false,
+        code: "invalid_input",
+        error: `PR ${pr} is branch ${resolved.branch}, not ${branch}`
+      };
+    return { ok: true, value: resolved.branch };
+  }
+  return { ok: true, value: branch ?? null };
+}
+async function run18(argv, io) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+  } catch (error) {
+    return usage3(io, error.message);
+  }
+  const { values } = parsed;
+  let positionals = parsed.positionals;
+  if (positionals[0] === "add") {
+    positionals = positionals.slice(1);
+    if (!["decision", "ruling", "verdict"].includes(positionals[0] ?? ""))
+      return usage3(io, "ledger add takes decision|ruling|verdict");
+  }
+  const [sub, ...rest] = positionals;
+  const pr = positiveInt(values.pr, "--pr");
+  if (pr instanceof Error)
+    return usage3(io, pr.message);
+  const last = positiveInt(values.last, "--last");
+  if (last instanceof Error)
+    return usage3(io, last.message);
+  const text = rest.join(" ");
+  if (sub === undefined)
+    return usage3(io, "missing subcommand");
+  if (!["decision", "ruling", "verdict", "list", "show", "check"].includes(sub))
+    return usage3(io, `unknown ledger subcommand "${sub}"`);
+  const ledger = readLedger(io.cwd);
+  if (!ledger.ok)
+    return failed(io, ledger);
+  const { rows } = ledger.value;
+  if (sub === "list" || sub === "show") {
+    if (rest.length)
+      return usage3(io, `unexpected argument: ${rest[0]}`);
+    const listed = filterRows(rows, {
+      branch: values.branch,
+      pr,
+      type: values.type,
+      last: last ?? 50
+    });
+    return emit(io, ok({ path: ledger.value.path, skipped: ledger.value.skipped, rows: listed }), (data) => data.rows.length ? data.rows.map((row) => {
+      const line = summarizeRow(row);
+      return `#${line.seq} ${line.at} ${line.type}${line.branch ? ` [${line.branch}]` : ""}${line.labels.length ? ` (${line.labels.join(", ")})` : ""}  ${line.summary}`;
+    }) : "ledger is empty");
+  }
+  const isRead = sub === "check" || sub === "verdict" && values.how === undefined && !VERDICT_RESULTS.includes(rest[0] ?? "");
+  if (isRead) {
+    if (rest.length > (sub === "verdict" ? 1 : 0))
+      return usage3(io, `unexpected argument: ${rest.at(-1)}`);
+    const target = targetBranch(io, rows, rest[0] ?? values.branch, pr);
+    if (!target.ok)
+      return failed(io, target);
+    const branch = target.value ?? currentBranch2(io.cwd);
+    if (!branch)
+      return emit(io, fail("invalid_input", "HEAD is detached; name the branch", {
+        unblock: "pass --branch <branch>"
+      }));
+    return emit(io, ok(checkVerdicts(io.cwd, branch, rows)), verdictLines);
+  }
+  const target = targetBranch(io, rows, values.branch, pr);
+  if (!target.ok)
+    return failed(io, target);
+  const context = {
+    cwd: io.cwd,
+    actor: actorFromEnv(io.env),
+    branch: target.value,
+    base: values.base ?? null,
+    ...pr === undefined ? {} : { pr },
+    ...values.supersedes ? { supersedes: values.supersedes } : {}
+  };
+  if (sub === "decision")
+    return fromResult(io, recordDecision(context, { what: text, why: values.why, refs: values.ref }), (row) => `recorded decision ${row.id}`);
+  if (sub === "ruling")
+    return fromResult(io, recordRuling(context, {
+      what: text,
+      why: values.why,
+      costIfWrong: values["cost-if-wrong"],
+      refs: values.ref
+    }), (row) => `recorded ruling ${row.id}`);
+  if (rest.length !== 1)
+    return usage3(io, `ledger verdict takes one result: ${VERDICT_RESULTS.join("|")}`);
+  return fromResult(io, recordVerdict(context, {
+    result: rest[0],
+    kind: values.kind,
+    how: values.how,
+    surface: values.surface ?? null,
+    self: values.self === true,
+    evidenceRefs: values.evidence
+  }), (row) => `recorded verdict ${row.id}: ${row.result} [${row.kind}] for ${row.branch} @ ${(row.head ?? "").slice(0, 12)}${row.self ? ` (self${row.selfReason === "no_session" ? ": WORKIT_SESSION_ID unset" : ""}; never accepted)` : ""}`);
+}
+var USAGE = "workit ledger decision|ruling|verdict|list|check ... (workit help ledger for the grammar)", OPTIONS, positiveInt = (value, flag) => {
+  if (value === undefined)
+    return;
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : new Error(`${flag} must be a positive integer`);
+}, failed = (io, result) => emit(io, fail(result.code, result.error, result.unblock ? { unblock: result.unblock } : {})), fromResult = (io, result, human) => result.ok ? emit(io, ok(result.value), human) : failed(io, result), usage3 = (io, error) => emit(io, fail("invalid_input", error, { unblock: USAGE })), verdictLines = (check) => {
+  const lines = [
+    `${check.branch} @ ${(check.head ?? "no commit").slice(0, 12)}: current: ${check.current.basis}${typeof check.current.verdict?.result === "string" ? ` (${check.current.verdict.result})` : ""}; ${check.accepted.accepted ? "accepted" : `not accepted (${check.accepted.reasons.join(", ")})`}`
+  ];
+  for (const entry of check.verdicts)
+    lines.push(`  ${entry.kind}: ${entry.basis}${entry.accepted ? ", accepted" : ` (${entry.reasons.join(", ")})`}  ${summarizeRow(entry.verdict).summary}`);
+  return lines;
+};
+var init_ledger2 = __esm(() => {
+  init_ledger();
+  init_rev();
+  init_output();
+  OPTIONS = {
+    why: { type: "string" },
+    "cost-if-wrong": { type: "string" },
+    ref: { type: "string", multiple: true },
+    how: { type: "string" },
+    kind: { type: "string" },
+    surface: { type: "string" },
+    evidence: { type: "string", multiple: true },
+    self: { type: "boolean" },
+    branch: { type: "string" },
+    base: { type: "string" },
+    pr: { type: "string" },
+    type: { type: "string" },
+    last: { type: "string" },
+    supersedes: { type: "string" },
+    json: { type: "boolean" }
+  };
 });
 
 // packages/workit-cli/src/verbs/handoff.ts
@@ -73087,24 +74178,92 @@ var exports_handoff = {};
 __export(exports_handoff, {
   run: () => run19
 });
+import { parseArgs as parseArgs2 } from "node:util";
+function human(brief) {
+  const lines = [
+    `branch: ${brief.branch ?? "(detached)"} @ ${short(brief.head)}${brief.subject ? ` ${brief.subject}` : ""}`
+  ];
+  if (brief.base)
+    lines.push(`base:   ${brief.base}${brief.ahead === null ? "" : ` (ahead ${brief.ahead}, behind ${brief.behind})`}`);
+  lines.push(brief.dirty.dirty ? `dirty:  ${brief.dirty.files} file(s): ${brief.dirty.paths.join(", ")}${brief.dirty.files > brief.dirty.paths.length ? ", …" : ""}` : "dirty:  clean");
+  if (brief.stack)
+    lines.push(`stack:  ${brief.stack.name} ${brief.stack.index}/${brief.stack.size}${brief.stack.parent ? ` on ${brief.stack.parent}` : ""}`);
+  if (brief.pr !== null)
+    lines.push(`pr:     #${brief.pr}`);
+  lines.push(`verdict: current ${brief.verdict.current}; ${brief.verdict.accepted ? "accepted" : `not accepted (${brief.verdict.reasons.join(", ")})`}`, ...brief.verdict.verdicts.map((entry) => `  ${entry.kind}: ${entry.basis}${entry.accepted ? ", accepted" : ` (${entry.reasons.join(", ")})`}  ${entry.summary}`));
+  if (brief.checks.length)
+    lines.push("checks:", ...brief.checks.map((check) => `  ${check.name}: ${check.result ?? "?"} (${check.fresh ? "fresh" : "stale"})`));
+  if (brief.rulings.length)
+    lines.push("rulings:", ...brief.rulings.map((row) => `  #${row.seq} ${row.summary}`));
+  if (brief.lastHandoff)
+    lines.push(`last handoff (${brief.lastHandoff.at}): ${brief.lastHandoff.next}${brief.lastHandoff.note ? ` (note: ${brief.lastHandoff.note})` : ""}`);
+  if (brief.recent.length)
+    lines.push("recent ledger:", ...brief.recent.map((row) => `  #${row.seq} ${row.type}${row.branch ? ` [${row.branch}]` : ""}${row.labels.length ? ` (${row.labels.join(", ")})` : ""}  ${row.summary}`));
+  if (brief.note)
+    lines.push(`note:   ${brief.note}`);
+  lines.push(`next:   ${brief.next}`);
+  if (brief.next !== brief.nextCommand)
+    lines.push(`next command: ${brief.nextCommand}`);
+  if (brief.recorded)
+    lines.push(`recorded handoff ${brief.recorded}`);
+  return lines;
+}
+async function resumeBrief(argv, io) {
+  let values;
+  try {
+    ({ values } = parseArgs2({
+      args: argv,
+      options: {
+        note: { type: "string" },
+        next: { type: "string" },
+        record: { type: "boolean" },
+        last: { type: "string" },
+        json: { type: "boolean" }
+      },
+      allowPositionals: false,
+      strict: true
+    }));
+  } catch (error) {
+    return emit(io, fail("invalid_input", error.message, { unblock: USAGE2 }));
+  }
+  const last = values.last === undefined ? 10 : Number(values.last);
+  if (!Number.isInteger(last) || last < 1)
+    return emit(io, fail("invalid_input", "--last must be a positive integer", { unblock: USAGE2 }));
+  const built = buildHandoff(io.cwd, {
+    last,
+    note: values.note ?? null,
+    next: values.next ?? null
+  });
+  if (!built.ok)
+    return emit(io, fail(built.code, built.error, built.unblock ? { unblock: built.unblock } : {}));
+  const data = built.value;
+  let recorded = null;
+  if (values.record) {
+    const row = recordHandoff({ cwd: io.cwd, actor: actorFromEnv(io.env), branch: data.branch }, { note: data.note, next: data.next });
+    if (!row.ok)
+      return emit(io, fail(row.code, row.error, { data: { ...data, recorded } }));
+    recorded = row.value.id;
+  }
+  return emit(io, ok({ ...data, recorded }), human);
+}
 async function run19(argv, io) {
   if (!argv.includes("--task"))
-    return brief(argv, io);
+    return resumeBrief(argv, io);
   await Promise.resolve().then(() => init_task());
   return runTaskCommand(["handoff", ...argv]);
 }
-var brief;
+var USAGE2 = "workit handoff [--note <text>] [--next <text>] [--record] [--last <n>] [--json]", short = (sha) => sha ? sha.slice(0, 12) : "no commit";
 var init_handoff = __esm(() => {
-  init_stub();
-  brief = notImplemented("handoff", "S13");
+  init_ledger();
+  init_output();
 });
 
 // packages/workit-cli/src/main.ts
-import path34 from "node:path";
+import path36 from "node:path";
 // packages/workit-cli/package.json
 var package_default = {
   name: "@brainervirus/workit-cli",
-  version: "2.2.0",
+  version: "2.2.2",
   private: false,
   description: "Workit CLI — setup wizard, doctor, and task control for agentic coding workflows",
   keywords: [
@@ -73284,15 +74443,14 @@ var VERBS = [
     name: "ledger",
     group: "delivery",
     usage: "workit ledger decision|ruling|verdict|list|check ...",
-    summary: "Record and query decisions, rulings and verdicts",
-    planned: "S13",
-    load: () => Promise.resolve().then(() => (init_ledger(), exports_ledger))
+    summary: "Record and query decisions, rulings and SHA-keyed verdicts (patch-id carry-over across rebases)",
+    load: () => Promise.resolve().then(() => (init_ledger2(), exports_ledger))
   },
   {
     name: "handoff",
     group: "delivery",
-    usage: "workit handoff --task <id>",
-    summary: "Export task state and compact destination context",
+    usage: "workit handoff [--note <t>] [--next <t>] [--record] | workit handoff --task <id>",
+    summary: "Print a resume brief (branch, HEAD, dirty state, verdict, rulings, next command); --task exports v1 task state",
     load: () => Promise.resolve().then(() => (init_handoff(), exports_handoff))
   }
 ];
@@ -73378,7 +74536,7 @@ var defaultIo = (json) => ({
 });
 async function main(argv, overrides = {}, options = {}) {
   const parsed = parseGlobals(argv);
-  const cwd = path34.resolve(overrides.cwd ?? process.cwd(), parsed.cwd ?? ".");
+  const cwd = path36.resolve(overrides.cwd ?? process.cwd(), parsed.cwd ?? ".");
   const io = { ...defaultIo(parsed.json), ...overrides, json: parsed.json, cwd };
   if (parsed.error)
     return emit(io, fail("invalid_input", parsed.error));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-cli",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "private": false,
   "description": "Workit CLI — setup wizard, doctor, and task control for agentic coding workflows",
   "keywords": [
@@ -37,9 +37,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@brainervirus/workit-core": "^2.2.1",
-    "@brainervirus/workit-cursor": "^2.2.1",
-    "@brainervirus/workit-opencode": "^2.2.1",
+    "@brainervirus/workit-core": "^2.3.0",
+    "@brainervirus/workit-cursor": "^2.3.0",
+    "@brainervirus/workit-opencode": "^2.3.0",
     "@inkjs/ui": "2.0.0",
     "ink": "7.1.1",
     "react": "19.2.8"