@worca/app 1.1.1 → 1.2.0-rc.2

package/src/core/db.mjs

@@ -18,7 +18,7 @@
 
 import { createRequire } from 'node:module';
 import { mkdirSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { worcaHome } from './projects.mjs';
 import { maybeMigrateFromFs } from './migrate-fs-to-db.mjs';
 import { SEED_TEMPLATES, NODE_ID_MAP, FB_WIRE_MAP } from './graph/seed-templates.mjs';
@@ -54,7 +54,7 @@ const OPEN_BACKOFF_MS = 15;
 /** Latest schema version. Bump + append a new migration step when the DDL grows.
  *  Exported so migration tests assert "reached the module's current version"
  *  instead of hardcoding the number — a schema bump then touches no test file. */
-export const SCHEMA_VERSION = 25;
+export const SCHEMA_VERSION = 27;
 
 /** Absolute path to the database file: <worcaHome>/worca-cc.db. */
 export function dbPath() {
@@ -103,15 +103,22 @@ function _openConfiguredMigrated() {
 }
 
 /**
- * True when err is a transient SQLite lock/busy that retrying can clear. Prefers the
- * structured errcode (5 = SQLITE_BUSY, 6 = SQLITE_LOCKED) and falls back to the message
- * so a lock is still caught on any node:sqlite build that doesn't populate errcode. A
- * false positive only costs a bounded retry that still re-throws the original error.
+ * True when err is a transient SQLite error that retrying the open can clear. Prefers
+ * the structured errcode — 5 = SQLITE_BUSY, 6 = SQLITE_LOCKED, and primary code 10 =
+ * SQLITE_IOERR (extended codes carry it in the low byte) — and falls back to the
+ * message so a lock is still caught on any node:sqlite build that doesn't populate
+ * errcode. IOERR is here for the first-launch race on Windows: while one process
+ * performs the journal_mode=WAL switch, a competitor opening the same file can get
+ * "disk I/O error" from the -wal/-shm files being created and unlinked under it
+ * (seen on the Windows 11 VM with 12 concurrent openers). A persistent I/O error
+ * still surfaces: the retry is bounded and re-throws the original error. A false
+ * positive only costs that bounded retry.
  */
 function _isBusyError(err) {
   if (err && (err.errcode === 5 || err.errcode === 6)) return true;
+  if (err && Number.isInteger(err.errcode) && (err.errcode & 0xff) === 10) return true;
   const msg = err && err.message ? err.message : String(err);
-  return /locked|busy/i.test(msg);
+  return /locked|busy|disk I\/O error/i.test(msg);
 }
 
 /** Synchronous sleep (node:sqlite is sync; we must block this thread, not yield it). */
@@ -745,6 +752,8 @@ const INCREMENTAL_COLUMNS = {
   workflows:              { domain: 'TEXT', origin: 'TEXT', graph: 'TEXT', archived_at: 'TEXT' },
   config_workflow_nodes:  { ask_questions: 'INTEGER', subagent_model: 'TEXT' },  // v25: sub-agent model policy
   ask_run_links:          { comment_ids: 'TEXT' },        // v22: JSON array of dc_ ids pending at launch
+  ask_attachments:        { kind: "TEXT NOT NULL DEFAULT 'text'",  // v27: text | image | binary (#398)
+                            mime: 'TEXT' },               // v27: sniffed mime; NULL on pre-v27 rows (= text)
 };
 
 /** v23: per-loop-wire cycle budgets, the graph-engine twin of
@@ -1080,6 +1089,77 @@ function applySchemaV25(db) {
   repairSchemaGaps(db, schemaGaps(db));
 }
 
+/** v26 (Fable 5.1 replaces Fable 5 in PREDEFINED_MODELS): a pin left on the
+ *  retired id would render as "(default model)" in every picker — its option is
+ *  gone — and be rejected on the next write (config.mjs `unknown model
+ *  "claude-fable-5"`), while the run itself kept passing the old id to
+ *  `claude --model`. So every stored pin moves to the successor: the
+ *  config_workflow_nodes.model column, the per-role project_config.steps JSON,
+ *  and node defaults inside workflows.graph (nodes[].config.model is the shape
+ *  workflows.mjs validates; a bare nodes[].model is covered too). Ids match
+ *  case-insensitively, as config.mjs compares them. History (pipelines,
+ *  sub_agents.run_model, ask_*) records what actually ran and is left alone.
+ *  A one-word rename is reversible, so unlike V24 it takes no backup. JSON
+ *  that does not parse is left exactly as found — a broken row must not take
+ *  the ladder down. */
+const V26_MODEL_RENAMES = [['claude-fable-5', 'claude-fable-5-1']];
+
+function applySchemaV26(db) {
+  for (const [from, to] of V26_MODEL_RENAMES) renameStoredModelPins(db, from, to);
+}
+
+/** v27 (Ask Worca binary attachments, #398): ask_attachments.kind/mime — plain
+ *  additive columns declared in INCREMENTAL_COLUMNS, applySchemaV25's shape: this
+ *  repairSchemaGaps call is what CREATES them on the ladder path (a DB stamped
+ *  exactly 26), reconcileSchema covers the fast path. Existing rows keep the
+ *  column DEFAULT 'text', which is exactly what every pre-v27 attachment is. */
+function applySchemaV27(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+}
+
+/** Move every stored pin on model id `from` (lower-case) to `to`. Each table
+ *  is guarded like V24's: hand-seeded upgrade fixtures (and a DB from before the
+ *  fs->db import) reach this step without some of them. */
+function renameStoredModelPins(db, from, to) {
+  const hasTable = (t) => hasSqliteTable(db, t);
+  const isFrom = (v) => typeof v === 'string' && v.trim().toLowerCase() === from;
+  const renameIn = (sel) => {
+    if (!sel || typeof sel !== 'object' || !isFrom(sel.model)) return false;
+    sel.model = to;
+    return true;
+  };
+  if (hasTable('config_workflow_nodes')) {
+    db.prepare('UPDATE config_workflow_nodes SET model = ? WHERE lower(trim(model)) = ?').run(to, from);
+  }
+
+  const like = `%${from}%`;   // cheap pre-filter; the JSON walk below decides
+  const setSteps = hasTable('project_config') && db.prepare('UPDATE project_config SET steps = ? WHERE project_key = ?');
+  for (const row of setSteps ? db.prepare('SELECT project_key, steps FROM project_config WHERE steps LIKE ?').all(like) : []) {
+    let steps;
+    try { steps = JSON.parse(row.steps); } catch { continue; }
+    if (!steps || typeof steps !== 'object' || Array.isArray(steps)) continue;
+    let changed = false;
+    for (const sel of Object.values(steps)) changed = renameIn(sel) || changed;
+    if (changed) setSteps.run(JSON.stringify(steps), row.project_key);
+  }
+
+  const hasGraphColumn = () => db.prepare('PRAGMA table_info(workflows)').all().some((c) => c.name === 'graph');
+  const setGraph = hasTable('workflows') && hasGraphColumn()
+    && db.prepare('UPDATE workflows SET graph = ? WHERE id = ?');
+  for (const row of setGraph ? db.prepare('SELECT id, graph FROM workflows WHERE graph LIKE ?').all(like) : []) {
+    let graph;
+    try { graph = JSON.parse(row.graph); } catch { continue; }
+    if (!graph || typeof graph !== 'object' || !Array.isArray(graph.nodes)) continue;
+    let changed = false;
+    for (const node of graph.nodes) {
+      if (!node || typeof node !== 'object') continue;
+      changed = renameIn(node.config) || changed;
+      changed = renameIn(node) || changed;
+    }
+    if (changed) setGraph.run(JSON.stringify(graph), row.id);
+  }
+}
+
 /** Audit channel for V24 (dev convention: one console.warn per decision). */
 const auditV24 = (msg) => console.warn(`[worca] V24: ${msg}`);
 
@@ -1111,7 +1191,8 @@ function usableBackup(bak) {
 }
 
 /**
- * V24 is the ONLY ladder step that rewrites user data, so an existing DB is
+ * V24 is the only ladder step that rewrites user data destructively (V26 renames
+ * one model id, reversibly), so an existing DB is
  * snapshotted BEFORE the transaction opens (`VACUUM INTO` cannot run inside one
  * — measured: "cannot VACUUM from within a transaction"). Skipped for a fresh
  * file (nothing to lose) and for `:memory:` (PRAGMA database_list gives file '').
@@ -1141,7 +1222,7 @@ function backupBeforeV24(db) {
     throw new Error(`worca cannot take the pre-v24 database backup at ${bak}: `
       + `${err && err.message ? err.message : err}. The v2 upgrade rewrites saved `
       + 'pipelines, so it refuses to run without one — free disk space or make '
-      + `${file.replace(/\/[^/]*$/, '')} writable and start worca again.`, { cause: err });
+      + `${dirname(file)} writable and start worca again.`, { cause: err });
   }
 }
 
@@ -1417,6 +1498,8 @@ export function migrate(db) {
     if (current < 23) applySchemaV23(db);            // graph columns + config_workflow_wires
     if (current < 24) applySchemaV24(db, { existing: current >= 1 });  // the v2 break
     if (current < 25) applySchemaV25(db);            // sub-agent model policy + recorded child model
+    if (current < 26) applySchemaV26(db);            // Fable 5 pins -> Fable 5.1 (catalog swap)
+    if (current < 27) applySchemaV27(db);            // ask_attachments.kind/mime (#398)
     db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
     db.exec('COMMIT');
   } catch (err) {

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);
+  });
+}