@brainervirus/workit-core 8.7.0 → 8.9.0

package/src/hooks/skill-nudge.ts

@@ -11,9 +11,6 @@
 // A session is nudged about one skill at most once (a marker per session
 // in the workspace store), never in a subagent, never once it loaded the skill.
 // Every failure answers "no nudge": hooks fail open.
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
 import {
   skillLoadWording,
   WORKIT_METHOD_SKILLS,
@@ -22,9 +19,9 @@ import {
   type WorkitSkill,
 } from "../core/skill-manifests";
 import { appendHookObserved, readLedger } from "../ledger";
-import { resolveStore } from "../store/paths";
 import type { HookDecision, HookInput, HostId } from "./protocol";
-import { inWorkitWorkspace, rawDelivery, rawGitPre } from "./raw-git";
+import { inWorkitWorkspace, rawDelivery, rawGitPre, workitInvocations } from "./raw-git";
+import { readSessionMarker, sessionMarkerFile, writeSessionMarker } from "./session-marker";
 import { segmentsOf, type ShellDialect } from "./shell-words";
 
 /** Skills the user starts; a nudge says to offer them, never to load them. */
@@ -105,35 +102,6 @@ export const promptTrigger = (prompt: string): { skill: WorkitSkill; trigger: st
   return null;
 };
 
-/** Per-session nudge state: skills nudged or loaded, so each nudges once. */
-type Marker = { nudged: string[]; loaded: string[] };
-
-/** The marker in the workspace's store (null outside one: nothing is nudged or recorded there). */
-const markerFile = (input: HookInput, session: string): string | null => {
-  const location = resolveStore(input.cwd);
-  if (location instanceof Error || !location.shared) return null;
-  const name = createHash("sha256").update(`${input.host}\0${session}`).digest("hex").slice(0, 32);
-  return path.join(location.dir, "hooks", `skills-${name}.json`);
-};
-
-const readMarker = (file: string): Marker => {
-  try {
-    const value = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<Marker>;
-    return { nudged: value.nudged ?? [], loaded: value.loaded ?? [] };
-  } catch {
-    return { nudged: [], loaded: [] };
-  }
-};
-
-const writeMarker = (file: string, marker: Marker): void => {
-  try {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(marker));
-  } catch {
-    // Fail open: without a marker a later nudge repeats.
-  }
-};
-
 /** Skills this session already loaded, from its `skill.loaded` rows. */
 const loadedSkills = (cwd: string, session: string): Set<string> => {
   const ledger = readLedger(cwd);
@@ -194,11 +162,11 @@ export function recordSkillLoad(
     const session = input.session.id;
     if (!skill || !session) return;
     if (!inWorkitWorkspace(input.cwd)) return;
-    const file = markerFile(input, session);
+    const file = sessionMarkerFile(input, session);
     if (!file) return;
-    const marker = readMarker(file);
+    const marker = readSessionMarker(file);
     if (marker.loaded.includes(skill)) return;
-    writeMarker(file, { ...marker, loaded: [...marker.loaded, skill] });
+    writeSessionMarker(file, { ...marker, loaded: [...marker.loaded, skill] });
     if (loadedSkills(input.cwd, session).has(skill)) return;
     appendHookObserved(input.cwd, {
       type: "skill.loaded",
@@ -218,12 +186,12 @@ const nudgeOnce = (
   skill: WorkitSkill,
   line: string,
 ): string | null => {
-  const file = markerFile(input, session);
+  const file = sessionMarkerFile(input, session);
   if (!file) return null;
-  const marker = readMarker(file);
+  const marker = readSessionMarker(file);
   if (marker.nudged.includes(skill) || marker.loaded.includes(skill)) return null;
   if (loadedSkills(input.cwd, session).has(skill)) return null;
-  writeMarker(file, { ...marker, nudged: [...marker.nudged, skill] });
+  writeSessionMarker(file, { ...marker, nudged: [...marker.nudged, skill] });
   return line;
 };
 
@@ -240,11 +208,22 @@ const promptLoads = (prompt: string): string | null =>
   /^\s*Load the (workit-[a-z-]+) skill with the skill tool\b/.exec(prompt)?.[1] ??
   null;
 
+/**
+ * A prompt that relays another agent's words, not the user's: Claude Code
+ * delivers subagent hand-backs, teammate messages and background-task
+ * notifications through UserPromptSubmit. A reviewer's report that says
+ * "regressed" is not a request for workit-debug.
+ */
+export const relayedMessage = (prompt: string): boolean =>
+  /^\s*(?:Another Claude session sent a message\b|<agent-message\s+from=|\[SYSTEM NOTIFICATION\b|<task-notification>)/.test(
+    prompt,
+  );
+
 /** A main session's prompt in a Workit workspace: one advisory line naming the skill it asks for. */
 export function promptNudge(input: HookInput, prompt: string | null | undefined): string | null {
   try {
     const session = input.session.id;
-    if (!prompt || !session || input.session.agentId) return null;
+    if (!prompt || !session || input.session.agentId || relayedMessage(prompt)) return null;
     const loads = promptLoads(prompt);
     if (loads) {
       // The prompt already loads its skill; record it, never nudge.
@@ -265,35 +244,13 @@ export function promptNudge(input: HookInput, prompt: string | null | undefined)
 }
 
 const WORKIT_DELIVERY = /^(?:pr (?:create|merge)|ci wait|git push)\b/;
-const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
-const LAUNCHERS = new Set([
-  "npx",
-  "bunx",
-  "pnpx",
-  "-y",
-  "--yes",
-  "pnpm",
-  "dlx",
-  "exec",
-  "env",
-  "sudo",
-  "command",
-]);
-
-/** Does a segment list run a workit delivery verb (also inside `bash -c '…'`)? */
-const runsWorkitDelivery = (command: string, dialect: ShellDialect, depth = 0): boolean =>
-  segmentsOf(command, dialect).some(({ words }) => {
-    // The command word, past env assignments and package runners (`npx -y`).
-    const at = words.findIndex((word) => !/^\w+=/.test(word) && !LAUNCHERS.has(word));
-    if (at >= 0 && /(?:^|[\\/])workit(?:\.exe)?$|^@brainervirus\/workit-cli$/.test(words[at])) {
-      const args = words.slice(at + 1);
-      if (args.some((arg) => arg === "--help" || arg === "-h" || arg === "--dry-run")) return false;
-      return WORKIT_DELIVERY.test(args.join(" "));
-    }
-    const shell = SHELLS.has(words[at]?.split(/[\\/]/).at(-1) ?? "");
-    const script = shell && words[at + 1] === "-c" ? words[at + 2] : undefined;
-    return depth < 3 && script !== undefined && runsWorkitDelivery(script, "posix", depth + 1);
-  });
+/** Does the command run a workit delivery verb (also inside `bash -c '…'`), never help or a dry run? */
+const runsWorkitDelivery = (command: string, dialect: ShellDialect): boolean =>
+  workitInvocations(command, dialect).some(
+    (args) =>
+      !args.some((arg) => arg === "--help" || arg === "-h" || arg === "--dry-run") &&
+      WORKIT_DELIVERY.test(args.join(" ")),
+  );
 
 /**
  * Does the command deliver in a Workit workspace: a push, a PR/MR create or

package/src/hooks/stop.ts

@@ -0,0 +1,308 @@
+// 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;
+//   (c) verdict: the session opened the PR (or verified delivery) but the
+//       head carries no accepted non-author verdict.
+// 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 and local git only (no forge call), and every failure allows
+// the stop.
+import { spawnSync } from "node:child_process";
+import { resolveAutonomy } from "../autonomy";
+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";
+
+const NONE: HookDecision = { kind: "none" };
+
+export type StopObligation = {
+  kind: "unpushed" | "checks" | "verdict";
+  /** What is left, with the workit command that clears it. */
+  reason: string;
+};
+
+/** 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 = (
+  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;
+  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)" : ""}.`,
+  };
+};
+
+/** (c) Delivered by this session, yet no accepted non-author verdict on the head. */
+const unverified = (
+  cwd: string,
+  branch: string,
+  all: readonly ReadRow[],
+  descriptor: HostDescriptor,
+): StopObligation | null => {
+  const check = checkVerdicts(cwd, branch, all);
+  if (check.accepted.accepted || check.accepted.reasons.includes("failing_verdict")) return null;
+  const has = check.review === "self-reviewed" ? "only a self verdict" : "no current verdict";
+  const verifier = `${descriptor.subagents.agentPrefix}verifier`;
+  return {
+    kind: "verdict",
+    reason: `the head ${short(check.head)} of ${branch}, which this session delivered, has ${has}: if no verifier is already running on it, 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.`,
+  };
+};
+
+/** 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;
+    const ledger = readLedger(input.cwd);
+    if (!ledger.ok) return null;
+    const all = ledger.value.rows;
+    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 endpoint = resolveAutonomy(input.cwd).effectiveEndpoint;
+    if (endpoint !== "commit") {
+      const left = unpushed(input.cwd, branch, endpoint, commits, mergedHeads(rows));
+      if (left) return left;
+    }
+    const pr = openPr(rows);
+    if ((endpoint === "green" || endpoint === "merged") && pr !== null && head) {
+      const left = redChecks(rows, pr, head, endpoint);
+      if (left) return left;
+    }
+    return delivered ? unverified(input.cwd, branch, all, descriptor) : 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);
+  return left
+    ? {
+        kind: "continue",
+        reason: `Workit: before stopping, ${left.reason} If this cannot be done now, say so to the user and stop.`,
+      }
+    : NONE;
+}

package/src/ledger.ts

@@ -1801,6 +1801,9 @@ export function summarizeRow(row: ReadRow): RowSummary {
     case "pr.created":
       summary = `#${row.pr ?? "?"} -> ${text("base")} at ${(row.head ?? "?").slice(0, 12)}${row.created === false ? " (existing)" : ""}`;
       break;
+    case "pr.status":
+      summary = `#${row.pr ?? "?"} ${text("state") && text("state") !== "open" ? `${text("state")} ` : ""}checks ${text("checks") || "?"} at ${(row.head ?? "?").slice(0, 12)}`;
+      break;
     case "pr.merged":
       summary = `#${row.pr ?? "?"} ${text("method")} at ${(row.head ?? "?").slice(0, 12)}${text("mergeSha") ? ` -> ${text("mergeSha").slice(0, 12)}` : ""}`;
       break;