@brainervirus/workit-core 8.18.0 → 8.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.18.0",
+  "version": "8.19.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/hooks/handle.ts

@@ -8,7 +8,7 @@ import {
 import type { HostDescriptor, Support } from "./descriptor";
 import { branchGuidance } from "../core/branch";
 import { workspaceTrailers } from "../core/workspaces";
-import { recordIssuedSession } from "../host-session";
+import { judgeBranch, recordIssuedSession, verdictCommand } from "../host-session";
 import { heavyDenial, heavyGate, rewriteNote, splitDenial } from "./heavy-gate";
 import { shellPolicy } from "./policy";
 import {
@@ -114,9 +114,15 @@ const subagentStartText = (
   // and only with the token it hands to this subagent alone.
   // (An isolated judge's text is rebuilt with cwd "": the hook's own cwd then.)
   // Issued once: a replayed SubagentStart for the same id gets no token.
-  const token = session ? recordIssuedSession(input.cwd || process.cwd(), session, own) : null;
-  const flags = token ? `--session ${own} --token ${token}` : `--session ${own}`;
-  return `${readOnly} Its own Workit session is ${own}: record verdicts with \`workit ledger verdict <result> ${flags} ...\` so the ledger tells it apart from the author.${token ? " The token is this subagent's alone: never write it into a report, a file or a commit. --token needs a workit CLI at least as new as this plugin; if the CLI answers that --token is an unknown option, update the workit CLI (workit upgrade --cli) and record again." : ""}`;
+  const cwd = input.cwd || process.cwd();
+  const token = session ? recordIssuedSession(cwd, session, own) : null;
+  // Already issued: without its token the id is refused (unbound_session).
+  if (session && !token)
+    return `${readOnly} ${own} was already issued to an earlier subagent, so no token is handed out again and a verdict under it would be refused (unbound_session). Record no verdict as ${own}: spawn a fresh verifier or reviewer, which gets its own session and token.`;
+  const judge = event.agentType.endsWith("reviewer") ? "reviewer" : "verifier";
+  const line = verdictCommand({ branch: judgeBranch(cwd), judge, session: own, token });
+  const pick = judge === "verifier" ? ", --kind live when you drove the real surface" : "";
+  return `${readOnly} Its own Workit session is ${own}, so the ledger tells its verdicts apart from the author's. Record the verdict with exactly this command (pick the result${pick}, name the candidate branch if it differs, say what you ran): \`${line}\`.${token ? " The token is this subagent's alone: never write it into a report, a file or a commit. --token needs a workit CLI at least as new as this plugin; if the CLI answers that --token is an unknown option, update the workit CLI (workit upgrade --cli) and record again." : ""}`;
 };
 
 export function handleHook(input: HookInput, deps: HookDeps): HookDecision {

package/src/host-session.ts

@@ -10,7 +10,9 @@
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { isProtectedTarget } from "./core/branch";
 import { resolveStateDir } from "./core/logger";
+import { currentBranch } from "./git/rev";
 import { resolveStore } from "./store/paths";
 
 export type HostSession = { host: string | null; session: string | null };
@@ -217,6 +219,46 @@ export function recordIssuedSession(cwd: string, lead: string, issued: string):
   }
 }
 
+/**
+ * The branch a judge spawned from `cwd` most likely verifies: the checkout's
+ * branch, or null on a detached HEAD or a protected branch (a lead on `main`
+ * fanning out names the candidate in its brief, never its own branch).
+ */
+export function judgeBranch(cwd: string): string | null {
+  const branch = currentBranch(cwd);
+  return branch && !isProtectedTarget(cwd, branch) ? branch : null;
+}
+
+/**
+ * The exact verdict command a verifier or reviewer runs, filled in (#271
+ * S2a). `--token=` keeps a token from ever parsing as a flag. Hosts whose
+ * child shell carries its own session (OpenCode, Pi) pass no session.
+ * `--kind` is always named: left out, the CLI records `review`.
+ */
+export function verdictCommand(options: {
+  branch: string | null;
+  judge: "verifier" | "reviewer" | null;
+  session?: string | null;
+  token?: string | null;
+}): string {
+  const kind =
+    options.judge === "verifier"
+      ? "<live|unit>"
+      : options.judge === "reviewer"
+        ? "review"
+        : "<live|unit|review>";
+  return [
+    "workit ledger verdict <verified|failed|blocked>",
+    `--kind ${kind}`,
+    `--branch ${options.branch ?? "<branch>"}`,
+    options.session ? `--session ${options.session}` : null,
+    options.token ? `--token=${options.token}` : null,
+    '--how "<what you ran and saw>"',
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
 /** Keep the newest ISSUED_PER_LEAD ids of one lead (and their token hashes); `own` is never pruned. */
 function pruneIssued(dir: string, own: string, tokens: string): void {
   try {