@brainervirus/workit-core 8.20.0 → 8.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.20.0",
+  "version": "8.21.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

@@ -26,6 +26,7 @@ import {
   skillReadIn,
   withContextLine,
 } from "./skill-nudge";
+import { seedStanding, standingDelta } from "./standing";
 import { stopDecision } from "./stop";
 import { liveOwner } from "../core/live-session";
 import { shellGate, writeGate } from "./write-gate";
@@ -125,7 +126,29 @@ const subagentStartText = (
   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." : ""}`;
 };
 
+const PRE_TOOL = new Set<HookEventKind>(["shell.pre", "write.pre", "tool.pre"]);
+
+/**
+ * A running worker's standing-order delta rides any pre-tool answer that lets
+ * the call run. In-process hosts deliver it on their own channel (OpenCode's
+ * system context, Pi's tool result), so it is never spent here for them.
+ */
 export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
+  const decision = decide(input, deps);
+  if (
+    deps.descriptor.transport !== "hook-process" ||
+    !PRE_TOOL.has(input.event.kind) ||
+    decision.kind === "deny"
+  )
+    return decision;
+  const delta = standingDelta(input);
+  if (!delta) return decision;
+  return decision.kind === "rewrite"
+    ? { ...decision, text: [decision.text, delta].filter(Boolean).join("\n") }
+    : withContextLine(decision, delta);
+}
+
+function decide(input: HookInput, deps: HookDeps): HookDecision {
   const { descriptor } = deps;
   const event = input.event;
   switch (event.kind) {
@@ -221,6 +244,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         ? writeGate(input.cwd, event.paths, liveOwner(input, descriptor.transport))
         : NONE;
     case "subagent.start":
+      seedStanding({ ...input, session: { ...input.session, agentId: event.agentId } });
       return {
         kind: "context",
         text: subagentStartText(input, descriptor, event),

package/src/hooks/index.ts

@@ -26,6 +26,7 @@ export { asksUser, stopDecision, stopObligation, type StopObligation } from "./s
 export { callKey, noteRawCommit, rawGitPost, rawGitPre } from "./raw-git";
 export { promptNudge, recordSkillLoad, shellNudge, skillFileIn } from "./skill-nudge";
 export { isWriteTool, writePaths } from "./hosts/fields";
+export { seedStanding, standingDelta, standingSinceStart } from "./standing";
 export { dispatchHook, failureDecision, handleHook, type HookDeps } from "./handle";
 export { HOOK_ADAPTERS, runHookProcess } from "./run";
 export { CLAUDE_CODE_DESCRIPTOR, claudeCodeAdapter } from "./hosts/claude-code";

package/src/hooks/standing-signal.ts

@@ -0,0 +1,99 @@
+// The standing-order revision signal (#320). Every standing add or clear
+// writes the new row's id to `<store>/standing/rev`; each agent that a hook
+// has answered since keeps the revision it last saw in
+// `<store>/standing/seen/<key>.json`. A tool call whose agent already saw the
+// current revision costs two small reads and never loads the Workit runtime.
+// fs, path and crypto only: the Codex launcher imports this before the
+// runtime, and the Claude Code launcher (bin/workit-hook.mjs) keeps a copy
+// that test/workit-core/hooks/standing-signal.test.ts holds equal.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export type StandingSeen = { rev: string | null; ids: string[] };
+
+/** `<git common dir>/workit` by fs reads alone, or null outside a repository. */
+export const gitStoreDir = (cwd: string): string | null => {
+  try {
+    for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+      const dotGit = path.join(dir, ".git");
+      if (fs.existsSync(dotGit)) {
+        let gitDir = dotGit;
+        if (fs.statSync(dotGit).isFile()) {
+          const target = /^gitdir:\s*(.+)$/mu.exec(fs.readFileSync(dotGit, "utf8"))?.[1]?.trim();
+          if (!target) return null;
+          gitDir = path.resolve(dir, target);
+          const common = path.join(gitDir, "commondir");
+          if (fs.existsSync(common))
+            gitDir = path.resolve(gitDir, fs.readFileSync(common, "utf8").trim());
+        }
+        return path.join(gitDir, "workit");
+      }
+      if (path.dirname(dir) === dir) return null;
+    }
+  } catch {
+    return null;
+  }
+};
+
+export const standingRevFile = (store: string): string => path.join(store, "standing", "rev");
+
+/** One file per agent: a host session, or one subagent of it. */
+export const standingSeenFile = (store: string, session: string, agentId: string | null): string =>
+  path.join(
+    store,
+    "standing",
+    "seen",
+    `${createHash("sha256")
+      .update(`${session}\0${agentId ?? ""}`)
+      .digest("hex")
+      .slice(0, 32)}.json`,
+  );
+
+export const readStandingRev = (store: string): string | null => {
+  try {
+    return fs.readFileSync(standingRevFile(store), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+};
+
+export const readStandingSeen = (file: string): StandingSeen => {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8")) as { rev?: unknown; ids?: unknown };
+    return {
+      rev: typeof value.rev === "string" ? value.rev : null,
+      ids: Array.isArray(value.ids)
+        ? value.ids.filter((id): id is string => typeof id === "string")
+        : [],
+    };
+  } catch {
+    return { rev: null, ids: [] };
+  }
+};
+
+/** Fails open: without the file the agent is offered the same delta again. */
+export const writeStandingSeen = (file: string, seen: StandingSeen): void => {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(seen));
+  } catch {
+    // An unwritable store only repeats the delta.
+  }
+};
+
+export const bumpStandingRev = (store: string, rev: string): void => {
+  try {
+    fs.mkdirSync(path.join(store, "standing"), { recursive: true });
+    fs.writeFileSync(standingRevFile(store), `${rev}\n`);
+  } catch {
+    // Running workers miss the delta; briefs rendered later still carry it.
+  }
+};
+
+/** Has this agent not yet seen the store's current standing revision? */
+export const standingPending = (cwd: string, session: string, agentId: string | null): boolean => {
+  const store = gitStoreDir(cwd);
+  const rev = store ? readStandingRev(store) : null;
+  return rev !== null && readStandingSeen(standingSeenFile(store!, session, agentId)).rev !== rev;
+};

package/src/hooks/standing.ts

@@ -0,0 +1,196 @@
+// Standing-order deltas for running workers (#320, decision mvi7psa4). A
+// worker's brief carries the orders in force when it was rendered; an order
+// the lead adds or clears later reaches the worker on its next hooked tool
+// call, once per revision (standing-signal.ts). A worker of a fanout is a
+// subagent or child of one of its leads, a session id handed out under one
+// (`<lead>:<x>`, `<lead>-w-<slice>`), or any session on one of its slice
+// branches; the lead itself is never one.
+import fs from "node:fs";
+import path from "node:path";
+import { currentBranch } from "../git/rev";
+import { activeStanding, readLedger, type ReadRow } from "../ledger";
+import {
+  gitStoreDir,
+  readStandingRev,
+  readStandingSeen,
+  standingSeenFile,
+  writeStandingSeen,
+} from "./standing-signal";
+import type { HookInput } from "./protocol";
+
+type Plan = { name: string; leads: string[]; branches: string[] };
+
+const readPlans = (store: string): Plan[] => {
+  const dir = path.join(store, "fanouts");
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir).filter((name) => name.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const plans: Plan[] = [];
+  for (const name of names) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8")) as Record<
+        string,
+        unknown
+      >;
+      if (typeof raw.name !== "string" || !Array.isArray(raw.slices)) continue;
+      const texts = (value: unknown): string[] =>
+        Array.isArray(value)
+          ? value.filter((item): item is string => typeof item === "string" && item !== "")
+          : [];
+      plans.push({
+        name: raw.name,
+        leads: texts([raw.leadSession, ...texts(raw.formerLeads)]),
+        branches: texts(
+          raw.slices.map((slice) =>
+            slice && typeof slice === "object" ? (slice as { branch?: unknown }).branch : null,
+          ),
+        ),
+      });
+    } catch {
+      // An unreadable plan has no workers to tell.
+    }
+  }
+  return plans;
+};
+
+/** The lead a subagent or child reports to, when the host names it. */
+const leadOf = (input: HookInput): string | null =>
+  input.session.parentId ??
+  (input.session.agentId ? input.session.id : null) ??
+  (input.session.id.includes(":") ? input.session.id.split(":")[0] : null);
+
+const worksFor = (plan: Plan, input: HookInput, branch: () => string | null): boolean => {
+  const session = input.session.id;
+  if (plan.leads.includes(session) && !input.session.agentId) return false;
+  const lead = leadOf(input);
+  if (lead && plan.leads.includes(lead)) return true;
+  if (plan.leads.some((each) => session.startsWith(`${each}-w-`))) return true;
+  const current = branch();
+  return current !== null && plan.branches.includes(current);
+};
+
+type Standing = { rev: string; orders: Map<string, ReadRow>; rows: readonly ReadRow[] };
+
+/** Orders in force now for every fanout this agent works for, keyed by row id. */
+const standingFor = (input: HookInput, store: string, rev: string): Standing => {
+  const orders = new Map<string, ReadRow>();
+  const ledger = readLedger(input.cwd);
+  const rows = ledger.ok ? ledger.value.rows : [];
+  let branch: string | null | undefined;
+  const lazyBranch = () => (branch === undefined ? (branch = currentBranch(input.cwd)) : branch);
+  for (const plan of readPlans(store))
+    if (worksFor(plan, input, lazyBranch))
+      for (const row of activeStanding(rows, plan.name, plan.leads.length ? plan.leads : null))
+        orders.set(row.id, row);
+  return { rev, orders, rows };
+};
+
+/** The same store path the launchers' fast paths compute, so they read the same seen file. */
+const located = (input: HookInput) => {
+  const store = input.session.id ? gitStoreDir(input.cwd) : null;
+  const rev = store ? readStandingRev(store) : null;
+  if (!store || rev === null) return null;
+  return { store, rev, file: standingSeenFile(store, input.session.id, input.session.agentId) };
+};
+
+/**
+ * A new subagent's brief already carries the orders in force: its baseline,
+ * so only later changes reach it.
+ */
+export const seedStanding = (input: HookInput): void => {
+  try {
+    const where = located(input);
+    if (!where) return;
+    const now = standingFor(input, where.store, where.rev);
+    writeStandingSeen(where.file, { rev: where.rev, ids: [...now.orders.keys()] });
+  } catch {
+    // Without a baseline the first delta recaps every order in force.
+  }
+};
+
+const fanoutOf = (row: ReadRow): string => (typeof row.fanout === "string" ? row.fanout : "?");
+
+/** The orders added and dropped since `ids`, as one model-visible block, or null. */
+const changedSince = (now: Standing, ids: readonly string[]): string | null => {
+  const known = new Set(ids);
+  const added = [...now.orders.values()].filter((row) => !known.has(row.id));
+  const byId = new Map(now.rows.map((row) => [row.id, row]));
+  const dropped = ids
+    .filter((id) => !now.orders.has(id))
+    .map((id) => byId.get(id))
+    .filter((row): row is ReadRow => row !== undefined);
+  if (!added.length && !dropped.length) return null;
+  const fanouts = [...new Set([...added, ...dropped].map(fanoutOf))].join(", ");
+  const lines = [
+    `Workit: the lead changed the standing orders for fanout ${fanouts} while you run. They apply to you now and override your brief's STANDING list.`,
+    ...added.map((row) => `  - new: ${String(row.what)}`),
+    ...dropped.map(
+      (row) =>
+        `  - no longer in force: ${String(row.what)}${row.stop ? " (the stop is lifted: continue your brief)" : ""}`,
+    ),
+  ];
+  if (added.some((row) => row.stop === true))
+    lines.push(
+      "Stop now: make no further changes, close what you opened, and report to the lead with your branch, head SHA, what is done and what is not.",
+    );
+  return lines.join("\n");
+};
+
+/**
+ * What changed since this agent last saw the standing orders; null when
+ * nothing did or it works for no fanout. An agent seen for the first time is
+ * told every order in force. Marks the revision seen, so a host that keeps
+ * each answer in the transcript gets the block once.
+ */
+export const standingDelta = (input: HookInput): string | null => {
+  try {
+    const where = located(input);
+    if (!where) return null;
+    const seen = readStandingSeen(where.file);
+    if (seen.rev === where.rev) return null;
+    const now = standingFor(input, where.store, where.rev);
+    writeStandingSeen(where.file, { rev: where.rev, ids: [...now.orders.keys()] });
+    return changedSince(now, seen.ids);
+  } catch {
+    return null;
+  }
+};
+
+const sinceStart = new Map<string, { rev: string; text: string | null }>();
+
+/**
+ * For a host that rebuilds its context on every model call (OpenCode): the
+ * changes since this agent's first call, on every call while they stand.
+ * The first call records the baseline (its brief carries those orders); the
+ * ledger is read again only when the revision moves.
+ */
+export const standingSinceStart = (input: HookInput): string | null => {
+  try {
+    const store = input.session.id ? gitStoreDir(input.cwd) : null;
+    if (!store) return null;
+    const rev = readStandingRev(store) ?? "";
+    const file = standingSeenFile(store, input.session.id, input.session.agentId);
+    const cached = sinceStart.get(file);
+    if (cached?.rev === rev) return cached.text;
+    let text: string | null = null;
+    if (rev) {
+      const now = standingFor(input, store, rev);
+      const seen = readStandingSeen(file);
+      let ids = seen.ids;
+      if (seen.rev === null) {
+        // Seen before any order existed: every order is new to it.
+        ids = cached ? [] : [...now.orders.keys()];
+        writeStandingSeen(file, { rev, ids });
+      }
+      text = changedSince(now, ids);
+    }
+    sinceStart.set(file, { rev, text });
+    if (sinceStart.size > 256) sinceStart.delete(sinceStart.keys().next().value!);
+    return text;
+  } catch {
+    return null;
+  }
+};

package/src/ledger.ts

@@ -57,6 +57,7 @@ import { hostAwareLockTimeout } from "./core/store-lock";
 import { vcsConfig } from "./core/vcs-config";
 import { GIT_TIMEOUTS, currentBranch, headSha, patchId, worktreeTree } from "./git/rev";
 import { hostSessionFromEnv, issuedBinding } from "./host-session";
+import { bumpStandingRev } from "./hooks/standing-signal";
 import { resolveStore } from "./store/paths";
 
 export const LEDGER_VERSION = 1;
@@ -165,8 +166,16 @@ export type VerdictRow = RowCommon & {
   evidenceRefs: string[];
 };
 export type HandoffRow = RowCommon & { type: "handoff"; note: string | null; next: string };
-/** A lead's standing order for every worker of a fanout ("no new dependencies"). */
-export type StandingRow = RowCommon & { type: "standing"; fanout: string; what: string };
+/**
+ * A lead's standing order for every worker of a fanout ("no new dependencies").
+ * `stop` marks the stop line: running workers stop and report.
+ */
+export type StandingRow = RowCommon & {
+  type: "standing";
+  fanout: string;
+  what: string;
+  stop?: true;
+};
 /** Ends one standing order (`target`), or every one recorded before it (null). */
 export type StandingClearedRow = RowCommon & {
   type: "standing.cleared";
@@ -1827,11 +1836,27 @@ function leadOnly(context: RecordContext, lead: string | null): LedgerResult<voi
   );
 }
 
+/** Running workers see a new revision on their next hook (hooks/standing.ts). */
+function signalStanding<T extends { id: string }>(
+  cwd: string,
+  result: LedgerResult<T>,
+): LedgerResult<T> {
+  const root = result.ok ? storeRoot(cwd) : null;
+  if (result.ok && root?.ok && root.value.shared) bumpStandingRev(root.value.root, result.value.id);
+  return result;
+}
+
+/** The stop line's text, as briefs and running workers read it. */
+export const stopOrderText = (note: string | null): string =>
+  `STOP: start nothing new, stop every process you started (dev servers, browsers, watchers), commit only finished work, and report to the lead now${note ? ` (${note})` : ""}`;
+
 export function recordStanding(
   context: RecordContext,
-  input: { fanout: string; lead: string | null; what?: string },
+  input: { fanout: string; lead: string | null; what?: string; stop?: boolean },
 ): LedgerResult<StandingRow> {
-  const what = required(input.what, "<order>");
+  const what: LedgerResult<string> = input.stop
+    ? { ok: true, value: stopOrderText(input.what?.trim() || null) }
+    : required(input.what, "<order>");
   if (!what.ok) return what;
   // One order per line of every brief: a newline or control character would
   // let an order forge other brief fields.
@@ -1845,16 +1870,18 @@ export function recordStanding(
   if (!lead.ok) return lead;
   const link = checkSupersede(context, "standing");
   if (!link.ok) return link;
-  return appendRow<StandingRow>(
+  const recorded = appendRow<StandingRow>(
     context.cwd,
     {
       ...common(context, noteKey(context)),
       type: "standing",
       fanout: input.fanout,
       what: what.value,
+      ...(input.stop ? { stop: true as const } : {}),
     },
     { now: context.now },
   );
+  return signalStanding(context.cwd, recorded);
 }
 
 /** Clear one standing order by id (it must be in force), or all of them; lead only. */
@@ -1883,18 +1910,48 @@ export function clearStanding(
         `workit ledger standing list --fanout ${input.fanout}`,
       );
   }
-  return appendRow<StandingClearedRow>(
+  return signalStanding(
     context.cwd,
-    {
-      ...common(context, noteKey(context)),
-      type: "standing.cleared",
-      fanout: input.fanout,
-      target: input.target,
-    },
-    { now: context.now },
+    appendRow<StandingClearedRow>(
+      context.cwd,
+      {
+        ...common(context, noteKey(context)),
+        type: "standing.cleared",
+        fanout: input.fanout,
+        target: input.target,
+      },
+      { now: context.now },
+    ),
   );
 }
 
+/** Lift the stop line: clear each stop order in force and keep the others; lead only. */
+export function liftStop(
+  context: RecordContext,
+  input: { fanout: string; lead: string | null; leads?: readonly string[] | null },
+): LedgerResult<StandingClearedRow[]> {
+  const lead = leadOnly(context, input.lead);
+  if (!lead.ok) return lead;
+  const ledger = readLedger(context.cwd);
+  if (!ledger.ok) return ledger;
+  const stops = activeStanding(ledger.value.rows, input.fanout, input.leads ?? null).filter(
+    (row) => row.stop === true,
+  );
+  if (!stops.length)
+    return err(
+      "not_found",
+      `no stop line in force for fanout ${input.fanout}`,
+      `workit ledger standing list --fanout ${input.fanout}`,
+    );
+  const cleared: StandingClearedRow[] = [];
+  for (const stop of stops) {
+    const row = clearStanding(context, { ...input, target: stop.id });
+    if (!row.ok) return row;
+    cleared.push(row.value);
+  }
+  return { ok: true, value: cleared };
+}
+
 /**
  * Is `branch` checked out, with uncommitted changes, in another worktree of
  * this repository? (`codeKey` sees only the cwd's own worktree.)