@brainervirus/workit-core 8.16.0 → 8.17.1

package/src/core/resources.ts

@@ -20,6 +20,16 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { tailLines, type CheckRun } from "../checks";
+import { stateDir } from "./heavy";
+
+export { stateDir };
+export {
+  probeScope,
+  scopePrefix,
+  scopeSupport,
+  type ScopeProbe,
+  type ScopeSupport,
+} from "./heavy-scope";
 
 /** Named checks that take the lease when nothing is configured. */
 export const DEFAULT_HEAVY_CHECKS = ["test", "build", "typecheck"];
@@ -183,17 +193,6 @@ export function resolveResourceSettings(
 // ---------------------------------------------------------------------------
 // the machine lease
 
-/** Workit's state dir for `env` (the logger's resolution, over an explicit env). */
-export function stateDir(env: NodeJS.ProcessEnv, platform: NodeJS.Platform = process.platform) {
-  if (env.WORKFLOW_TOOLKIT_STATE) return env.WORKFLOW_TOOLKIT_STATE;
-  if (env.XDG_STATE_HOME) return path.join(env.XDG_STATE_HOME, "workit");
-  const home = env.HOME || os.homedir();
-  if (platform === "darwin") return path.join(home, "Library", "Application Support", "workit");
-  if (platform === "win32")
-    return path.join(env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "workit");
-  return path.join(home, ".local", "state", "workit");
-}
-
 export const leaseDir = (env: NodeJS.ProcessEnv): string => path.join(stateDir(env), "leases");
 
 export type LeaseRecord = {
@@ -588,71 +587,6 @@ export function describeHolder(holder: LeaseHolder, now = Date.now()): string {
   return `${holder.check}, pid ${holder.pid}${holder.session ? `, session ${holder.session}` : ""}, ${age}, ${holder.cwd}`;
 }
 
-// ---------------------------------------------------------------------------
-// the systemd user scope
-
-export type ScopeSupport = { ok: true } | { ok: false; reason: string };
-
-const onPath = (command: string, env: NodeJS.ProcessEnv): boolean =>
-  (env.PATH ?? "")
-    .split(path.delimiter)
-    .filter(Boolean)
-    .some((dir) => {
-      try {
-        fs.accessSync(path.join(dir, command), fs.constants.X_OK);
-        return true;
-      } catch {
-        return false;
-      }
-    });
-
-/**
- * Can heavy checks run in their own `systemd-run --user --scope`? Needs Linux,
- * `systemd-run` on PATH, a running user manager, and the memory and cpu
- * controllers delegated to it (cgroup v2).
- */
-export function scopeSupport(
-  env: NodeJS.ProcessEnv,
-  platform: NodeJS.Platform = process.platform,
-  read: (file: string) => string | null = readText,
-): ScopeSupport {
-  if (platform !== "linux") return { ok: false, reason: `no systemd scopes on ${platform}` };
-  if (!onPath("systemd-run", env)) return { ok: false, reason: "systemd-run is not on PATH" };
-  const uid = process.getuid?.() ?? 0;
-  const runtime = env.XDG_RUNTIME_DIR || `/run/user/${uid}`;
-  if (!fs.existsSync(path.join(runtime, "systemd", "private")))
-    return { ok: false, reason: "no user systemd manager is running" };
-  const controllers = read(
-    `/sys/fs/cgroup/user.slice/user-${uid}.slice/user@${uid}.service/cgroup.controllers`,
-  );
-  if (controllers === null)
-    return { ok: false, reason: "cgroup v2 is not mounted for the user manager" };
-  const missing = ["memory", "cpu"].filter((name) => !controllers.split(/\s+/u).includes(name));
-  if (missing.length)
-    return { ok: false, reason: `the user manager is not delegated ${missing.join(" and ")}` };
-  return { ok: true };
-}
-
-/** The `systemd-run` prefix that runs a command in its own limited scope. */
-export function scopePrefix(
-  unit: string,
-  settings: Pick<ResourceSettings, "memoryMax" | "cpuQuota">,
-) {
-  return [
-    "systemd-run",
-    "--user",
-    "--scope",
-    "--quiet",
-    "--collect",
-    `--unit=${unit}`,
-    "-p",
-    `MemoryMax=${settings.memoryMax}`,
-    "-p",
-    `CPUQuota=${settings.cpuQuota}`,
-    "--",
-  ];
-}
-
 /** systemd-run's own failure before it ran the command (bus, unit, property). */
 const SCOPE_START_FAILURE =
   /^Failed to (?:connect to bus|create bus connection|start transient scope unit|parse \S+?=)/u;
@@ -745,3 +679,25 @@ export function firstNotice(
   }
   return true;
 }
+
+export type SlotState = {
+  slot: number;
+  /** The lease in this slot, or null when it is free. */
+  holder: LeaseHolder | null;
+  /** Why the lease in it no longer holds (the next acquirer reclaims it). */
+  stale: string | null;
+};
+
+/** What each of `slots` lease slots holds right now. Read-only: nothing is reclaimed. */
+export function leaseSlots(dir: string, slots: number, probe: LeaseProbe = {}): SlotState[] {
+  const states: SlotState[] = [];
+  for (let slot = 0; slot < slots; slot += 1) {
+    const lease = parseLease(readText(path.join(dir, `slot-${slot}.json`)));
+    states.push({
+      slot,
+      holder: lease ? holderOf(lease) : null,
+      stale: lease ? staleReason(lease, probe) : null,
+    });
+  }
+  return states;
+}

package/src/core/workspaces.ts

@@ -143,6 +143,13 @@ const workspaceConfigSchema = z
     defaultEndpoint: z.unknown().optional(),
     /** How a normal-risk behavior change is verified (S17); same rules as grants. */
     verification: z.enum(["self", "independent"]).optional(),
+    /**
+     * Who does the work (skills and `fanout plan` read it): `inline-first`
+     * (default) keeps the lead working itself and refuses a slice without a
+     * reason to delegate; `lead-orchestrates` allows slices without one.
+     * Read leniently (workspaceDelegation): an unknown value reads as unset.
+     */
+    delegation: z.unknown().optional(),
     /**
      * Whether commits get the `Workit-Session:` trailer (default true). With
      * `false`, `workit git commit` and the session hook write none and
@@ -766,6 +773,21 @@ export const workspaceLiveSessionGuard = (cwd: string, dir?: string): boolean =>
   inheritedSetting(cwd, dir, (entry) => typeof entry.liveSessionGuard === "boolean")?.source
     ?.liveSessionGuard !== false;
 
+export const DELEGATION_MODES = ["inline-first", "lead-orchestrates"] as const;
+export type DelegationMode = (typeof DELEGATION_MODES)[number];
+
+const isDelegation = (value: unknown): value is DelegationMode =>
+  (DELEGATION_MODES as readonly unknown[]).includes(value);
+
+/**
+ * The workspace's `delegation` mode, default `inline-first`; inherited like
+ * `trailers`. A value this version does not know reads as unset.
+ */
+export const workspaceDelegation = (cwd: string, dir?: string): DelegationMode => {
+  const source = inheritedSetting(cwd, dir, (entry) => isDelegation(entry.delegation))?.source;
+  return isDelegation(source?.delegation) ? source.delegation : "inline-first";
+};
+
 const hostFamily = (host: string): string => host.replace(/_(?:cli|desktop)$/u, "");
 
 const TIER_KEYS = new Set(["mundane", "standard", "hard"]);

package/src/fanout-brief.ts

@@ -112,6 +112,7 @@ const rules = (
       ? '  3. Commit with plain `git commit -m <msg> --trailer "Workit-Session: <the WORKIT_SESSION_ID in your env>" --trailer "<your host attribution trailer>" -- <paths in SCOPE>`; push only if this brief says so.'
       : "  3. Commit with `workit git commit -m <msg> -- <paths in SCOPE>`; push only if this brief says so.",
     "  4. Never record a verdict on your own work.",
+    "  5. Run tests, lint, typecheck and builds only through `workit check` (a named check, or `workit check --heavy -- <cmd>`): one machine-wide lease queues every agent, so never a hand-made flock; `workit lock status` shows who holds it.",
   ];
 };
 
@@ -210,6 +211,7 @@ export function renderBrief(
     "ACCEPTANCE:",
     ...slice.acceptance.map((line) => `  - ${line}`),
     `VERIFY: ${slice.verify.join("; ")}`,
+    ...(slice.reason ? [`REASON: ${slice.reason}`] : []),
     `TIER: ${slice.tier}`,
     ...(model
       ? [`  model: ${model.model}  (fanout.tierModels in workspace ${model.workspace})`]

package/src/fanout.ts

@@ -20,7 +20,7 @@
 //
 // Each slice's `hash` covers what it is (goal, acceptance, verify, forbidden,
 // scope, owns, branch, base, dependencies), not how it is briefed (tier,
-// timebox, context, issues) or where its worktree goes. A re-plan that changes a
+// reason, timebox, context, issues) or where its worktree goes. A re-plan that changes a
 // slice starts a new run for that slice alone: its `hashSince` moves to now,
 // and only ledger rows recorded under its hash (worktree rows carry
 // `sliceHash`) or since then link a gone branch's merged PR to it or count as
@@ -45,6 +45,7 @@ import {
   storeRoot,
   type LedgerActor,
 } from "./ledger";
+import { workspaceDelegation, type DelegationMode } from "./core/workspaces";
 import { stackFileName } from "./stack";
 
 export const FANOUT_VERSION = 1;
@@ -58,6 +59,8 @@ export type Slice = {
   base: string;
   worktree: string;
   tier: Tier;
+  /** Why this work is delegated; required under `delegation: inline-first`. */
+  reason: Reason | null;
   dependsOn: string[];
   /** The file-scope manifest: globs (`*`, `**`, `?`, `{a,b}`) relative to the repo root. */
   scope: string[];
@@ -77,6 +80,10 @@ export type Slice = {
   hashSince: string;
 };
 
+/** Why a slice is delegated at all (the brief's REASON line). */
+export const REASONS = ["explore", "parallel", "backstop", "high-risk-verify"] as const;
+export type Reason = (typeof REASONS)[number];
+
 export const FAN_IN_MODES = ["prs", "integration"] as const;
 export type FanInMode = (typeof FAN_IN_MODES)[number];
 
@@ -321,6 +328,8 @@ export type PlanDefaults = {
   root: string;
   /** Where default worktrees go: `<repo>-wt/` next to the main checkout. */
   worktreeRoot: string;
+  /** Under inline-first (the default when absent), a slice needs a reason. */
+  delegation?: DelegationMode;
 };
 
 type Parsed = { ok: true; plan: FanoutFile } | { ok: false; problems: string[] };
@@ -405,6 +414,15 @@ export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string |
     const tier = item.tier;
     if (typeof tier !== "string" || !(TIERS as readonly string[]).includes(tier))
       problems.push(`${where}: tier must be one of ${TIERS.join(", ")}`);
+    const rawReason = typeof item.reason === "string" ? item.reason.trim() : item.reason;
+    let reason: Reason | null = null;
+    if (rawReason === undefined || rawReason === null || rawReason === "") {
+      if ((defaults.delegation ?? "inline-first") === "inline-first")
+        problems.push(
+          `${where}: reason is empty; delegation is inline-first, so name why this is delegated: ${REASONS.join(", ")} (or set delegation to lead-orchestrates in the workspace)`,
+        );
+    } else if ((REASONS as readonly unknown[]).includes(rawReason)) reason = rawReason as Reason;
+    else problems.push(`${where}: reason must be one of ${REASONS.join(", ")}`);
     const dependsOn = textList(item.dependsOn ?? []);
     if (dependsOn === null) problems.push(`${where}: dependsOn must be a list of slice ids`);
     const issues = textList(item.issue ?? []);
@@ -420,6 +438,7 @@ export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string |
         optional("worktree") ?? path.join(defaults.worktreeRoot, id),
       ),
       tier: tier as Tier,
+      reason,
       dependsOn: [...new Set(dependsOn ?? [])],
       scope,
       owns,
@@ -782,7 +801,7 @@ export const planLeads = (
 
 /**
  * sha256 (16 hex) of the slice's definition. Brief-only fields (tier,
- * timebox, context, issues) and the worktree path are left out, so fixing a typo in
+ * reason, timebox, context, issues) and the worktree path are left out, so fixing a typo in
  * them never re-dispatches landed work.
  */
 export function sliceHash(slice: Slice): string {
@@ -791,6 +810,7 @@ export function sliceHash(slice: Slice): string {
     hash: _hash,
     hashSince: _since,
     tier: _tier,
+    reason: _reason,
     timebox: _timebox,
     context: _context,
     issues: _issues,
@@ -839,6 +859,9 @@ function parseStored(raw: unknown): FanoutFile | null {
       base: text(item.base) || raw.trunk,
       worktree: text(item.worktree),
       tier: (TIERS as readonly unknown[]).includes(item.tier) ? (item.tier as Tier) : "standard",
+      reason: (REASONS as readonly unknown[]).includes(item.reason)
+        ? (item.reason as Reason)
+        : null,
       dependsOn: list(item.dependsOn),
       scope: globs(item.scope),
       owns: globs(item.owns),
@@ -1043,6 +1066,7 @@ export function planFanout(
       trunk: input.trunk ?? defaultTrunk(cwd),
       root: mainCheckout(cwd),
       worktreeRoot: worktreeRoot(cwd),
+      delegation: workspaceDelegation(cwd),
     },
     input.name,
   );

package/src/hooks/deadline.ts

@@ -0,0 +1,228 @@
+// The hook's own deadline (issue #309). A host kills a hook past its timeout
+// and discards its output; under machine load that silently drops the Workit
+// context and gates. Past this deadline, below every host timeout, the hook
+// answers a minimal valid result naming the skip and records it for doctor.
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "../core/logger";
+import { dispatchHook } from "./handle";
+import type { HookDecision, HookEventKind, HostAdapter, RenderedHook } from "./protocol";
+
+export const HOOK_SKIP_TEXT = "workit context skipped: host under load";
+
+/** For a host without its own row; Claude Code's prompt/tool/subagent value. */
+export const HOOK_DEADLINE_MS = 8_000;
+
+/**
+ * Per host, by native event ("" for the rest): a margin below the host's own
+ * timeout, left for a dispatch that started in time. Claude Code registers
+ * 15 s (20 s for SessionStart and Stop); Codex defaults to 600 s and Workit
+ * registers 20 s for Stop; Cursor defaults to 60 s.
+ */
+export const HOST_DEADLINES: Readonly<Record<string, Readonly<Record<string, number>>>> = {
+  claude_code: { "": 8_000, SessionStart: 16_000, Stop: 16_000 },
+  codex_cli: { "": 45_000, Stop: 16_000 },
+  codex_desktop: { "": 45_000, Stop: 16_000 },
+  cursor: { "": 45_000 },
+};
+
+/** One JSON HookSkip per line; `workit doctor` (hook_deadline) reads it. */
+export const HOOK_SKIPS_FILE = "hook-skips.jsonl";
+
+/** `skip`: the hook answered the minimal result; `late`: it answered in full, past the deadline. */
+export type HookSkip = {
+  at: string;
+  host: string;
+  event: HookEventKind | null;
+  outcome: "skip" | "late";
+  stage: "input" | "dispatch" | "done";
+  elapsedMs: number;
+};
+
+export type HookDeadline = {
+  /** Milliseconds from `startedAt`; by default WORKIT_HOOK_DEADLINE_MS, else HOST_DEADLINES. */
+  deadlineMs?: number;
+  /**
+   * Epoch ms the budget counts from; the call by default. A hook-process
+   * entry passes PROCESS_START so its start-up and module load count too.
+   */
+  startedAt?: number;
+  now?: () => number;
+  /** The handler step; dispatchHook unless a host handles the event itself. */
+  dispatch?: (
+    adapter: HostAdapter,
+    raw: unknown,
+    env: NodeJS.ProcessEnv,
+  ) => (RenderedHook & { error: string | null }) | Promise<RenderedHook & { error: string | null }>;
+  record?: (skip: HookSkip) => void;
+};
+
+export type DeadlineResult = RenderedHook & { error: string | null; skipped: boolean };
+
+const override = (env: NodeJS.ProcessEnv): number | null => {
+  const value = Number(env.WORKIT_HOOK_DEADLINE_MS);
+  return Number.isFinite(value) && value > 0 ? value : null;
+};
+
+/** The deadline for one native event; `native` undefined gives the host's shortest. */
+export const hookDeadlineMs = (env: NodeJS.ProcessEnv, host = "", native?: string): number => {
+  const row = HOST_DEADLINES[host];
+  return (
+    override(env) ??
+    (row
+      ? native === undefined
+        ? Math.min(...Object.values(row))
+        : (row[native] ?? row[""])
+      : HOOK_DEADLINE_MS)
+  );
+};
+
+const skipsFile = (stateDir: string) => path.join(stateDir, HOOK_SKIPS_FILE);
+
+/** Best effort: a read-only state dir never changes the hook's answer. */
+export const recordHookSkip = (skip: HookSkip, stateDir: string = resolveStateDir()): void => {
+  try {
+    mkdirSync(stateDir, { recursive: true });
+    appendFileSync(skipsFile(stateDir), `${JSON.stringify(skip)}\n`);
+  } catch {
+    // The skip still reached the host; only the doctor count is lost.
+  }
+};
+
+const QUIET: ReadonlySet<HookEventKind | null> = new Set([
+  "stop",
+  "subagent.stop",
+  "shell.post",
+  "compact.pre",
+  "prompt.submit",
+  null,
+]);
+
+/** The minimal answer: the skip named where the event has a model channel, else no decision. */
+const skipDecision = (event: HookEventKind | null): HookDecision =>
+  QUIET.has(event) ? { kind: "none" } : { kind: "context", text: HOOK_SKIP_TEXT };
+
+const TIMED_OUT = Symbol("timed out");
+
+/** Resolves to `work`'s value, or TIMED_OUT when `ms` passes first. */
+export const within = async <T>(work: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<typeof TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(TIMED_OUT), Math.max(0, ms));
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([work, expired]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+export const isTimedOut = (value: unknown): value is typeof TIMED_OUT => value === TIMED_OUT;
+
+type Budget = Required<Pick<HookDeadline, "now" | "record">> & {
+  startedAt: number;
+  /** The host's shortest until the payload names its event. */
+  deadlineMs: number;
+  /** The host whose HOST_DEADLINES row refines it per event; null when the caller fixed it. */
+  host: string | null;
+};
+
+/** Epoch ms this process started. */
+export const PROCESS_START = performance.timeOrigin;
+
+export const hookBudget = (
+  env: NodeJS.ProcessEnv,
+  options: HookDeadline = {},
+  host = "",
+): Budget => {
+  const now = options.now ?? Date.now;
+  return {
+    now,
+    record: options.record ?? ((skip) => recordHookSkip(skip)),
+    startedAt: options.startedAt ?? now(),
+    deadlineMs: options.deadlineMs ?? hookDeadlineMs(env, host),
+    host: options.deadlineMs === undefined ? host : null,
+  };
+};
+
+/** Reads the whole payload, or null when the deadline passes first. */
+export const readWithin = async (
+  stdin: AsyncIterable<unknown> | Iterable<unknown>,
+  budget: Budget,
+): Promise<string | null> => {
+  const read = (async () => {
+    let text = "";
+    for await (const chunk of stdin) text += String(chunk);
+    return text;
+  })();
+  const text = await within(read, budget.startedAt + budget.deadlineMs - budget.now());
+  return isTimedOut(text) ? null : text;
+};
+
+/** Records one outcome; returns the parsed native event name for rendering. */
+const note = (
+  adapter: HostAdapter,
+  raw: unknown,
+  env: NodeJS.ProcessEnv,
+  budget: Budget,
+  outcome: HookSkip["outcome"],
+  stage: HookSkip["stage"],
+): { native: string | null; event: HookEventKind | null } => {
+  const parsed = raw === undefined ? null : adapter.parse(raw, env);
+  const event = parsed ? (parsed.ok ? parsed.input.event.kind : parsed.event) : null;
+  budget.record({
+    at: new Date(budget.now()).toISOString(),
+    host: adapter.descriptor.host,
+    event,
+    outcome,
+    stage,
+    elapsedMs: Math.round(budget.now() - budget.startedAt),
+  });
+  return { native: parsed?.native ?? null, event };
+};
+
+/** The minimal result for a skipped hook, rendered in the host's own shape. */
+export const skippedHook = (
+  adapter: HostAdapter,
+  raw: unknown,
+  env: NodeJS.ProcessEnv,
+  budget: Budget,
+  stage: HookSkip["stage"],
+): DeadlineResult => {
+  const { native, event } = note(adapter, raw, env, budget, "skip", stage);
+  return {
+    ...adapter.render(skipDecision(event), native),
+    error: `${HOOK_SKIP_TEXT} (past the ${budget.deadlineMs} ms hook deadline)`,
+    skipped: true,
+  };
+};
+
+/**
+ * dispatchHook under the deadline: a hook already past it answers the
+ * minimal result without running the handler, and a handler that overruns
+ * it is abandoned. A synchronous handler cannot be interrupted once started;
+ * one that finishes late answers in full and is recorded as late.
+ */
+export const dispatchWithin = async (
+  adapter: HostAdapter,
+  raw: unknown,
+  env: NodeJS.ProcessEnv,
+  budget: Budget,
+  dispatch: NonNullable<HookDeadline["dispatch"]> = dispatchHook,
+): Promise<DeadlineResult> => {
+  const native = (raw as { hook_event_name?: unknown } | null)?.hook_event_name;
+  if (budget.host !== null && typeof native === "string")
+    budget.deadlineMs = hookDeadlineMs(env, budget.host, native);
+  const remaining = () => budget.startedAt + budget.deadlineMs - budget.now();
+  const result =
+    remaining() > 0
+      ? await within(
+          Promise.resolve().then(() => dispatch(adapter, raw, env)),
+          remaining(),
+        )
+      : TIMED_OUT;
+  if (isTimedOut(result)) return skippedHook(adapter, raw, env, budget, "dispatch");
+  if (remaining() < 0) note(adapter, raw, env, budget, "late", "done");
+  return { ...result, skipped: false };
+};

package/src/hooks/descriptor.ts

@@ -19,6 +19,8 @@ export type HostDescriptor = {
     channel: "permissionDecision" | "exit2+json" | "effect" | "block" | null;
     /** A parse or handler failure on a pre-tool gate denies instead of passing. */
     failClosed: boolean;
+    /** The pre-shell hook can replace the command before it runs (the heavy-command lease). */
+    rewrite: Support;
   };
   context: {
     sessionStart: Support;

package/src/hooks/handle.ts

@@ -9,6 +9,7 @@ import type { HostDescriptor, Support } from "./descriptor";
 import { branchGuidance } from "../core/branch";
 import { workspaceTrailers } from "../core/workspaces";
 import { recordIssuedSession } from "../host-session";
+import { heavyDenial, heavyGate, rewriteNote, splitDenial } from "./heavy-gate";
 import { shellPolicy } from "./policy";
 import {
   callKey,
@@ -162,6 +163,19 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         ? shellGate(input.cwd, event.command, liveOwner(input, descriptor.transport), event.dialect)
         : NONE;
       if (gate.kind === "deny") return gate;
+      // A heavy command runs under the machine lease: rewritten where the
+      // host can replace the command, else denied with the exact rewrite.
+      // Every gate above passed on the original command (ruling mvid5onk).
+      const plan = heavyGate(input.cwd, event.command, {
+        host: input.host,
+        dialect: event.dialect,
+        permissionMode: input.permissionMode,
+      });
+      if (plan.kind === "split" && canDeny) return splitDenial(plan);
+      const rewrites = usable(descriptor.shellPolicy.rewrite);
+      if (plan.kind === "rewrite" && !rewrites && canDeny) return heavyDenial(event.command, plan);
+      const lease = plan.kind === "rewrite" && rewrites ? plan : null;
+      const aside = plan.kind === "passthrough" ? plan.note : null;
       // The command will run: note HEAD so the post-tool hook (or the next
       // command, without one) can tell whether a raw commit moved it.
       noteRawCommit(
@@ -169,13 +183,28 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         event.command,
         postTool ? callKey(event.toolUseId, event.command) : NEXT_COMMAND,
       );
+      const rewritten = (text: string | null): HookDecision =>
+        lease
+          ? {
+              kind: "rewrite",
+              command: lease.command,
+              input: event.toolInput ? { ...event.toolInput, command: lease.command } : null,
+              text,
+            }
+          : NONE;
       // An in-process plugin shows nudges on the tool result (shellNudge):
       // spending the once-per-session nudge here would lose it.
-      if (descriptor.transport !== "hook-process") return NONE;
-      return withContextLine(
-        canDeny ? rawGitPre(input, event.command) : NONE,
+      if (descriptor.transport !== "hook-process") return rewritten(null);
+      const nudged = withContextLine(
+        withContextLine(canDeny ? rawGitPre(input, event.command) : NONE, aside),
         shipNudge(input, event.command),
       );
+      if (!lease) return nudged;
+      return rewritten(
+        [rewriteNote(lease), nudged.kind === "context" ? nudged.text : null]
+          .filter(Boolean)
+          .join("\n"),
+      );
     }
     case "shell.post":
       if (usable(descriptor.events["shell.post"].support))

package/src/hooks/heavy-gate.ts

@@ -0,0 +1,91 @@
+// The heavy-command gate (issue #325, ruling mvid5onk): after every Workit
+// gate passed on the original command, a raw heavy command (tests, builds,
+// lint, typecheck, installs; core/heavy.ts) runs under the machine-wide
+// heavy-check lease:
+//   - one simple heavy command: rewritten to `workit check --heavy -- <cmd>`
+//     where the host can replace it (Claude Code, OpenCode, Pi), else denied
+//     with that exact command (Codex, Cursor);
+//   - a chain with heavy parts: denied, naming each part's lease command
+//     (never `bash -c`);
+//   - a command a host permission rule names, or one whose wrapper only an
+//     allow for `workit` would let through: left alone, with a note.
+import {
+  claudeRules,
+  codexRules,
+  cursorRules,
+  opencodeRules,
+  type RuleRead,
+} from "../core/heavy-rules";
+import { heavyPlan, workitOnPath, type HeavyPlan } from "../core/heavy";
+import { maybeHeavy } from "../core/heavy-words";
+import type { HookDecision, HostId } from "./protocol";
+import type { ShellDialect } from "./shell-words";
+
+/** The host's readable permission rules (null where it keeps none the hook could read). */
+const rulesFor = (host: HostId, cwd: string, env: NodeJS.ProcessEnv): RuleRead | null => {
+  switch (host) {
+    case "claude_code":
+      return claudeRules(cwd, env);
+    case "opencode":
+      return opencodeRules(cwd, env);
+    case "codex_cli":
+    case "codex_desktop":
+      return codexRules(cwd, env);
+    case "cursor":
+      return cursorRules(cwd, env);
+    case "pi":
+      return null;
+  }
+};
+
+export type GateOptions = {
+  host: HostId;
+  dialect?: ShellDialect;
+  /** Claude `permission_mode`: bypassPermissions skips the allowlist check. */
+  permissionMode?: string | null;
+  env?: NodeJS.ProcessEnv;
+};
+
+/**
+ * The gate's plan for `command`, run after the Workit gates allowed it.
+ * Nothing when no `workit` is on PATH (the wrapper could not run) or the
+ * host sets WORKIT_HEAVY_GATE=0. Never throws.
+ */
+export function heavyGate(cwd: string, command: string, options: GateOptions): HeavyPlan {
+  const env = options.env ?? process.env;
+  try {
+    // The launchers' cheap word check first: most commands stop here.
+    if (env.WORKIT_HEAVY_GATE === "0" || !maybeHeavy(command, cwd, env) || !workitOnPath(env))
+      return { kind: "none" };
+    return heavyPlan(command, {
+      cwd,
+      env,
+      dialect: options.dialect ?? "posix",
+      rules: rulesFor(options.host, cwd, env),
+      bypass: options.permissionMode === "bypassPermissions",
+    });
+  } catch {
+    return { kind: "none" };
+  }
+}
+
+/** The model-visible line after a rewrite. */
+export const rewriteNote = (plan: Extract<HeavyPlan, { kind: "rewrite" }>): string =>
+  `workit: this heavy command (${plan.reason}) runs under the machine-wide heavy-check lease as \`${plan.command}\`: it waits while another heavy check holds the lease (\`workit lock status\` shows who). Run heavy commands that way yourself; \`workit help lock\` explains the lease.`;
+
+/** The deny on hosts that cannot rewrite: the exact command to run instead. */
+export const heavyDenial = (
+  original: string,
+  plan: Extract<HeavyPlan, { kind: "rewrite" }>,
+): HookDecision => ({
+  kind: "deny",
+  reason: `heavy_command: \`${original.trim()}\` is heavy (${plan.reason}) and must run under the machine-wide heavy-check lease, so parallel agents cannot exhaust this machine's memory and CPU. Run exactly: ${plan.command}`,
+  unblock: plan.command,
+});
+
+/** The deny for a chain with heavy parts. */
+export const splitDenial = (plan: Extract<HeavyPlan, { kind: "split" }>): HookDecision => ({
+  kind: "deny",
+  reason: plan.reason,
+  unblock: plan.unblock,
+});