@brainervirus/workit-core 8.13.0 → 8.14.0

package/src/hooks/write-gate.ts

@@ -5,13 +5,28 @@
 // Reads only the task index, one task snapshot and the ledger; never
 // migrates, never captures a candidate, and fails open on any state error.
 import { realpathSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileSignature, TaskStore } from "../core/task-store";
 import { latestJudgment, writeBlockers, type WriteBlocker } from "../core/policy/derive";
 import { applicableDecision } from "../core/task-evaluation";
-import { ledgerPath } from "../ledger";
+import {
+  claimLiveSession,
+  liveConflict,
+  type LiveConflict,
+  type LiveDeps,
+  type LiveOwner,
+} from "../core/live-session";
+import { workspaceLiveSessionGuard } from "../core/workspaces";
+import { appendHookObserved, ledgerPath } from "../ledger";
 import type { HookDecision } from "./protocol";
-import { segmentsOf } from "./shell-words";
+import {
+  inWorkitWorkspace,
+  rawInvocations,
+  workitInvocations,
+  type RawInvocation,
+} from "./raw-git";
+import { segmentsOf, type ShellDialect } from "./shell-words";
 
 const NONE: HookDecision = { kind: "none" };
 
@@ -204,13 +219,298 @@ const gateFor = (cwd: string): Gate | null => {
   return gate;
 };
 
+// --- the live-session guard (#274) ------------------------------------------
+
+/** git subcommands that change a checkout's files, index or HEAD. */
+const MUTATING_GIT = new Set([
+  "add",
+  "am",
+  "apply",
+  "checkout",
+  "cherry-pick",
+  "clean",
+  "commit",
+  "merge",
+  "mv",
+  "pull",
+  "rebase",
+  "reset",
+  "restore",
+  "revert",
+  "rm",
+  "stash",
+  "switch",
+]);
+/** Subcommands whose `-n` means `--dry-run` (for `commit`, `-n` skips hooks). */
+const DRY_N = new Set(["add", "clean", "rm", "mv"]);
+/** `workit git` verbs that commit or move HEAD in the checkout. */
+const MUTATING_WORKIT_GIT = new Set(["commit", "branch"]);
+
+/** A placeholder file name that stands for its directory (an unknown write, a git command). */
+const DIR_TARGET = ".workit-live-target";
+
+/** A one-command override: `WORKIT_LIVE_SESSION=override <command>`. */
+const OVERRIDE = "WORKIT_LIVE_SESSION=override";
+
+/** Only asks for help or a dry run: changes nothing. */
+const inert = (args: readonly string[], sub: string): boolean =>
+  args.some(
+    (arg) =>
+      arg === "--help" ||
+      arg === "-h" ||
+      arg === "--dry-run" ||
+      (DRY_N.has(sub) && /^-[a-zA-Z]*n[a-zA-Z]*$/.test(arg) && !arg.startsWith("--")),
+  );
+
+/**
+ * The directories mutating git commands in `command` run in (raw-git's
+ * analysis: `cd`/`pushd`, groups, `-C`, env and wrapper prefixes, `bash -c`,
+ * `$(…)`, `eval`, `xargs`, `find -exec`, PowerShell, `cmd /c`). A command
+ * whose directory cannot be known is skipped, never denied.
+ */
+const gitMutationDirs = (cwd: string, command: string, dialect: ShellDialect): string[] => {
+  let invocations: readonly RawInvocation[];
+  try {
+    invocations = rawInvocations(command, dialect);
+  } catch {
+    return [];
+  }
+  return invocations.flatMap((invocation) => {
+    if (invocation.tool !== "git" || invocation.dir === undefined) return [];
+    const at = invocation.args.findIndex((arg) => !arg.startsWith("-"));
+    const sub = invocation.args[at] ?? "";
+    const rest = invocation.args.slice(at + 1);
+    if (!MUTATING_GIT.has(sub) || inert(rest, sub)) return [];
+    // `git stash list|show` only reads.
+    if (sub === "stash" && ["list", "show"].includes(rest[0] ?? "")) return [];
+    return [path.resolve(cwd, invocation.dir ?? ".")];
+  });
+};
+
+const CD = new Set(["cd", "chdir", "set-location", "sl"]);
+const PUSHD = new Set(["pushd", "push-location"]);
+const POPD = new Set(["popd", "pop-location"]);
+
+/** A `cd` operand resolved against `dir`; undefined when it cannot be known. */
+const cdInto = (dir: string | undefined, words: string[]): string | undefined => {
+  const target = words.slice(1).find((word) => !word.startsWith("-") || word === "-");
+  // Only a leading `~` expands; a mid-path `~` is literal (Windows 8.3
+  // short names like RUNNER~1).
+  if (dir === undefined || target === "-" || (target && /^~|[$`*?]/.test(target))) return undefined;
+  return target === undefined ? os.homedir() : path.resolve(dir, target);
+};
+
+const quoteWord = (word: string): string =>
+  /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+
+/**
+ * Per top-level segment, the files it writes (redirects, `touch`, `rm`,
+ * `sed -i`…) and `workit git commit|branch`, resolved against the
+ * directory that segment runs in (`cd`, `pushd`/`popd`, `( … )` groups). A
+ * relative target in an unknown directory is skipped.
+ */
+const segmentTargets = (cwd: string, command: string, dialect: ShellDialect): string[] => {
+  const targets: string[] = [];
+  let dir: string | undefined = cwd;
+  let stack: Array<string | undefined> = [];
+  const groups: Array<{ dir: string | undefined; stack: Array<string | undefined> }> = [];
+  const at = (file: string) =>
+    path.isAbsolute(file) ? file : dir === undefined ? null : path.resolve(dir, file);
+  for (const segment of segmentsOf(command, dialect)) {
+    if (segment.group === "open") {
+      groups.push({ dir, stack: [...stack] });
+      continue;
+    }
+    if (segment.group === "close") {
+      const saved = groups.pop();
+      if (saved) ({ dir, stack } = saved);
+      continue;
+    }
+    const lead = segment.words.findIndex((word) => !/^\w+=/.test(word));
+    const words = lead < 0 ? [] : segment.words.slice(lead);
+    const name = (words[0]?.split(/[\\/]/).at(-1) ?? "").toLowerCase();
+    if (CD.has(name)) {
+      dir = cdInto(dir, words);
+      continue;
+    }
+    if (PUSHD.has(name)) {
+      stack.push(dir);
+      dir = cdInto(dir, words);
+      continue;
+    }
+    if (POPD.has(name)) {
+      dir = stack.length ? stack.pop() : undefined;
+      continue;
+    }
+    for (const file of segment.redirects)
+      if (!/^\/dev\/(?:null|stdout|stderr|tty)$/.test(file)) {
+        const resolved = at(file);
+        if (resolved) targets.push(resolved);
+      }
+    const edits = editsOf(segment.words);
+    if (edits === null) {
+      if (dir !== undefined) targets.push(path.join(dir, DIR_TARGET));
+    } else
+      for (const file of edits) {
+        const resolved = at(file);
+        if (resolved) targets.push(resolved);
+      }
+    if (
+      dir !== undefined &&
+      workitInvocations(segment.words.map(quoteWord).join(" "), "posix").some(
+        (args) =>
+          args[0] === "git" && MUTATING_WORKIT_GIT.has(args[1] ?? "") && !inert(args.slice(2), ""),
+      )
+    )
+      targets.push(path.join(dir, DIR_TARGET));
+  }
+  return targets;
+};
+
+/** The command is one simple command led by `WORKIT_LIVE_SESSION=override`. */
+const overridden = (command: string, dialect: ShellDialect): boolean => {
+  const segments = segmentsOf(command, dialect);
+  if (segments.length !== 1 || segments[0].group || segments[0].subs?.length) return false;
+  const words = segments[0].words;
+  const lead = words.findIndex((word) => !/^\w+=/.test(word));
+  return lead > 0 && words.slice(0, lead).includes(OVERRIDE);
+};
+
+const HOST_LABELS: Readonly<Record<string, string>> = {
+  claude_code: "Claude Code",
+  opencode: "OpenCode",
+  codex_cli: "Codex CLI",
+  codex_desktop: "Codex Desktop",
+  cursor: "Cursor",
+  pi: "Pi",
+};
+
+const ageText = (ms: number): string => {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  return seconds < 120 ? `${seconds}s` : `${Math.round(seconds / 60)} min`;
+};
+
+const liveDeny = ({ marker, checkout, ageMs, file }: LiveConflict): HookDecision => {
+  const unblock = `Work in your own worktree (\`git worktree add <path> -b <branch>\`, or \`workit fanout worktree create <slice>\`). Only if the user confirms that session is finished: release it with \`rm '${file}'\`, or prefix one command with ${OVERRIDE}.`;
+  return {
+    kind: "deny",
+    reason: `workit live-session guard: ${checkout} belongs to another live agent session, ${HOST_LABELS[marker.host] ?? marker.host} session ${marker.session}${marker.pid === null ? "" : ` (pid ${marker.pid})`}, last active ${ageText(ageMs)} ago. Do not edit a checkout another session is working in; read-only commands stay allowed. ${unblock}`,
+    unblock,
+  };
+};
+
+/** One target per directory. */
+const guarded = (targets: readonly string[]): string[] => {
+  const seen = new Set<string>();
+  return targets.filter((target) => {
+    const dir = path.dirname(target);
+    if (seen.has(dir)) return false;
+    seen.add(dir);
+    return true;
+  });
+};
+
+/**
+ * Deny when a target's checkout belongs to another live session and its
+ * workspace keeps `liveSessionGuard` on. Fails open.
+ */
+const liveGate = (owner: LiveOwner, targets: readonly string[], deps?: LiveDeps): HookDecision => {
+  try {
+    for (const target of guarded(targets)) {
+      const conflict = liveConflict(target, owner, deps);
+      if (conflict && workspaceLiveSessionGuard(conflict.checkout)) return liveDeny(conflict);
+    }
+  } catch {
+    // Fail open.
+  }
+  return NONE;
+};
+
+const claimAll = (owner: LiveOwner, targets: readonly string[], deps?: LiveDeps): void => {
+  for (const target of guarded(targets)) claimLiveSession(target, owner, deps);
+};
+
+/** The absolute paths an edit touches: its files, or cwd itself when unknown. */
+const liveTargets = (cwd: string, paths: readonly string[] | null): string[] =>
+  paths?.length ? paths.map((file) => path.resolve(cwd, file)) : [path.join(cwd, DIR_TARGET)];
+
 /**
  * Deny a working-tree edit while the branch task has unmet before-write
  * requirements. `paths` are the files the tool writes, or null when unknown
  * (a shell write, a patch whose headers cannot be read); unknown or empty
  * targets are gated, and an edit touching only exempt files is always allowed.
+ * With `owner` (the hook's session), the live-session guard runs first, and
+ * an allowed edit refreshes the owner's marker in each checkout it touches.
+ */
+export function writeGate(
+  cwd: string,
+  paths: readonly string[] | null,
+  owner?: LiveOwner | null,
+  deps?: LiveDeps,
+): HookDecision {
+  if (!owner) return beforeWriteGate(cwd, paths);
+  const targets = liveTargets(cwd, paths);
+  const live = liveGate(owner, targets, deps);
+  if (live.kind !== "none") return live;
+  const decision = beforeWriteGate(cwd, paths);
+  if (decision.kind === "none") claimAll(owner, targets, deps);
+  return decision;
+}
+
+/**
+ * The write gates on one shell command: the live-session guard on its writes
+ * and mutating git commands in the directories they run in, then the
+ * before-write gate on its writes. A command that is only
+ * `WORKIT_LIVE_SESSION=override <command>` skips the guard and leaves a
+ * ledger row. An allowed mutation refreshes the owner's marker.
  */
-export function writeGate(cwd: string, paths: readonly string[] | null): HookDecision {
+export function shellGate(
+  cwd: string,
+  command: string,
+  owner: LiveOwner | null,
+  dialect: ShellDialect = "posix",
+  deps?: LiveDeps,
+): HookDecision {
+  const writes = shellWrites(command);
+  let targets: string[] = [];
+  if (owner) {
+    try {
+      targets = [
+        ...segmentTargets(cwd, command, dialect),
+        ...gitMutationDirs(cwd, command, dialect).map((dir) => path.join(dir, DIR_TARGET)),
+      ];
+    } catch {
+      targets = [];
+    }
+  }
+  if (owner && targets.length) {
+    const live = liveGate(owner, targets, deps);
+    if (live.kind !== "none") {
+      if (!overridden(command, dialect)) return live;
+      noteOverride(cwd, owner, command);
+    }
+  }
+  const decision = writes.writes ? beforeWriteGate(cwd, writes.targets) : NONE;
+  if (owner && targets.length && decision.kind === "none") claimAll(owner, targets, deps);
+  return decision;
+}
+
+/** A ledger row for an override that let a command past the guard (managed repositories only). */
+const noteOverride = (cwd: string, owner: LiveOwner, command: string): void => {
+  try {
+    if (!inWorkitWorkspace(cwd)) return;
+    appendHookObserved(cwd, {
+      type: "live_session.override",
+      actor: { host: owner.host, session: owner.session, agentId: null },
+      session: owner.session,
+      command: command.slice(0, 200),
+    });
+  } catch {
+    // A note never blocks the command.
+  }
+};
+
+function beforeWriteGate(cwd: string, paths: readonly string[] | null): HookDecision {
   try {
     const gate = gateFor(cwd);
     if (!gate || gate.blockers.length === 0) return NONE;

package/src/host-session.ts

@@ -7,7 +7,7 @@
 //   - 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 { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { resolveStateDir } from "./core/logger";
@@ -87,11 +87,12 @@ const ISSUED_PER_LEAD = 64;
 
 /**
  * Written into each issued-id file. A hook bundle that contains this string
- * records issued ids per lead in the user's state dir (`/2`; `/1` hooks of
- * 8.10-8.12 wrote them per repository, which breaks cross-repo verdicts); `workit doctor` looks for it in the installed Claude
- * Code and Codex hooks to catch a plugin older than the CLI.
+ * records issued ids per lead in the user's state dir with a token only the
+ * subagent is told (`/3`; `/2` files carry no token, `/1` hooks of 8.10-8.12
+ * wrote them per repository); `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/2";
+export const ISSUED_SESSIONS_MARKER = "workit-issued-sessions/3";
 
 const hash = (value: string): string =>
   createHash("sha256").update(value).digest("hex").slice(0, 32);
@@ -100,6 +101,13 @@ const hash = (value: string): string =>
 // started in one repository delegates review of others, and the verifier
 // records its verdict from whichever repository it reviews (#294).
 const userIssuedRoot = (): string => path.join(resolveStateDir(), "issued");
+/**
+ * Token hashes, one file per issued id under `<state>/issued-tokens/<lead
+ * hash>/`: a tree hooks older than tokens never write, so an old cached
+ * plugin hook that rewrites a record in `issued/` cannot strip its token.
+ * Once a lead has one, every id under it needs a token (sticky binding).
+ */
+const userTokenRoot = (): string => path.join(resolveStateDir(), "issued-tokens");
 
 /**
  * Hooks of 8.10-8.12 wrote issued ids into `<store>/hooks/issued` of the
@@ -126,7 +134,13 @@ function migrateRepoIssued(cwd: string | undefined): void {
       const to = path.join(userIssuedRoot(), lead);
       fs.mkdirSync(to, { recursive: true, mode: 0o700 });
       for (const id of fs.readdirSync(from)) {
-        fs.copyFileSync(path.join(from, id), path.join(to, id));
+        // Never over an existing per-user record: a legacy in-repo copy must
+        // not replace a token-bound one (EEXIST just drops the legacy copy).
+        try {
+          fs.copyFileSync(path.join(from, id), path.join(to, id), fs.constants.COPYFILE_EXCL);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        }
         fs.rmSync(path.join(from, id), { force: true });
       }
       removeIfEmpty(from);
@@ -170,14 +184,40 @@ const PLUGIN_UPDATE: Readonly<Record<string, string>> = {
   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 {
+const tokenHash = (token: string): string => createHash("sha256").update(token).digest("hex");
+
+/**
+ * Remember that a SubagentStart hook issued `issued` to a subagent of `lead`,
+ * and return the token that binds the id to that subagent: the hook hands it
+ * only to the subagent, and only its sha256 is stored, so a lead or sibling
+ * that reads the id in the ledger cannot act as it (audit mv83zyg6 P1).
+ * Each id is issued once: a SubagentStart fired again for an id already
+ * issued (a lead replaying the hook) gets no new token (review mv8daa5d P1).
+ * Null when nothing was issued: already issued, or the write failed (fails open).
+ */
+export function recordIssuedSession(cwd: string, lead: string, issued: string): string | null {
+  const token = randomBytes(18).toString("base64url");
   try {
     migrateRepoIssued(cwd);
+    const own = hash(issued);
+    const tokens = path.join(userTokenRoot(), hash(lead));
+    fs.mkdirSync(tokens, { recursive: true, mode: 0o700 });
+    // `wx`: the first SubagentStart for an id wins; any later one fails here.
+    fs.writeFileSync(path.join(tokens, own), `${tokenHash(token)}\n`, { mode: 0o600, flag: "wx" });
     const dir = path.join(userIssuedRoot(), hash(lead));
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    const own = hash(issued);
-    fs.writeFileSync(path.join(dir, own), ISSUED_SESSIONS_MARKER);
+    fs.writeFileSync(path.join(dir, own), `${ISSUED_SESSIONS_MARKER}\n`, { mode: 0o600 });
+    pruneIssued(dir, own, tokens);
+    return token;
+  } catch {
+    // Already issued (EEXIST), or a failed write: no token is handed out.
+    return null;
+  }
+}
+
+/** 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 {
     const entries = fs.readdirSync(dir);
     if (entries.length <= ISSUED_PER_LEAD) return;
     // Oldest first; the id just issued is never the one pruned.
@@ -185,22 +225,75 @@ export function recordIssuedSession(cwd: string, lead: string, issued: string):
       .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))
+    for (const { name } of byAge.slice(0, entries.length - ISSUED_PER_LEAD)) {
       fs.rmSync(path.join(dir, name), { force: true });
+      fs.rmSync(path.join(tokens, 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 => {
+/** The issued-id file's text, or null when no hook issued `claimed`. */
+const issuedRecord = (cwd: string | undefined, claimed: string): string | null => {
+  const cut = claimed.lastIndexOf(":");
+  if (cut <= 0) return null;
   migrateRepoIssued(cwd);
   try {
-    return fs.existsSync(path.join(userIssuedRoot(), hash(lead), hash(claimed)));
+    return fs.readFileSync(
+      path.join(userIssuedRoot(), hash(claimed.slice(0, cut)), hash(claimed)),
+      "utf8",
+    );
   } catch {
-    return false;
+    return null;
   }
 };
 
+const TOKEN_HASH = /^([0-9a-f]{64})$/mu;
+
+/** The stored token hash for `claimed`, and whether its lead has any token at all. */
+const issuedToken = (claimed: string): { stored: string | null; leadBound: boolean } => {
+  const cut = claimed.lastIndexOf(":");
+  if (cut <= 0) return { stored: null, leadBound: false };
+  const dir = path.join(userTokenRoot(), hash(claimed.slice(0, cut)));
+  try {
+    const text = fs.readFileSync(path.join(dir, hash(claimed)), "utf8");
+    return { stored: TOKEN_HASH.exec(text)?.[1] ?? null, leadBound: true };
+  } catch {
+    return { stored: null, leadBound: safeList(dir).length > 0 };
+  }
+};
+
+/**
+ * How a SubagentStart hook issued `claimed` (`<lead>:<agent id>`): `token`
+ * (it must be presented, `--token`), `legacy` (a hook older than tokens
+ * recorded it) or null (never issued). Binding is sticky: once its lead has
+ * any token-bound id, a token-less record (an old cached hook rewriting one,
+ * or issuing a new one) reads `token` with no token that can match.
+ */
+export type IssuedBinding = "token" | "legacy";
+export function issuedBinding(cwd: string | undefined, claimed: string): IssuedBinding | null {
+  const record = issuedRecord(cwd, claimed);
+  const { stored, leadBound } = issuedToken(claimed);
+  if (stored) return "token";
+  if (record === null) return null;
+  return leadBound ? "token" : "legacy";
+}
+
+/** Whether `token` is the one the hook gave the subagent it issued `claimed` to. */
+export function issuedTokenMatches(
+  cwd: string | undefined,
+  claimed: string,
+  token: string | null | undefined,
+): boolean {
+  migrateRepoIssued(cwd);
+  const { stored } = issuedToken(claimed);
+  if (!stored || !token) return false;
+  const given = Buffer.from(tokenHash(token.trim()));
+  const want = Buffer.from(stored);
+  return given.length === want.length && timingSafeEqual(given, want);
+}
+
 const leadOf = (session: string): string => session.slice(0, session.lastIndexOf(":"));
 
 /**
@@ -230,12 +323,17 @@ export type SessionClaimRefusal = { error: string; unblock: string };
  * 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);
+ *   - the shell's own session; a declared `<lead>:<x>` (any WORKIT_HOST but
+ *     cli) only when a 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).
+ * An issued id the hook bound to a token is accepted only with that token
+ * (`options.token`): a lead or sibling that read the id cannot reuse it.
+ * `options.flag`: named by `--session`. On a host that is only for an issued
+ * id; a shell's own or derived session comes from its environment, so a
+ * `--session` the gate would not accept is refused here, not later.
  * Anything else is a forged id: a verdict recorded under it would make author
  * is not verifier a naming convention.
  */
@@ -243,6 +341,7 @@ export function sessionClaimRefusal(
   env: NodeJS.ProcessEnv,
   claimed: string,
   cwd?: string,
+  options: { token?: string | null; flag?: boolean } = {},
 ): SessionClaimRefusal | null {
   const real = realHostSession(env);
   const host = family(real.host);
@@ -254,16 +353,27 @@ export function sessionClaimRefusal(
       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 ownShell =
+    (claimed === real.session && !(real.kind === "declared" && claimed.includes(":"))) ||
+    (real.kind === "derived" && claimed.endsWith(`:${real.session}`));
+  if (ownShell)
+    return options.flag
+      ? {
+          error: `session_flag: --session ${claimed} names this shell's own ${real.host} session; on a host only an issued subagent id is passed as --session`,
+          unblock: "drop --session: the shell's own session is already the acting one",
+        }
+      : null;
+  const issuedClaim = claimed === real.session || claimed.startsWith(`${real.session}:`);
+  if (issuedClaim) {
+    const binding = issuedBinding(cwd, claimed);
+    if (binding === "legacy") return null;
+    if (binding === "token")
+      return issuedTokenMatches(cwd, claimed, options.token)
+        ? null
+        : {
+            error: `unbound_session: ${claimed} was issued to a subagent, and this call did not present the token its SubagentStart hook gave it`,
+            unblock: `only that subagent acts as ${claimed}: it passes --token exactly as its SubagentStart context names it (or WORKIT_SESSION_TOKEN); anyone else spawns their own verifier`,
+          };
   }
   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
@@ -278,7 +388,7 @@ export function sessionClaimRefusal(
     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",
+      : "never name a session yourself: spawn a verifier or reviewer subagent and pass exactly the --session and --token its SubagentStart context names, or pass --as verifier",
   };
 }