@workit-dev/core 0.0.1 → 1.0.0

package/src/hooks/stop.ts

@@ -0,0 +1,408 @@
+// Stop control (ledger decision "stop control: option A, nudge once"): when
+// the main agent ends its turn with an obligation the ledger or git can
+// prove unmet, the host continues it once with a reason naming the
+// obligation and the workit command that clears it. The obligations, for the
+// session's branch (the checked-out branch, on which this session recorded a
+// commit or opened a PR):
+//   (a) unpushed: a commit this session recorded, not on the push remote,
+//       while the effective endpoint is pr, green or merged;
+//   (b) checks: the branch's open PR has failing or pending checks recorded
+//       for its current head (`pr.status` rows) while the endpoint is green
+//       or merged; a live `workit ci wait` on that PR and head (ci-waiter.ts),
+//       often moved to the background, is in flight: the stop is allowed
+//       with a notice instead, and the wait re-invokes the lead when it ends;
+//   (c) verdict: the session opened the PR (or verified delivery) but the
+//       head lacks the verdict the policy asks for, while the endpoint is
+//       green or merged (a PR opens without one). Under `verification:
+//       proportional` (the default) the review lane of the head decides
+//       (core/policy/lane.ts): none owes nothing, self the author's own
+//       `--self` verdict, focused and full an accepted non-author verdict.
+//       Under `self`: the author's own at normal risk; at high risk or under
+//       `independent`: a non-author one, and not raised when the task's
+//       latest judgment records no behavior change at normal risk
+//       (policy/derive.ts asks for none either). Never raised while a
+//       verifier or reviewer this lead started still runs.
+// Each obligation blocks once per head and session (a marker keyed by kind
+// and head), not once per turn.
+// A branch that landed owes nothing: a recorded merge (`workit pr merge`, or
+// `pr status`/`ci wait` seeing the forge report it merged) of HEAD or of a
+// head that contains this session's commits, or, with no merge recorded, an
+// upstream that is gone. Its remote branch may be deleted, and an
+// `--unverified` merge was the user's call.
+// A stop is never blocked: in a subagent, outside a Workit workspace, when
+// the host says this stop already follows a continuation (one continue per
+// turn), or when the agent's last message asks the user a question. Reads
+// the ledger, local git and the ci-wait marker only (no forge call), and
+// every failure allows the stop.
+import { spawnSync } from "node:child_process";
+import { resolveAutonomy, type VerificationMode } from "../autonomy";
+import { liveCiWaiter, type CiWaiter } from "../ci-waiter";
+import { currentJudgment } from "../core/policy/current-judgment";
+import { branchLane, laneNeed } from "../core/policy/lane";
+import { currentBranch, pushRemoteName } from "../git/rev";
+import { checkVerdicts, readLedger, type ReadRow } from "../ledger";
+import type { HostDescriptor } from "./descriptor";
+import type { HookDecision, HookInput } from "./protocol";
+import { guardedBranch, inWorkitWorkspace } from "./raw-git";
+import { readSessionMarker, sessionMarkerFile, updateSessionMarker } from "./session-marker";
+
+const NONE: HookDecision = { kind: "none" };
+
+export type StopObligation = {
+  kind: "unpushed" | "checks" | "verdict";
+  /** What is left, with the workit command that clears it. */
+  reason: string;
+  /** HEAD when it was found: with the kind, the once-per-head key. */
+  head?: string | null;
+  /** A live `workit ci wait` on the PR and head: the checks are in flight, not owed. */
+  waiter?: CiWaiter;
+};
+
+/** A question mark (Latin, full-width, Arabic) ending a sentence, or Spanish's opening one. */
+const QUESTION = /[?？؟](?=[\s*_`"')\]>]*(?:\s|$))|¿/;
+/** An offer or a request for permission. */
+const OFFER =
+  /\b(?:let me know|want me to|should I|shall I|would you like|do you want|if you(?:'d| would) like|may I|can I go ahead)\b/i;
+/** A `[y/N]`, `(y/n)` or `[Y/n]` prompt. */
+const YES_NO = /[[(]\s*y(?:es)?\s*\/\s*n(?:o)?\s*[\])]/i;
+/** A list item: `- a`, `* a`, `1. a`, `2) a`, `a) a`. */
+const LIST_ITEM = /^\s*(?:[-*+•]|\d+[.)]|[a-z][.)])\s+/i;
+
+/**
+ * Does the message end by asking the user something? The last two
+ * paragraphs (past code blocks and a trailing option list) are read for a
+ * question mark, an offer ("want me to", "shall I", "let me know") or a
+ * yes/no prompt: a stop that waits on the user is never blocked, so this
+ * errs towards "yes".
+ */
+export const asksUser = (message: string | null | undefined): boolean => {
+  if (!message) return false;
+  const paragraphs = message
+    .replace(/```[\s\S]*?(?:```|$)/g, "\n\n")
+    .split(/\n\s*\n/)
+    .map((paragraph) => paragraph.trim())
+    .filter(Boolean);
+  // A trailing option list belongs to the question before it.
+  while (
+    paragraphs.length > 1 &&
+    paragraphs
+      .at(-1)!
+      .split("\n")
+      .every((line) => LIST_ITEM.test(line))
+  )
+    paragraphs.pop();
+  const tail = paragraphs.slice(-2).join("\n");
+  return QUESTION.test(tail) || OFFER.test(tail) || YES_NO.test(tail);
+};
+
+const short = (sha: string | null | undefined) => (sha ?? "?").slice(0, 12);
+
+/** A git command's output lines, or null when it fails. */
+const gitList = (cwd: string, args: string[]): string[] | null => {
+  const run = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 3_000,
+    windowsHide: true,
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: "0",
+      GIT_OPTIONAL_LOCKS: "0",
+      LC_ALL: "C",
+    },
+  });
+  return run.status === 0 ? run.stdout.split("\n").filter(Boolean) : null;
+};
+
+const gitLine = (cwd: string, args: string[]): string | null => gitList(cwd, args)?.[0] ?? null;
+
+const sessionOf = (row: ReadRow): string | null =>
+  (typeof row.session === "string" ? row.session : null) ?? row.actor.session;
+
+/**
+ * The branch's open PR: the newest one the CLI opened or observed
+ * (`pr.created`, `pr.status`), unless it was merged since.
+ */
+/** A `pr.status` row's PR state; rows written before it was recorded are open. */
+const prState = (row: ReadRow): string => (typeof row.state === "string" ? row.state : "open");
+
+/** A CLI row saying the PR ended: `workit pr merge`, or the forge reporting it merged or closed. */
+const ended = (row: ReadRow): boolean =>
+  row.observer === "workit_cli" &&
+  (row.type === "pr.merged" || (row.type === "pr.status" && prState(row) !== "open"));
+
+const openPr = (rows: readonly ReadRow[]): number | null => {
+  const seen = rows.findLast(
+    (row) =>
+      (row.type === "pr.created" || row.type === "pr.status") &&
+      row.observer === "workit_cli" &&
+      typeof row.pr === "number",
+  );
+  if (!seen || ended(seen)) return null;
+  const closed = rows.some((row) => ended(row) && row.pr === seen.pr && row.seq > seen.seq);
+  return closed ? null : (seen.pr as number);
+};
+
+/**
+ * The heads the ledger records as merged: `workit pr merge` (`pr.merged`), or
+ * the forge reporting the PR merged (`pr.status` state merged, as `workit pr
+ * status` and `workit ci wait` record a merge done in the forge UI). A PR
+ * closed without merging is not one. Newest last, at most three.
+ */
+const mergedHeads = (rows: readonly ReadRow[]): string[] =>
+  [
+    ...new Set(
+      rows
+        .filter(
+          (row) =>
+            row.observer === "workit_cli" &&
+            typeof row.head === "string" &&
+            (row.type === "pr.merged" || (row.type === "pr.status" && prState(row) === "merged")),
+        )
+        .map((row) => row.head as string),
+    ),
+  ].slice(-3);
+
+/** Is `sha` a commit in the local object store? */
+const localCommit = (cwd: string, sha: string): boolean =>
+  /^[0-9a-f]{7,64}$/.test(sha) && gitList(cwd, ["cat-file", "-e", `${sha}^{commit}`]) !== null;
+
+/** The branch's configured upstream was deleted on the remote and pruned. */
+const upstreamGone = (cwd: string, branch: string): boolean =>
+  gitLine(cwd, ["for-each-ref", "--format=%(upstream:track)", `refs/heads/${branch}`]) === "[gone]";
+
+/**
+ * Has the branch landed? A recorded merge (`mergedHeads`) of the current
+ * HEAD, or of a head that already contains every commit of this session on
+ * HEAD: the merge record and the branch both say done, so nothing is left to
+ * push (the remote branch may be deleted) or to verify (an `--unverified`
+ * merge was the user's call). With no merge recorded, an upstream that is
+ * gone (the forge deleted the merged branch and a fetch pruned it) says the
+ * same. New commits of this session after a recorded merge are not landed.
+ */
+const landed = (
+  cwd: string,
+  branch: string,
+  rows: readonly ReadRow[],
+  head: string | null,
+  mine: ReadonlySet<string>,
+): boolean => {
+  if (!head) return false;
+  const merged = mergedHeads(rows);
+  if (merged.length === 0) return upstreamGone(cwd, branch);
+  if (merged.includes(head)) return true;
+  if (mine.size === 0) return false;
+  return merged.some((at) => {
+    // Commits on HEAD the merged head lacks; null when it is not a local commit.
+    const after = gitList(cwd, ["rev-list", `--max-count=${UNPUSHED_SCAN}`, "HEAD", "--not", at]);
+    return after !== null && !after.some((sha) => mine.has(sha));
+  });
+};
+
+/** How far back (a) looks for unpushed commits. */
+const UNPUSHED_SCAN = 500;
+
+/**
+ * (a) This session's recorded commits on HEAD that neither the push remote
+ * nor a recorded merge holds. Another session's or the user's commits never
+ * count, nor do commits already merged before the branch was reused.
+ */
+const unpushed = (
+  cwd: string,
+  branch: string,
+  endpoint: string,
+  mine: ReadonlySet<string>,
+  merged: readonly string[],
+): StopObligation | null => {
+  const remote = pushRemoteName(cwd, branch);
+  if (!remote || mine.size === 0) return null;
+  const listed = gitList(cwd, [
+    "rev-list",
+    `--max-count=${UNPUSHED_SCAN}`,
+    "HEAD",
+    "--not",
+    `--remotes=${remote}`,
+    ...merged.filter((sha) => localCommit(cwd, sha)),
+  ]);
+  const count = (listed ?? []).filter((sha) => mine.has(sha)).length;
+  if (count === 0) return null;
+  return {
+    kind: "unpushed",
+    reason: `${branch} has ${count} commit(s) of this session not on ${remote}, and this workspace's endpoint is \`${endpoint}\` (\`workit grant show\`): push them with \`workit git push\`${endpoint === "pr" ? ", then open or update the PR (`workit pr create --fill`)" : ""}.`,
+  };
+};
+
+/** (b) The open PR's checks, as last recorded for the current head. */
+const redChecks = (
+  cwd: string,
+  rows: readonly ReadRow[],
+  pr: number,
+  head: string,
+  endpoint: string,
+): StopObligation | null => {
+  const status = rows.findLast(
+    (row) => row.type === "pr.status" && row.observer === "workit_cli" && row.pr === pr,
+  );
+  const state = status && status.head === head && prState(status) === "open" ? status.checks : null;
+  if (state !== "failing" && state !== "pending") return null;
+  const waiter = liveCiWaiter(cwd, pr, head);
+  if (waiter)
+    return {
+      kind: "checks",
+      waiter,
+      reason: `a \`workit ci wait\` for PR #${pr} at ${short(waiter.head ?? head)} is in flight (pid ${waiter.pid}, until ${new Date(waiter.deadline).toISOString()}); its result re-invokes you when it ends, so do not start another wait.`,
+    };
+  return {
+    kind: "checks",
+    reason: `PR #${pr}'s checks were last seen ${state} at ${short(head)}, and this workspace's endpoint is \`${endpoint}\`: run \`workit ci wait --pr ${pr}\`${state === "failing" ? " after fixing the failures `workit pr status` lists (then push)" : ""}.`,
+  };
+};
+
+/**
+ * The base the branch's PR targets: the newest the forge reported (a
+ * `pr.status` row, so a PR retargeted on the forge is read against its
+ * current base), else the one it was opened with (`pr.created`), else null
+ * (the default base). Read from the ledger: the hook never calls the forge.
+ */
+const prBase = (rows: readonly ReadRow[]): string | null => {
+  const seen = rows.findLast(
+    (row) =>
+      (row.type === "pr.status" || row.type === "pr.created") &&
+      row.observer === "workit_cli" &&
+      typeof row.base === "string",
+  );
+  return typeof seen?.base === "string" ? seen.base : null;
+};
+
+/**
+ * (c) Delivered by this session, yet the head lacks the verdict the policy
+ * asks for. Under `verification: proportional` the review lane of the head
+ * decides (core/policy/lane.ts): none owes nothing, self the author's own,
+ * focused and full a non-author one. Under `self`, the author's own at
+ * normal risk; under `independent` or at high risk, a non-author one.
+ */
+const unverified = (
+  cwd: string,
+  branch: string,
+  all: readonly ReadRow[],
+  descriptor: HostDescriptor,
+  verification: VerificationMode,
+  head: string | null,
+): StopObligation | null => {
+  const check = checkVerdicts(cwd, branch, all);
+  if (check.accepted.accepted || check.accepted.reasons.includes("failing_verdict")) return null;
+  const judgment = currentJudgment(cwd);
+  const high = judgment?.riskTier === "high";
+  let independent: boolean;
+  if (verification === "proportional") {
+    const lane = branchLane(cwd, {
+      base: prBase(all.filter((row) => row.branch === branch)),
+      head,
+      judgment,
+    });
+    const need = laneNeed(lane.lane);
+    if (need === "none") return null;
+    independent = need === "non-author";
+  } else {
+    // Like policy/derive.ts: a verdict is asked for a behavior change or high
+    // risk. A recorded judgment with neither (docs only) owes none.
+    if (judgment && !judgment.behaviorChange && !high) return null;
+    independent = verification === "independent" || high;
+  }
+  if (!independent && check.review === "self-reviewed") return null;
+  const has = check.review === "self-reviewed" ? "only a self verdict" : "no current verdict";
+  const verifier = `${descriptor.subagents.agentPrefix}verifier`;
+  const how = independent
+    ? `hand it to a session that did not author it (the ${verifier} agent records \`workit ledger verdict <result> --branch ${branch} --how "<evidence>"\`), or tell the user it is unverified. Never record a verdict on your own work as independent.`
+    : `after an observed passing \`workit check test\`, record your own: \`workit ledger verdict tests-verified --self --branch ${branch} --how "<what you ran>"\` (shown as self-reviewed), or tell the user it is unverified.`;
+  return {
+    kind: "verdict",
+    reason: `the head ${short(check.head)} of ${branch}, which this session delivered, has ${has}, and this change needs ${independent ? "an independent verdict" : "a verdict (your own is enough)"}: ${how}`,
+  };
+};
+
+/** The first unmet obligation for the session's branch, or null. Never throws. */
+export function stopObligation(
+  input: HookInput,
+  descriptor: HostDescriptor,
+): StopObligation | null {
+  try {
+    const session = input.session.id;
+    // Outside a Workit workspace there is no ledger either; the check only
+    // spares every other repository's Stop the git and ledger reads below.
+    if (!session || input.session.agentId || !inWorkitWorkspace(input.cwd)) return null;
+    const branch = currentBranch(input.cwd);
+    if (!branch || guardedBranch(input.cwd, branch)) return null;
+    // Read with the hash chain: a hand-appended row neither creates nor
+    // clears an obligation, and verdicts are judged with integrity (N1).
+    const ledger = readLedger(input.cwd, { integrity: true });
+    if (!ledger.ok) return null;
+    const all = ledger.value.rows.filter((row) => row.integrity !== "unverified");
+    const rows = all.filter((row) => row.branch === branch);
+    const mine = rows.filter((row) => sessionOf(row) === session);
+    const commits = new Set(
+      mine
+        .filter((row) => row.type === "commit.recorded")
+        .map((row) => (typeof row.sha === "string" ? row.sha : row.head))
+        .filter((sha): sha is string => typeof sha === "string"),
+    );
+    const delivered = mine.some(
+      (row) =>
+        row.observer === "workit_cli" &&
+        (row.type === "pr.created" || row.type === "delivery.verified"),
+    );
+    if (commits.size === 0 && !delivered) return null;
+    const head = gitLine(input.cwd, ["rev-parse", "HEAD"]);
+    if (landed(input.cwd, branch, rows, head, commits)) return null;
+    const autonomy = resolveAutonomy(input.cwd);
+    const endpoint = autonomy.effectiveEndpoint;
+    if (endpoint !== "commit") {
+      const left = unpushed(input.cwd, branch, endpoint, commits, mergedHeads(rows));
+      if (left) return { ...left, head };
+    }
+    const pr = openPr(rows);
+    if ((endpoint === "green" || endpoint === "merged") && pr !== null && head) {
+      const left = redChecks(input.cwd, rows, pr, head, endpoint);
+      if (left) return { ...left, head };
+    }
+    // A PR opens without a verdict: only green and merged need one.
+    if (!delivered || (endpoint !== "green" && endpoint !== "merged")) return null;
+    const left = unverified(input.cwd, branch, all, descriptor, autonomy.verification, head);
+    return left ? { ...left, head } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The stop decision: continue once with the obligation, or allow. A stop
+ * that follows a continuation (`stopHookActive`), a subagent's stop, and a
+ * stop whose last message asks the user something are always allowed. So is
+ * a stop whose last message is unknown: it may be a question.
+ */
+export function stopDecision(input: HookInput, descriptor: HostDescriptor): HookDecision {
+  const event = input.event;
+  if (event.kind !== "stop" || event.stopHookActive) return NONE;
+  if (!event.lastMessage?.trim() || asksUser(event.lastMessage)) return NONE;
+  const left = stopObligation(input, descriptor);
+  if (!left) return NONE;
+  if (left.waiter) return { kind: "notice", userMessage: `Workit: ${left.reason}` };
+  // Once per head and obligation for the session, and no verdict nag while a
+  // verifier or reviewer this lead started is still running.
+  const session = input.session.id;
+  const file = session ? sessionMarkerFile(input, session) : null;
+  const marker = file ? readSessionMarker(file) : null;
+  if (left.kind === "verdict" && marker && marker.judges.length > 0) return NONE;
+  const key = `${left.kind}:${left.head ?? ""}`;
+  if (file && marker) {
+    if (marker.stops.includes(key)) return NONE;
+    updateSessionMarker(file, (fresh) => ({
+      ...fresh,
+      stops: [...fresh.stops, key],
+    }));
+  }
+  return {
+    kind: "continue",
+    reason: `Workit: before stopping, ${left.reason} If this cannot be done now, say so to the user and stop.`,
+  };
+}