@worca/app 1.1.1 → 1.2.0-rc.1

package/src/core/failure-policy.mjs

@@ -0,0 +1,201 @@
+// failure-policy.mjs — the ONE place that decides what a failure does to a run.
+//
+// Every site in the engine that can see a failure — the per-node retry loop, the
+// flow-card dispatcher, the budget gate, run()/resume()'s setup and shell catch
+// blocks — asks `resolveFailure()` for a VERDICT and then enacts it with its own
+// mechanics (throwing the pause sentinel through the scheduler, picking a resume
+// point, stamping a setup replay). No site makes the decision itself, so shifting
+// a case from "terminal error" to "pause" (or back) is a one-cell edit in
+// FAILURE_POLICY below plus its row in test/failure-policy.test.mjs.
+//
+// Inputs (all plain values — this module is pure and imports nothing):
+//   site     where the failure surfaced (SITES)
+//   cls      classifyError()'s class, or null for an unclassified error; the
+//            budget gate passes its cost code
+//   auto     --yes / headless (true) or interactive (false)
+//   attempt  1-based attempt number, for bounded retries
+//   answer   the recovery prompt's answer once the user gave one ('retry'|'giveup')
+//
+// Verdicts:
+//   { outcome: 'retry' }                          try again (the site backs off)
+//   { outcome: 'prompt', options: [...] }         ask the user (interactive only)
+//   { outcome: 'pause', reason: ReasonCode }      park the run, resumable
+//   { outcome: 'error' }                          end the run as a terminal error
+//
+// Control-flow signals — a PauseError, an AbortError, a pause already requested,
+// the user's Stop — are NOT failures and never reach this table; every site guards
+// for them first. Stop is user-only and always ends the run as 'stopped'.
+//
+// A verdict is issued ONCE. When a site enacts 'error' it marks the error
+// terminal (markTerminal) so every enclosing catch — the flow dispatcher, the
+// shell — enacts that same verdict instead of re-deciding at its own site.
+
+/** Where a failure can surface. */
+export const SITES = Object.freeze(['node', 'flow', 'budget', 'setup', 'launch', 'shell', 'resume']);
+
+/** Machine-readable pause reasons. The human text rides `pauseDetail`. */
+export const REASON = Object.freeze({
+  USAGE_LIMIT: 'usage_limit',     // a session/usage cap that clears after a multi-hour reset
+  RECOVERABLE: 'recoverable',     // a classified (auth/quota/rate_limit/network) error the run could not outwait
+  ERROR: 'error',                 // a failure that would otherwise have ended the run
+  COST_PIPELINE: 'cost_pipeline', // the per-pipeline cost cap
+  COST_TOTAL: 'cost_total',       // the total (weekly/monthly) cost cap
+});
+export const REASON_CODES = Object.freeze(Object.values(REASON));
+
+/** Max auto-mode retries for a recoverable error before the row's `then` verdict. */
+export const RECOVERY_MAX_AUTO_ATTEMPTS = (() => {
+  const n = Number(process.env.WORCA_RECOVERY_MAX_ATTEMPTS);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 3;
+})();
+
+// ── verdict constructors ──────────────────────────────────────────────────────
+const pause = (reason) => Object.freeze({ outcome: 'pause', reason });
+const error = () => Object.freeze({ outcome: 'error' });
+/** Bounded retries (auto mode): `max` retries, then the `then` verdict. */
+const retry = (max, then) => Object.freeze({ outcome: 'retry', max, then });
+/** Interactive prompt: Retry re-runs in place; the give-up option enacts `giveUp`. */
+const prompt = (giveUp) => Object.freeze({ outcome: 'prompt', giveUp });
+
+/** One matrix cell: the verdict per run mode. */
+const cell = (auto, interactive) => Object.freeze({ auto, interactive });
+/** The same verdict in both modes. */
+const both = (v) => cell(v, v);
+
+// ── THE MATRIX ────────────────────────────────────────────────────────────────
+// Rows are keyed by site, then by error class; '*' is the row for any class the
+// site has no specific row for. Edit a cell to shift a case.
+//
+// A note on the two contested rows (PR #415 vs. the policy PR #412 shipped):
+//   node/'*'   an UNCLASSIFIED error (often a genuine bug) pauses instead of ending
+//              the run; resume retries the node in place. Flip to error() to
+//              restore "a bug ends the run".
+//   node/auth… an interactive recovery prompt's give-up option PAUSES (no Abort
+//              verdict). Flip prompt(error()) to offer Abort as a terminal error.
+export const FAILURE_POLICY = Object.freeze({
+  node: Object.freeze({
+    usage_limit: both(pause(REASON.USAGE_LIMIT)),
+    // auth/quota are user-fixable but never time-fixable — a 1s/2s/4s backoff
+    // cannot re-login or top up a balance — so auto mode pauses on the first hit.
+    // A self-parked auto run pauses as RECOVERABLE (the class is kept: "resume when
+    // it clears"); a user who gives up on the prompt pauses as ERROR (a verdict).
+    auth:        cell(pause(REASON.RECOVERABLE), prompt(pause(REASON.ERROR))),
+    quota:       cell(pause(REASON.RECOVERABLE), prompt(pause(REASON.ERROR))),
+    rate_limit:  cell(retry(RECOVERY_MAX_AUTO_ATTEMPTS, pause(REASON.RECOVERABLE)), prompt(pause(REASON.ERROR))),
+    network:     cell(retry(RECOVERY_MAX_AUTO_ATTEMPTS, pause(REASON.RECOVERABLE)), prompt(pause(REASON.ERROR))),
+    '*':         both(pause(REASON.ERROR)),
+  }),
+  // A flow card, the questions loop, _afterExecution, a composite shell mode, an
+  // allocation failure — engine-side throws around an execution.
+  flow: Object.freeze({ '*': both(pause(REASON.ERROR)) }),
+  // The step-boundary budget gate (not an error: a cap was reached).
+  budget: Object.freeze({
+    cost_pipeline: both(pause(REASON.COST_PIPELINE)),
+    cost_total:    both(pause(REASON.COST_TOTAL)),
+  }),
+  // run()'s setup — checkout, graph build, skills gate — failed with the pipeline
+  // row already created. A pause here stamps `setupIncomplete`; resume replays it.
+  setup: Object.freeze({ '*': both(pause(REASON.ERROR)) }),
+  // Before the pipeline row exists (topology, preflight, tool detection) there is
+  // nothing to resume into: a launch error is the only enactable verdict.
+  launch: Object.freeze({ '*': both(error()) }),
+  // Anything that escaped the engine after setup (a scheduler throw, a persist
+  // failure, a bookkeeping bug).
+  shell: Object.freeze({ '*': both(pause(REASON.ERROR)) }),
+  // resume() could not REHYDRATE the paused run — the checkout is gone, run.json
+  // is corrupt, a guardrail set or agent prompt no longer loads. The point on disk
+  // is already the best the run can offer: parking it again would re-persist the
+  // same point (and re-notify the task source) on every attempt, forever. A
+  // structurally unrecoverable resume ends the run.
+  resume: Object.freeze({ '*': both(error()) }),
+});
+
+/** The recovery prompt's options, derived from the row: what Retry does is fixed;
+ *  the give-up option's id is the wire `decision` value and names its verdict. */
+export function promptOptions(giveUp) {
+  const giveUpId = giveUp.outcome === 'pause' ? 'pause' : 'abort';
+  return Object.freeze([
+    Object.freeze({ id: 'retry', label: 'Retry' }),
+    giveUpId === 'pause'
+      ? Object.freeze({ id: 'pause', label: 'Pause the run (nothing is discarded — resume later)' })
+      : Object.freeze({ id: 'abort', label: 'Abort the run' }),
+  ]);
+}
+
+/** The give-up option of a prompt's options (the CLI/UI/chat render its label and
+ *  send its id back as the decision). Falls back to the pause option for a prompt
+ *  payload that predates options. */
+export function giveUpOption(options) {
+  const found = Array.isArray(options) ? options.find((o) => o && o.id !== 'retry') : null;
+  return found || promptOptions({ outcome: 'pause' })[1];
+}
+
+/** A recovery answer's `decision` wire value → the policy answer. 'abort' is the
+ *  pre-policy wire value (older UI tabs, chat /abort) and means give up too. */
+export function answerFromDecision(decision) {
+  return decision === 'retry' ? 'retry' : 'giveup';
+}
+
+/**
+ * Decide what a failure does. Pure.
+ * @param {{site:string, cls?:string|null, auto?:boolean, attempt?:number, answer?:'retry'|'giveup'}} f
+ * @returns {{outcome:'retry'|'prompt'|'pause'|'error', reason?:string, options?:readonly object[]}}
+ */
+export function resolveFailure({ site, cls = null, auto = false, attempt = 1, answer } = {}) {
+  const rows = FAILURE_POLICY[site];
+  if (!rows) throw new Error(`failure-policy: unknown site '${site}'`);
+  const row = (cls != null && rows[cls]) || rows['*'];
+  if (!row) throw new Error(`failure-policy: no row for ${site}/${cls}`);
+  let v = auto ? row.auto : row.interactive;
+  if (v.outcome === 'retry') {
+    v = attempt > v.max ? v.then : { outcome: 'retry' };
+  }
+  if (v.outcome === 'prompt') {
+    if (answer === undefined) return { outcome: 'prompt', options: promptOptions(v.giveUp) };
+    v = answer === 'retry' ? { outcome: 'retry' } : v.giveUp;
+  }
+  return v.outcome === 'pause' ? { outcome: 'pause', reason: v.reason } : { outcome: v.outcome };
+}
+
+// ── terminal-verdict stamp ────────────────────────────────────────────────────
+const TERMINAL = Symbol.for('worca.failure.terminal');
+/** Stamp an error whose verdict is 'error' so enclosing sites enact, not re-decide. */
+export function markTerminal(err) {
+  if (err && typeof err === 'object') { try { err[TERMINAL] = true; } catch { /* frozen */ } }
+  return err;
+}
+export function isTerminal(err) {
+  return !!(err && typeof err === 'object' && err[TERMINAL] === true);
+}
+
+// ── consequences of a pause, keyed on its reason ──────────────────────────────
+// What each surface does with a parked run is a function of the reason code, not
+// of ad hoc string checks. `null` is a manual pause (the user pressed Pause).
+const CONSEQUENCES = Object.freeze({
+  manual:                { reportsToSource: false, stagesResults: false, severity: 'info',    notifyPref: 'paused', exitInteractive: 0, label: null },
+  [REASON.USAGE_LIMIT]:  { reportsToSource: true,  stagesResults: false, severity: 'warning', notifyPref: 'paused', exitInteractive: 0, label: 'session/usage limit reached' },
+  [REASON.RECOVERABLE]:  { reportsToSource: true,  stagesResults: false, severity: 'warning', notifyPref: 'paused', exitInteractive: 0, label: 'recoverable error — resume to retry' },
+  [REASON.COST_PIPELINE]:{ reportsToSource: true,  stagesResults: false, severity: 'warning', notifyPref: 'paused', exitInteractive: 0, label: 'pipeline cost limit reached' },
+  [REASON.COST_TOTAL]:   { reportsToSource: true,  stagesResults: false, severity: 'warning', notifyPref: 'paused', exitInteractive: 0, label: 'total cost limit reached' },
+  [REASON.ERROR]:        { reportsToSource: true,  stagesResults: true,  severity: 'error',   notifyPref: 'error',  exitInteractive: 1, label: 'a step failed' },
+});
+
+/** The consequences row for a pause reason (unknown/legacy free-text reasons read
+ *  as a forced pause with a warning severity — every reasoned pause is forced). */
+export function pauseConsequences(reason) {
+  if (reason == null || reason === '') return CONSEQUENCES.manual;
+  return CONSEQUENCES[reason] || CONSEQUENCES[REASON.USAGE_LIMIT];
+}
+
+/** CLI exit code for a paused run. Under --yes every pause is the run parking
+ *  ITSELF with nobody left to resume: 3, so a wrapper can tell a resumable pause
+ *  from a hard error (1) and a usage error (2). Interactive: 0 when the user asked
+ *  for it or a cap/limit holds the run; 1 when an error forced it. */
+export function pauseExitCode(reason, auto) {
+  return auto ? 3 : pauseConsequences(reason).exitInteractive;
+}
+
+/** Human label for a reason code, or null for a manual pause / unknown code. */
+export function describePauseReason(reason) {
+  return pauseConsequences(reason).label;
+}

package/src/core/graph/scheduler.mjs

@@ -393,6 +393,12 @@ export function createScheduler(opts) {
   async function runComposite(h) {
     const portId = h.entry.expandsPort;
     const expanded = await execute({ ...h.args, composite: 'expand', expandsPort: portId });
+    // A pause raised INSIDE the expansion (the adapter converted a throw) settles the
+    // shell row here, with its expands binding intact. Falling through to
+    // runUnexpanded would strip `expandsPort`/the binding from the very entry the
+    // resume re-invokes, so the node would re-run once as a plain execution and the
+    // decomposition would never be re-read.
+    if (expanded?.paused === true) return { paused: true };
     const phases = Array.isArray(expanded?.phases) ? expanded.phases : [];
     if (!phases.length) return runUnexpanded(h, portId);
 
@@ -444,7 +450,8 @@ export function createScheduler(opts) {
     const tasks = Array.isArray(ph.tasks) ? ph.tasks : [];
     const phaseAbort = new AbortController();
     let firstError = null;
-    await execute({ ...h.args, composite: 'phase', phase: ph.ordinal, phaseStatus: 'running' });
+    const opened = await execute({ ...h.args, composite: 'phase', phase: ph.ordinal, phaseStatus: 'running' });
+    if (opened?.paused === true) return { paused: true };   // the phase bookkeeping paused the run: no slice launches
 
     const results = await Promise.allSettled(tasks.map((task, index) =>
       runSlice(h, portId, ph, task, index, phaseAbort).catch((err) => {

package/src/core/host-guard.mjs

@@ -0,0 +1,271 @@
+// src/core/host-guard.mjs
+// The host-process guard. Every agent worca spawns carries this file as a
+// PreToolUse hook on Bash (see buildSettingsPayload in claude-runner.mjs), so
+// no agent — predefined role, custom agent, plugin agent, or their in-process
+// sub-agents — can kill the worca server that runs it.
+//
+// Born of the 2026-08-31 incident: an implementer cleaning up stray test
+// servers ran `ps aux | grep '[n]ode --disable' | awk '{print $2}' | while
+// read p; do kill $p; done` and took down its own host mid-run (the pattern
+// matches the production server argv exactly).
+//
+// Policy — deny when the command:
+//   - invokes `pkill` or `killall` (pattern kills, unbounded blast radius);
+//   - invokes `kill` with anything but literal numeric PIDs or `%N` jobspecs
+//     (variables, substitutions, piped/xargs input, `-PGID` group targets —
+//     all of these are how a kill reaches processes nobody named);
+//   - names the host PID (WORCA_HOST_PID) as a literal kill target;
+//   - wraps a kill in a nested `sh -c` / `bash -c` payload.
+// Everything else is allowed, so an agent can still stop processes it spawned:
+// look PIDs up first (ps is read-only and always allowed), then kill the
+// literal numbers. Forcing literal PIDs is the point — every literal target
+// passes through the host-PID check.
+//
+// The hook CLI is deliberately fail-open on malformed input: a broken payload
+// must not brick every Bash call of every agent. The DECISION is fail-closed.
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/** ON unless WORCA_HOST_GUARD is "0"/"false" — the one kill-switch for the
+ *  hook, the WORCA_HOST_PID env var, and the system-prompt preamble alike. */
+export function hostGuardEnabled() {
+  const v = process.env.WORCA_HOST_GUARD;
+  return !(v === '0' || String(v ?? '').toLowerCase() === 'false');
+}
+
+/** The PreToolUse hook entry buildSettingsPayload merges into --settings.
+ *  Runs THIS file with the server's own node; JSON.stringify double-quotes
+ *  both paths for the shell. */
+export function hostGuardHookEntry() {
+  // Forward slashes on purpose: JSON.stringify would double every Windows
+  // backslash and the hook shell's unescaping is unverified there, while
+  // CreateProcess and Git Bash both accept forward-slash paths. POSIX node
+  // paths never contain backslashes, so the replace is a no-op off Windows.
+  const q = (s) => JSON.stringify(String(s).replaceAll('\\', '/'));
+  return {
+    matcher: 'Bash',
+    hooks: [{ type: 'command', command: `${q(process.execPath)} ${q(fileURLToPath(import.meta.url))}` }],
+  };
+}
+
+/** The system-prompt preamble every real spawn carries (runReal prepends it). */
+export function hostGuardSystemPrompt(pid) {
+  return [
+    '## Host process protection',
+    `You run under the worca app server (PID ${pid}, \`node ui/server.mjs\`). Never kill it, and never kill any process you did not spawn yourself.`,
+    'Pattern kills are forbidden and a PreToolUse hook blocks them on every OS: `pkill`, `killall`, `xargs kill`, `taskkill /IM`, `Stop-Process -Name`, `wmic process … delete`, and any `kill` fed from a pipe, variable, or substitution (e.g. `ps aux | grep … | while read p; do kill $p; done`).',
+    'To stop a process you started: record its PID when you spawn it (or list PIDs with `ps`, which is always allowed), then run `kill <literal pid>`.',
+  ].join('\n');
+}
+
+/** Command words that may prefix the one we care about. */
+const SKIP_WORDS = new Set([
+  'do', 'then', 'else', 'elif', 'if', 'while', 'until',
+  'exec', 'command', 'builtin', 'nohup', 'time', 'sudo', 'env',
+]);
+
+const NESTED_SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'powershell', 'pwsh', 'cmd']);
+
+/** Any killer, POSIX or Windows, appearing anywhere in a nested-shell payload. */
+const KILLER_WORD_RE = /\b(?:p?kill|killall|taskkill|stop-process|spps|wmic)\b/i;
+
+/** Killers that xargs / find -exec can hand targets to. */
+const KILLER_CMDS = new Set(['kill', 'pkill', 'killall', 'taskkill']);
+const isKillerToken = (t) => KILLER_CMDS.has(basename(t).toLowerCase().replace(/\.exe$/, ''));
+
+/** Replace quoted spans so quoted data ("fix; killall handling") never looks
+ *  like a command, and substitutions so `kill $(…)` / `kill \`…\`` surface as a
+ *  non-literal target instead of vanishing into the segment split; the RAW
+ *  text is still consulted for nested-shell payloads. The `{}` placeholder
+ *  (xargs -I{}, find -exec … {}) becomes a token BEFORE the split eats the
+ *  braces — otherwise `xargs -I{} kill {}` splits into an xargs segment with
+ *  no kill word and a kill segment with no targets, and both pass. */
+function stripQuotes(s) {
+  return s
+    .replace(/'[^']*'/g, ' __q__ ')
+    .replace(/"(?:[^"\\]|\\.)*"/g, ' __q__ ')
+    .replace(/\$\([^()]*\)/g, ' __sub__ ')
+    .replace(/`[^`]*`/g, ' __sub__ ')
+    .replace(/\{\}/g, ' __ph__ ');
+}
+
+const basename = (w) => w.slice(w.lastIndexOf('/') + 1);
+
+/** Leading env assignments and wrapper words stripped off a token list. */
+function commandWord(tokens) {
+  let i = 0;
+  while (i < tokens.length && (SKIP_WORDS.has(tokens[i]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]))) i++;
+  return { cmd: basename(tokens[i] ?? ''), rest: tokens.slice(i + 1) };
+}
+
+/** kill's targets: signal options consumed, redirections ignored. */
+function killTargets(rest) {
+  const targets = [];
+  let sawSignal = false;
+  let afterDashDash = false;
+  for (let i = 0; i < rest.length; i++) {
+    const t = rest[i];
+    if (t.startsWith('#')) break;                                  // trailing comment
+    if (/^\d*(?:>>?|<<?|>&|&>>?)$/.test(t)) { i++; continue; }     // spaced redirect: skip its operand too
+    if (/^\d*[<>]/.test(t) || t.includes('>') || t.includes('<')) continue; // attached redirection
+    if (!afterDashDash && t === '--') { afterDashDash = true; continue; }
+    if (!afterDashDash && t.startsWith('-')) {
+      if (t === '-s' || t === '-n') { i++; sawSignal = true; continue; }   // -s TERM / -n 15
+      if (!sawSignal && /^-(?:\d+|[A-Za-z]+\d*)$/.test(t)) { sawSignal = true; continue; } // first -9/-TERM
+      targets.push(t);                                                     // second dash token = a target
+      continue;
+    }
+    targets.push(t);
+  }
+  return targets;
+}
+
+/**
+ * The pure decision. `null` = allow; a non-empty string = deny, with the reason
+ * the agent will read (hook exit 2 feeds stderr back to the model).
+ * @param {string} command   the Bash tool's command text
+ * @param {number} [hostPid] the protected server PID (WORCA_HOST_PID); pattern
+ *   bans apply even without it
+ * @returns {string|null}
+ */
+export function evaluateKillCommand(command, hostPid) {
+  const raw = String(command ?? '');
+  if (!raw.trim()) return null;
+  const pidNote = Number.isFinite(hostPid)
+    ? ` The worca app server (PID ${hostPid}) runs this agent and must survive.`
+    : ' The worca app server runs this agent and must survive.';
+  const advice = ' To stop a process you spawned: list PIDs first (ps is always allowed), then `kill <literal pid>`.';
+
+  const segments = stripQuotes(raw).split(/(?:\|\||&&|;|\||&|\n|\$\(|`|[(){}])+/);
+  for (const seg of segments) {
+    const tokens = seg.trim().split(/\s+/).filter(Boolean);
+    if (!tokens.length) continue;
+    const { cmd: cmdRaw, rest } = commandWord(tokens);
+    // Windows commands are case-insensitive and may carry .exe (`TASKKILL`,
+    // `taskkill.exe`) — normalize once; POSIX names pass through unchanged.
+    const cmd = cmdRaw.toLowerCase().replace(/\.exe$/, '');
+
+    if (cmd === 'pkill' || cmd === 'killall') {
+      return `host guard: blocked \`${cmd}\` — pattern kills are forbidden.${pidNote}${advice}`;
+    }
+    if (cmd === 'xargs' && rest.some(isKillerToken)) {
+      return `host guard: blocked \`xargs kill\` — kill may only take literal numeric PIDs you name yourself.${pidNote}${advice}`;
+    }
+    // find spawns its -exec/-ok payload itself, so the kill never surfaces as
+    // a command word of its own segment; a killer anywhere in find's arguments
+    // alongside an -exec-family flag is the same unbounded fan-out as xargs.
+    if (cmd === 'find'
+        && rest.some((t) => /^-(?:exec|ok)(?:dir)?$/.test(t))
+        && rest.some(isKillerToken)) {
+      return `host guard: blocked \`find -exec kill\` — kill may only take literal numeric PIDs you name yourself.${pidNote}${advice}`;
+    }
+    // A nested shell is suspicious only when it carries an INLINE payload
+    // (-c / /c / -Command); `bash scripts/kill-dev-server.sh` is a script FILE
+    // and stays allowed (deliberate evasion via files is out of the threat
+    // model). PowerShell is the exception: its bare argument IS an inline
+    // command (`powershell "Stop-Process -Name node"`), so it is always scanned.
+    if (NESTED_SHELLS.has(cmd)
+        && (cmd === 'powershell' || cmd === 'pwsh' || rest.some((t) => /^(?:-c|\/c|-command|--command)$/i.test(t)))
+        && KILLER_WORD_RE.test(raw)) {
+      return `host guard: blocked a kill inside a nested \`${cmd}\` invocation — run the kill directly with literal PIDs so it can be checked.${pidNote}${advice}`;
+    }
+
+    // ── Windows-native killers (reachable from Git Bash on Windows) ──────────
+    if (cmd === 'taskkill') {
+      for (let i = 0; i < rest.length; i++) {
+        const flag = rest[i].toLowerCase().replace(/^[/-]+/, '');
+        if (flag === 'im') {
+          return `host guard: blocked \`taskkill /IM\` — killing by image name is a pattern kill.${pidNote}${advice}`;
+        }
+        if (flag === 'pid') {
+          const target = rest[++i] ?? '';
+          if (!/^\d+$/.test(target)) {
+            return `host guard: blocked \`taskkill /PID ${target}\` — only literal numeric PIDs are allowed.${pidNote}${advice}`;
+          }
+          if (Number.isFinite(hostPid) && Number(target) === hostPid) {
+            return `host guard: blocked taskkill of PID ${hostPid} — that is the worca app server this agent runs under. Kill only processes you spawned yourself.`;
+          }
+        }
+      }
+      continue;
+    }
+    if (cmd === 'stop-process' || cmd === 'spps') {
+      let sawId = false;
+      for (let i = 0; i < rest.length; i++) {
+        const t = rest[i].toLowerCase();
+        if (t === '-name' || t.startsWith('-name:')) {
+          return `host guard: blocked \`Stop-Process -Name\` — killing by process name is a pattern kill.${pidNote}${advice}`;
+        }
+        if (t === '-id' || t.startsWith('-id:')) {
+          sawId = true;
+          const value = t.includes(':') ? t.split(':')[1] : (rest[++i] ?? '');
+          for (const part of value.split(',')) {
+            if (!/^\d+$/.test(part)) {
+              return `host guard: blocked \`Stop-Process -Id ${part}\` — only literal numeric PIDs are allowed.${pidNote}${advice}`;
+            }
+            if (Number.isFinite(hostPid) && Number(part) === hostPid) {
+              return `host guard: blocked Stop-Process of PID ${hostPid} — that is the worca app server this agent runs under. Kill only processes you spawned yourself.`;
+            }
+          }
+        }
+      }
+      if (!sawId) {
+        return `host guard: blocked \`Stop-Process\` with no literal -Id — pipeline-fed or bare Stop-Process is a pattern kill.${pidNote}${advice}`;
+      }
+      continue;
+    }
+    if (cmd === 'wmic') {
+      // Checked against the RAW command: a parenthesized WHERE clause splits
+      // the segment (`where (name="node.exe") delete`), hiding the verb from
+      // this segment's tokens. A kill-verb elsewhere in a compound command can
+      // false-positive here — acceptable, the reason explains itself.
+      if (/\bprocess\b/i.test(raw) && /\b(?:delete|terminate)\b/i.test(raw)) {
+        return `host guard: blocked \`wmic process … delete\` — pattern kills are forbidden.${pidNote}${advice}`;
+      }
+      continue; // read-only wmic queries stay allowed
+    }
+
+    if (cmd !== 'kill') continue;
+
+    for (const t of killTargets(rest)) {
+      if (/^\d+$/.test(t)) {
+        if (Number.isFinite(hostPid) && Number(t) === hostPid) {
+          return `host guard: blocked kill of PID ${hostPid} — that is the worca app server this agent runs under. Kill only processes you spawned yourself.`;
+        }
+        continue;
+      }
+      if (/^%\d+$/.test(t)) continue; // this shell's own job
+      if (t.startsWith('-')) {
+        return `host guard: blocked \`kill ${t}\` — process-group/broadcast kills are forbidden.${pidNote}${advice}`;
+      }
+      return `host guard: blocked \`kill ${t}\` — kill accepts only literal numeric PIDs (no variables, substitutions, or piped input).${pidNote}${advice}`;
+    }
+  }
+  return null;
+}
+
+// ── hook CLI ─────────────────────────────────────────────────────────────────
+// stdin: the PreToolUse payload ({ tool_name, tool_input: { command } }).
+// exit 0 = allow; exit 2 = block, stderr is shown to the agent.
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (d) => { raw += d; });
+  process.stdin.on('end', () => {
+    let command = '';
+    try {
+      const payload = JSON.parse(raw);
+      if (payload?.tool_name !== 'Bash') process.exit(0);
+      command = String(payload?.tool_input?.command ?? '');
+    } catch {
+      process.exit(0); // fail-open: a malformed payload must not brick Bash
+    }
+    const pid = Number(process.env.WORCA_HOST_PID);
+    const reason = evaluateKillCommand(command, Number.isFinite(pid) && pid > 0 ? pid : undefined);
+    if (reason) {
+      process.stderr.write(`${reason}\n`);
+      process.exit(2);
+    }
+    process.exit(0);
+  });
+}

package/src/core/model-env.mjs

@@ -83,6 +83,74 @@ export function prepareModelEnv(modelEnv, sourceEnv = process.env) {
   return { env, dropped };
 }
 
+// ── env flags + masking (shared by claude-runner.mjs, plugin-shim.mjs, ui/server.mjs)
+
+/**
+ * The ONE "is this env flag on" rule for worca's own knobs (WORCA_MOCK,
+ * WORCA_SUBAGENT_HOOKS, WORCA_DEBUG_SPAWN, …): a denylist — anything but unset,
+ * "", "0" and "false" (any case) is on. Several names may be given; the first
+ * one that is set wins (WORCA_MOCK ?? ORCH_MOCK). Lives in this zero-import leaf
+ * so every gate shares it instead of hand-copying the comparison.
+ * @param {...string} names
+ */
+export function envFlag(...names) {
+  let v;
+  for (const n of names) { v = process.env[n]; if (v !== undefined) break; }
+  return !!v && v !== '0' && v.toLowerCase() !== 'false';
+}
+
+/**
+ * Mask a model-env VALUE for an operator-facing display (the Models editor):
+ * six bullets + the last 4 chars when longer than 8, else six bullets. The
+ * `••` prefix is what ui/server.mjs#isMaskedEcho keys on to treat an echoed
+ * value as "keep", so the shape is a contract — change both together. For LOG
+ * lines use describeModelEnvEntry: a per-spawn log must not carry a suffix.
+ */
+export function maskModelEnvValue(v) {
+  const s = String(v ?? '');
+  return s.length > 8 ? `••••••${s.slice(-4)}` : '••••••';
+}
+
+// Keys whose value is routing configuration, not a credential, and therefore
+// SAFE to print in a spawn log: which endpoint / which wire id a spawn used is
+// exactly the diagnostic question, and masking them makes two gateway cards
+// indistinguishable. Everything else (ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY,
+// ANTHROPIC_CUSTOM_HEADERS, plugin {secret} values, …) is treated as a secret.
+const READABLE_MODEL_ENV_KEYS = new Set([
+  'ANTHROPIC_MODEL', 'ANTHROPIC_BASE_URL', 'ANTHROPIC_SMALL_FAST_MODEL',
+]);
+const READABLE_MODEL_ENV_KEY_RES = [/^ANTHROPIC_DEFAULT_[A-Z0-9]+_MODEL$/, /^CLAUDE_CODE_USE_[A-Z0-9]+$/];
+
+/** Whether a model-env key's value may be printed verbatim in a log line. */
+export function isReadableModelEnvKey(key) {
+  return typeof key === 'string'
+    && (READABLE_MODEL_ENV_KEYS.has(key) || READABLE_MODEL_ENV_KEY_RES.some((re) => re.test(key)));
+}
+
+/**
+ * One `KEY=value` fragment for a log line. Readable keys print their value
+ * (a URL with userinfo has the credentials stripped; an unparsable URL is
+ * treated as a secret); every other key prints `<set, N chars>` — presence and
+ * length prove the env reached the spawn without leaking any part of it.
+ */
+export function describeModelEnvEntry(key, value) {
+  const s = String(value ?? '');
+  const secret = `<set, ${s.length} chars>`;
+  if (!isReadableModelEnvKey(key)) return `${key}=${secret}`;
+  if (key === 'ANTHROPIC_BASE_URL') {
+    let u;
+    try { u = new URL(s); } catch { return `${key}=${secret}`; }
+    if (u.username || u.password) { u.username = ''; u.password = ''; }
+    return `${key}=${u.href}`;
+  }
+  return `${key}=${s}`;
+}
+
+/** The sorted, log-safe `KEY=value, …` rendering of a whole model env. */
+export function describeModelEnv(env) {
+  return Object.keys(env || {}).sort().map((k) => describeModelEnvEntry(k, env[k])).join(', ');
+}
+
 // ── per-model cost override (opt-in pricing, config.mjs resolveModelCost) ─────
 // Lives HERE for the same reason the env policy does: BOTH catalog layers must
 // validate it against one rule. settings.mjs owns the user's global catalog and