@brainervirus/workit-core 8.9.1 → 8.10.0

package/package.json

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

package/skills/workit-fanout/references/brief.md

@@ -25,7 +25,7 @@ REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,
   each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),
   anything out of scope as a follow-up, not a diff.
 STANDING: <the standing orders, verbatim: `workit ledger standing add` records each one>
-  export WORKIT_SESSION_ID=<lead>-w<n>   (set by the lead; a verifier brief gets <lead>-v<n>)
+  export WORKIT_SESSION_ID=<lead>-w<n>   (set by the lead for a worker's commits; a verifier brief sets none: the host derives it)
 ```
 
 ## Worked example

package/skills/workit-fanout/references/orchestration.md

@@ -72,12 +72,22 @@ Which session id a verdict carries, per host:
 
 - Claude Code: subagents inherit your `WORKIT_SESSION_ID`, so the
   SubagentStart hook names each `verifier` and `reviewer` its own session
-  (`<lead>:<agent id>`), passed as `--session`; that one wins over any
-  `<lead>-v<n>` in a brief. An `implementer` uses the session its brief
-  exports for its workit commands.
-- Other hosts: the session the brief sets wins: `export
-  WORKIT_SESSION_ID=<lead>-w-<slice>` from `workit fanout brief` for a
-  worker, `<lead>-v<n>` (or `--as verifier`) for a verifier you start.
+  (`<lead>:<agent id>`), passed exactly as `--session`: the hook records the
+  ids it issues, and only those are accepted. An `implementer` uses the
+  session its brief exports for its workit commands.
+- Codex: the `workit-verifier` and `workit-reviewer` agents get the same
+  issued `--session` from SubagentStart; any other verifier passes
+  `--as verifier`.
+- OpenCode: a child session's shell already has
+  `WORKIT_SESSION_ID=<lead>:<child>`; Pi: a supervised worker's shell has
+  `<lead>:<worker session>`. Set nothing for a verifier there.
+- Cursor (no session id in the shell): the brief sets the verifier's
+  `WORKIT_SESSION_ID=<lead>:verifier-<random hex>`, a fresh suffix per
+  verifier. Cursor cannot check it: it is declared, not derived.
+- A worker's commits use `export WORKIT_SESSION_ID=<lead>-w-<slice>` from
+  `workit fanout brief`. A verdict under an id you made up (`<lead>-v1`,
+  `<lead>:v1`) is refused as `forged_session` on Claude Code, Codex,
+  OpenCode and Pi.
 
 A batch verifier takes several slices on one surface in one session: for
 each branch it checks out the head, runs that slice's VERIFY, and records its

package/skills/workit-implement/SKILL.md

@@ -33,8 +33,9 @@ description: Build a requested change in small verified steps - follow local pat
    `workit ledger verdict tests-verified --self --how "<what you ran>"`; it
    reads self-reviewed, never verified. High risk, a workspace with
    `verification: independent` (`workit grant show`) or a verified merge needs
-   a fresh verifier with its own session (`WORKIT_SESSION_ID=<yours>-v1`;
-   Claude Code: the `verifier` agent). Before saying done, reconcile
+   a fresh verifier with its own host-derived session (Claude Code and Codex:
+   the `verifier` agent; OpenCode: a child session; Pi: a supervised worker),
+   never a hand-minted id. Before saying done, reconcile
    every named deliverable against the target checkout and observe it (for a push:
    `workit verify-delivery push`).
 

package/skills/workit-review/SKILL.md

@@ -7,8 +7,10 @@ description: Independent review of a diff, branch or PR - intent fidelity and st
 
 Review the candidate, never the author's summary of it. A session that wrote a
 commit on the branch cannot record a passing verdict: if that is you, hand the
-review to a fresh agent with its own session (`WORKIT_SESSION_ID=<lead>-v<n>`;
-Claude Code: the `reviewer` or `verifier` agent).
+review to a fresh agent with its own host-derived session: Claude Code and
+Codex, the `reviewer` or `verifier` agent (`--session` from SubagentStart);
+OpenCode, a child session; Pi, a supervised worker. Never hand-mint one such
+as `<lead>-v1`: it is refused as `forged_session`.
 An author's `--self` verdict reads self-reviewed and never counts as
 independent; `type-check-only` never proves a behavior change.
 

package/src/core/methods.ts

@@ -115,7 +115,8 @@ Autonomy contract:
   satisfies a gate; an ad-hoc \`workit check -- <cmd>\` never does.
 - Author is not verifier: your own verdict is \`--self\`, shown as
   self-reviewed, never verified. High risk, \`verification: independent\` and
-  merge need a verifier with its own session (\`WORKIT_SESSION_ID=<lead>-v<n>\`).
+  merge need a verifier with its own host-derived session (a subagent's
+  \`<lead>:<child>\`, set by the host); never hand-mint one such as \`<lead>-v1\`.
 - A local-commit endpoint does not imply PR readiness, and a local commit alone
   is not evidence of a requested remote push. Before reporting delivery,
   reconcile every requested item and observe it (\`workit verify-delivery\`).

package/src/hooks/handle.ts

@@ -6,6 +6,7 @@ import {
   turnContextText,
 } from "./context";
 import type { HostDescriptor, Support } from "./descriptor";
+import { recordIssuedSession } from "../host-session";
 import { shellPolicy } from "./policy";
 import {
   callKey,
@@ -100,6 +101,9 @@ const subagentStartText = (
   const readOnly = `Workit observed ${who} as read-only/agent-guided.`;
   if (role !== "judge" || !event.agentId) return readOnly;
   const own = subagentSession(session, event.agentId);
+  // `ledger verdict` accepts `<lead>:<agent id>` only when this hook issued it.
+  // (An isolated judge's text is rebuilt with cwd "": the hook's own cwd then.)
+  if (session) recordIssuedSession(input.cwd || process.cwd(), session, own);
   return `${readOnly} Its own Workit session is ${own}: record verdicts with \`workit ledger verdict <result> --session ${own} ...\` so the ledger tells it apart from the author.`;
 };
 

package/src/hooks/hosts/codex.ts

@@ -362,5 +362,5 @@ export const codexAdapter: HostAdapter = {
   },
   render,
   addendum: (input) =>
-    `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run workit verbs with the workit CLI on the shell (node_modules/.bin/workit, or npx -y @brainervirus/workit-cli): check, git branch|commit|push, pr, ci, stack, ledger, handoff; task-family mutations take --json${input.session.id ? ` --actor ${input.session.id}` : ""}. workit acts as this thread (CODEX_THREAD_ID${input.session.id ? `=${input.session.id}` : ""}) unless WORKIT_SESSION_ID is set. A verifier or reviewer records workit ledger verdict under its own session, never the author's: a workit-verifier or workit-reviewer agent uses the --session its SubagentStart context names; any other uses one the lead assigns (WORKIT_HOST=codex_cli WORKIT_SESSION_ID=<lead>-v<n>). Merge and release need a workspace grant (workit grant show); a question answer is not host permission.</workit-codex-mutations>`,
+    `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run workit verbs with the workit CLI on the shell (node_modules/.bin/workit, or npx -y @brainervirus/workit-cli): check, git branch|commit|push, pr, ci, stack, ledger, handoff; task-family mutations take --json${input.session.id ? ` --actor ${input.session.id}` : ""}. workit acts as this thread (CODEX_THREAD_ID${input.session.id ? `=${input.session.id}` : ""}) unless WORKIT_SESSION_ID is set. A verifier or reviewer records workit ledger verdict under its own session, never the author's: a workit-verifier or workit-reviewer agent uses the --session its SubagentStart context names; any other passes --as verifier (an id derived from its own thread). A hand-minted id such as <lead>-v1 is refused as forged_session. Merge and release need a workspace grant (workit grant show); a question answer is not host permission.</workit-codex-mutations>`,
 };

package/src/host-session.ts

@@ -7,6 +7,10 @@
 //   - Pi: PI_SESSION_ID (the bash tool exposes the Pi session id);
 //   - Codex CLI and Desktop: CODEX_THREAD_ID (the thread id hooks get as session_id).
 // Cursor puts no conversation id in its shell; its hook names the id to use.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStore } from "./store/paths";
 
 export type HostSession = { host: string | null; session: string | null };
 
@@ -51,3 +55,188 @@ export function hostSessionFromEnv(env: NodeJS.ProcessEnv): HostSession {
   }
   return inner ? { host: inner.host, session: inner.session } : { host: declared, session: null };
 }
+
+/**
+ * Where this shell's session comes from:
+ *   - `derived`: the host's own shell variable (OPENCODE_SESSION_ID,
+ *     PI_SESSION_ID, CODEX_THREAD_ID), which a caller cannot replace by
+ *     exporting WORKIT_SESSION_ID;
+ *   - `declared`: a host that puts no id in the shell but names itself
+ *     (WORKIT_HOST, e.g. Claude Code's SessionStart export) declares it in
+ *     WORKIT_SESSION_ID;
+ *   - `none`: no host at all (CI, a plain terminal, Cursor's prefixed
+ *     commands): whatever session the caller names is only declared.
+ */
+export type RealSession = HostSession & { kind: "derived" | "declared" | "none" };
+
+export function realHostSession(env: NodeJS.ProcessEnv): RealSession {
+  for (const [key, host] of HOST_SESSION_VARS) {
+    const session = env[key]?.trim();
+    if (session) return { host: host(env), session, kind: "derived" };
+  }
+  const declared = hostSessionFromEnv(env);
+  const hosted = declared.host !== null && declared.host !== "cli";
+  return { ...declared, kind: hosted ? "declared" : "none" };
+}
+
+// Ids a SubagentStart hook gave a lead's subagents (`<lead>:<agent id>`): one
+// empty file per id under `<store>/hooks/issued/<lead hash>/`, so concurrent
+// hooks never lose each other's write, bounded per lead.
+const ISSUED_PER_LEAD = 64;
+
+/**
+ * Written into each issued-id file. A hook bundle that contains this string
+ * records issued ids; `workit doctor` looks for it in the installed Claude
+ * Code and Codex hooks to catch a plugin older than the CLI.
+ */
+export const ISSUED_SESSIONS_MARKER = "workit-issued-sessions/1";
+
+const hash = (value: string): string =>
+  createHash("sha256").update(value).digest("hex").slice(0, 32);
+
+const issuedRoot = (cwd: string): string | null => {
+  const location = resolveStore(cwd);
+  return location instanceof Error ? null : path.join(location.dir, "hooks", "issued");
+};
+
+const issuedDir = (cwd: string, lead: string): string | null => {
+  const root = issuedRoot(cwd);
+  return root === null ? null : path.join(root, hash(lead));
+};
+
+/** No hook in this workspace has ever recorded an issued id (an older plugin hook, most likely). */
+const noIssuedRecord = (cwd: string | undefined): boolean => {
+  if (cwd === undefined) return false;
+  try {
+    const root = issuedRoot(cwd);
+    return root !== null && !fs.existsSync(root);
+  } catch {
+    return false;
+  }
+};
+
+/** Per host: how to update the plugin whose SubagentStart hook issues ids. */
+const PLUGIN_UPDATE: Readonly<Record<string, string>> = {
+  claude_code: "claude plugin marketplace update workit && claude plugin update workit@workit",
+  codex: "codex plugin remove workit@workit && codex plugin add workit@workit",
+};
+
+/** Remember that a SubagentStart hook issued `issued` to a subagent of `lead`. Fails open. */
+export function recordIssuedSession(cwd: string, lead: string, issued: string): void {
+  try {
+    const dir = issuedDir(cwd, lead);
+    if (!dir) return;
+    fs.mkdirSync(dir, { recursive: true });
+    const own = hash(issued);
+    fs.writeFileSync(path.join(dir, own), ISSUED_SESSIONS_MARKER);
+    const entries = fs.readdirSync(dir);
+    if (entries.length <= ISSUED_PER_LEAD) return;
+    // Oldest first; the id just issued is never the one pruned.
+    const byAge = entries
+      .filter((name) => name !== own)
+      .map((name) => ({ name, at: fs.statSync(path.join(dir, name)).mtimeMs }))
+      .toSorted((a, b) => a.at - b.at);
+    for (const { name } of byAge.slice(0, entries.length - ISSUED_PER_LEAD))
+      fs.rmSync(path.join(dir, name), { force: true });
+  } catch {
+    // Fail open: an unrecorded id is refused later, never a broken hook.
+  }
+}
+
+const wasIssued = (cwd: string | undefined, lead: string, claimed: string): boolean => {
+  if (cwd === undefined) return false;
+  try {
+    const dir = issuedDir(cwd, lead);
+    return dir !== null && fs.existsSync(path.join(dir, hash(claimed)));
+  } catch {
+    return false;
+  }
+};
+
+const leadOf = (session: string): string => session.slice(0, session.lastIndexOf(":"));
+
+/**
+ * Hosts whose child sessions run their own shell with their own host session
+ * id: a child proves itself from its own shell, so a lead never mints a child id.
+ */
+const OWN_CHILD_SHELL = new Set(["opencode", "pi"]);
+
+const SESSION_UNSAFE = /[^A-Za-z0-9_.:@/+-]/g;
+
+/**
+ * The host-derived identity of a child session: `<lead>:<child>`, the shape
+ * Claude Code's SubagentStart hook gives a subagent. The child's own id is
+ * kept whole (it is what the host vouches for); the lead part is trimmed to
+ * fit the ledger's 128-character session grammar.
+ */
+export function childSessionId(lead: string, child: string): string {
+  const leaf = child.replace(SESSION_UNSAFE, "-").slice(-120);
+  const prefix = lead.replace(SESSION_UNSAFE, "-").slice(0, 127 - leaf.length);
+  return prefix ? `${prefix}:${leaf}` : leaf;
+}
+
+export type SessionClaimRefusal = { error: string; unblock: string };
+
+/**
+ * Whether `claimed` may act as this shell's session (`cwd` locates the
+ * workspace's record of hook-issued ids):
+ *   - no host session (CI, a plain terminal): any id; `--session X` and
+ *     WORKIT_SESSION_ID=X are the same declaration;
+ *   - the shell's own session (a declared `<lead>:<x>` on Claude Code only
+ *     when its SubagentStart hook issued it);
+ *   - on a host that sets the id, `<lead>:<this session>`: a child naming its
+ *     own host session;
+ *   - `<this session>:<agent id>` only when this lead's SubagentStart hook
+ *     issued it (Claude Code, Codex).
+ * Anything else is a forged id: a verdict recorded under it would make author
+ * is not verifier a naming convention.
+ */
+export function sessionClaimRefusal(
+  env: NodeJS.ProcessEnv,
+  claimed: string,
+  cwd?: string,
+): SessionClaimRefusal | null {
+  const real = realHostSession(env);
+  const host = family(real.host);
+  // A host that always sets its own variable, named without it: the variable
+  // was removed (`env -u OPENCODE_SESSION_ID`), so nothing vouches for the id.
+  if (real.kind !== "derived" && host !== null && HOST_SET_VARIABLE[host])
+    return {
+      error: `forged_session: WORKIT_HOST names ${real.host}, but its own ${HOST_SET_VARIABLE[host]} is not in this shell, so ${claimed} cannot be checked`,
+      unblock: `record the verdict from the ${real.host} session's own shell, where ${HOST_SET_VARIABLE[host]} is set`,
+    };
+  if (real.kind === "none" || !real.session) return null;
+  let issuedClaim = false;
+  if (claimed === real.session) {
+    const declaredChild =
+      real.kind === "declared" && host === "claude_code" && claimed.includes(":");
+    if (!declaredChild || wasIssued(cwd, leadOf(claimed), claimed)) return null;
+    issuedClaim = true;
+  } else if (real.kind === "derived" && claimed.endsWith(`:${real.session}`)) return null;
+  else if (claimed.startsWith(`${real.session}:`)) {
+    if (wasIssued(cwd, real.session, claimed)) return null;
+    issuedClaim = true;
+  }
+  const error = `forged_session: ${claimed} is neither this shell's session (${real.session}) nor an id its host issued to a child of it`;
+  // A well-formed subagent id, but no hook here ever recorded one: the hook
+  // most likely predates this CLI (CLI and plugin update separately).
+  if (issuedClaim && noIssuedRecord(cwd) && host !== null && PLUGIN_UPDATE[host])
+    return {
+      error: `${error}; no SubagentStart hook in this workspace has recorded an issued id`,
+      unblock: `the workit plugin hook is probably older than this CLI and does not record the ids it issues: update the plugin (${PLUGIN_UPDATE[host]}), then relaunch the verifier so its SubagentStart runs the new hook (workit doctor checks this as hook_issued_sessions)`,
+    };
+  const ownChildShell = host !== null && OWN_CHILD_SHELL.has(host);
+  return {
+    error,
+    unblock: ownChildShell
+      ? `record the verdict from the verifier's own ${host === "pi" ? "Pi worker" : "OpenCode child session"} shell, where WORKIT_SESSION_ID is already set; never set WORKIT_SESSION_ID or --session by hand`
+      : "never name a session yourself: spawn a verifier or reviewer subagent and pass exactly the --session its SubagentStart context names, or pass --as verifier",
+  };
+}
+
+/** Hosts that always put their own session variable in the agent's shell. */
+const HOST_SET_VARIABLE: Readonly<Record<string, string>> = {
+  opencode: "OPENCODE_SESSION_ID",
+  pi: "PI_SESSION_ID",
+  codex: "CODEX_THREAD_ID",
+};

package/src/ledger.ts

@@ -1140,10 +1140,31 @@ export function authorSessions(
   return sessions;
 }
 
+/** Where each host's verifier session comes from, for refusal hints. */
+const HOST_DERIVED_SESSIONS =
+  "Claude Code, Codex and Cursor: `--session <lead>:<agent id>` from the SubagentStart hook; OpenCode child sessions and Pi workers: WORKIT_SESSION_ID=<lead>:<child> already set in their shell";
+
+/** Whether `derived` is a host-derived `<lead>:<bare>` id for the bare host session `bare`. */
+const derivesFrom = (derived: string, bare: string): boolean =>
+  !bare.includes(":") && derived.endsWith(`:${bare}`);
+
+/**
+ * Whether `session` is one of the authors: the same id, or one is a bare host
+ * session and the other its derived `<lead>:<session>` form (an OpenCode
+ * child that committed as `<lead>:<child>` and judges as `<child>` is still
+ * the author). Two derived ids never match on a shared last segment.
+ */
+const authoredBy = (authors: Set<string>, session: string): boolean => {
+  if (authors.has(session)) return true;
+  for (const author of authors)
+    if (derivesFrom(author, session) || derivesFrom(session, author)) return true;
+  return false;
+};
+
 const independenceReasons = (row: ReadRow, authors: Set<string>): RejectReason[] => {
   const reasons: RejectReason[] = [];
   if (!row.actor.session) reasons.push("no_session");
-  else if (authors.has(row.actor.session)) reasons.push("author_session");
+  else if (authoredBy(authors, row.actor.session)) reasons.push("author_session");
   if (row.self === true && !reasons.includes("no_session")) reasons.push("self");
   return reasons;
 };
@@ -1687,15 +1708,16 @@ export function recordVerdict(
     head: key.head,
   });
   const authoring = [session, input.derivedFrom].find(
-    (candidate): candidate is string => typeof candidate === "string" && authors.has(candidate),
+    (candidate): candidate is string =>
+      typeof candidate === "string" && authoredBy(authors, candidate),
   );
   if (!self && authoring)
     return err(
       "blocked",
       `author_verdict: session ${authoring} authored ${branch}; a verdict must come from a different session`,
       input.derivedFrom === undefined
-        ? "have a non-author session record the verdict: spawn a verifier with its own WORKIT_SESSION_ID=<lead>-v<n> (Claude Code: subagents get one from the SubagentStart hook); or, as the author, pass --self (self-reviewed, never accepted)"
-        : "run the verifier as a separate session: the lead spawns it with its own WORKIT_SESSION_ID (Claude Code: subagents get one from the SubagentStart hook)",
+        ? `have a non-author session record the verdict: spawn a verifier subagent, which gets its own host-derived session (${HOST_DERIVED_SESSIONS}); or, as the author, pass --self (self-reviewed, never accepted)`
+        : `run the verifier as a separate session: spawn a verifier subagent, which gets its own host-derived session (${HOST_DERIVED_SESSIONS})`,
     );
   const link = checkSupersede(context, "verdict", { self, kind, branch });
   if (!link.ok) return link;