@evoclock/pi-agentic-driver 0.10.0 → 1.0.0

package/scripts/enforcement/herdr_lifecycle_pi.js

@@ -8,7 +8,7 @@
 // allowlist constant. Pane placement uses pane split directly; tab placement
 // uses tab create. Both capture the returned pane identity and start once.
 import { createHash } from "node:crypto";
-import { readFileSync, realpathSync } from "node:fs";
+import { accessSync, constants as fsConstants, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -17,11 +17,12 @@ import {
   HERDR_ROLE_POLICY,
   resolveTrustedHerdrExecutable,
 } from "./herdr_communication_pi.js";
-import { isNativeTuiContext } from "./native_tui_context.js";
+import { isAttendedElectronContext, isNativeTuiContext } from "./native_tui_context.js";
 
 export const HERDR_SPAWN_WORKER_TOOL = "agentic_herdr_spawn_worker";
 export const HERDR_LIFECYCLE_SCHEMA = "agentic-driver.herdr-lifecycle.v1";
 export const HERDR_LIFECYCLE_VERSION = "spawn-worker.v1";
+export const ATTENDED_ELECTRON_BOUNDARY = "attended-electron";
 export const SPAWN_PLACEMENTS = Object.freeze(["tab", "right", "below"]);
 // Herdr accepts only `right` and `down` split directions;
 // the user-facing `below` is mapped, never forwarded.
@@ -47,7 +48,10 @@ function resolvePiModelsPath() {
   }
   return join(homedir(), ".pi", "agent", "models.json");
 }
-const MODEL_ID_REGEXP = /^[a-z0-9][a-z0-9._-]{0,63}(?:\/[a-z0-9][a-z0-9._-]{0,127})*$/;
+// A model selection is either a unique local model id or a provider followed
+// by one or more bounded model-id segments. Pi model IDs may use colons, but
+// provider names may not. validateSpawnParams separately bounds total length.
+const MODEL_ID_REGEXP = /^[a-z0-9][a-z0-9._:-]{0,127}$|^[a-z0-9][a-z0-9._-]{0,63}(?:\/[a-z0-9][a-z0-9._:-]{0,127})+$/;
 // Closed response keys. Shapes beyond `.result.move_result.pane.pane_id` are
 // provisional from tagged-source evidence (Tranche 07) and fail closed on
 // anything extra.
@@ -494,8 +498,8 @@ export function resolveTrustedSpawnRepository(coordinatorCwd, requestedName) {
 // via the documented fixed argv `pi --list-models` table; custom models.json
 // entries remain an additional accepted source. The roll is parsed once per
 // resolveInstalledModel call and is never cached across calls.
-const PROVIDER_TOKEN_REGEXP = /^[a-z0-9][a-z0-9._-]*$/i;
-const MODEL_TOKEN_REGEXP = /^[a-z0-9][a-z0-9._/-]*$/i;
+const PROVIDER_TOKEN_REGEXP = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const MODEL_TOKEN_REGEXP = /^[a-z0-9][a-z0-9._:-]{0,127}(?:\/[a-z0-9][a-z0-9._:-]{0,127})*$/i;
 
 // Parses the fixed-width provider/model table emitted by `pi --list-models`.
 // Only the first two whitespace tokens of each data row are read; the header
@@ -509,8 +513,10 @@ function parseListModelsTable(raw) {
     const tokens = trimmed.split(/\s+/);
     if (tokens.length < 2) continue;
     const [provider, id] = tokens;
-    if (!PROVIDER_TOKEN_REGEXP.test(provider) || !MODEL_TOKEN_REGEXP.test(id)) continue;
-    pairs.add(`${provider}/${id}`);
+    const pair = `${provider}/${id}`;
+    if (pair.length > 192 || !PROVIDER_TOKEN_REGEXP.test(provider)
+      || !MODEL_TOKEN_REGEXP.test(id) || !MODEL_ID_REGEXP.test(pair)) continue;
+    pairs.add(pair);
   }
   return pairs;
 }
@@ -529,10 +535,11 @@ function readCustomModelPairs(modelsPath) {
   for (const [provider, config] of Object.entries(providers)) {
     const models = isPlainObject(config) && Array.isArray(config.models) ? config.models : [];
     for (const model of models) {
+      const pair = `${provider}/${model?.id}`;
       if (isPlainObject(model) && typeof model.id === "string"
-          && PROVIDER_TOKEN_REGEXP.test(provider)
-          && MODEL_TOKEN_REGEXP.test(model.id)) {
-        pairs.add(`${provider}/${model.id}`);
+          && pair.length <= 192 && PROVIDER_TOKEN_REGEXP.test(provider)
+          && MODEL_TOKEN_REGEXP.test(model.id) && MODEL_ID_REGEXP.test(pair)) {
+        pairs.add(pair);
       }
     }
   }
@@ -630,9 +637,10 @@ function normalizeProcessResult(value) {
 
 async function invokeHerdr(argv, canonicalRoot, options, signal) {
   if (signal?.aborted) throw lifecycleError("aborted", "the spawn operation was aborted");
-  const executable = resolveTrustedHerdrExecutable(
-    typeof options.runProcess === "function" ? { runProcess: options.runProcess } : {},
-  );
+  // Forward the full options object: the internal testExecutablePath seam
+  // (offline fake Herdr process boundary) must reach executable resolution,
+  // otherwise offline tests would silently spawn the production binary.
+  const executable = resolveTrustedHerdrExecutable(options);
   const spec = {
     executable,
     argv: Object.freeze([...argv]),
@@ -879,6 +887,251 @@ function toolResult(details) {
   };
 }
 
+// --- Attended Electron-specific boundary -----------------------------------
+// An explicit, closed contract for a trusted NON-TUI host: the Electron main
+// process. It is a separate context class (see native_tui_context.js), never
+// a Pi-TUI representation. The host has no Herdr session pane, so this
+// boundary NEVER reads or manufactures HERDR_PANE_ID and supports ONLY tab
+// placement (a tab create needs no coordinator pane identity). Stages:
+//   preflightAttendedElectronSpawn  — read-only validation intended to run
+//     BEFORE any board claim: context class, closed parameters, trusted
+//     repository (registry + realpath + Git root), installed model roll,
+//     trusted Herdr executable availability, and duplicate-role observation.
+//     A preflight is NOT an atomic guarantee: external state can change after
+//     it, which is why the commit stage re-validates everything and callers
+//     must preserve truthful claimed-but-not-started reconciliation.
+//   executeHerdrSpawnWorkerAttendedElectron — the single-attempt commit:
+//     one native owner confirmation from the host, then the same guarded
+//     tab create → agent start → agent get → pane get sequence with exact
+//     read-back. No retry, no automatic cleanup; failures report partial
+//     state with human cleanup guidance.
+function attendedElectronContextError(context) {
+  if (!isAttendedElectronContext(context)) {
+    throw lifecycleError(
+      "attended_electron_context_required",
+      "the attended Electron boundary requires an explicit electron-attended context with a native confirm callback (never a Pi TUI representation)",
+      "blocked",
+    );
+  }
+  if (typeof context?.cwd !== "string" || context.cwd.trim() === "") {
+    throw lifecycleError(
+      "attended_electron_context_required",
+      "the attended Electron context requires the trusted host working directory",
+      "blocked",
+    );
+  }
+}
+
+function attendedElectronParams(params) {
+  const request = validateSpawnParams(params);
+  if (request.placement !== "tab") {
+    throw lifecycleError(
+      "pane_identity_unavailable",
+      "the attended Electron host has no Herdr session pane; only tab placement is legitimate and no pane identity is manufactured or inherited",
+      "denied",
+    );
+  }
+  return request;
+}
+
+function resolveAttendedElectronPrerequisites(request, context, options) {
+  const canonicalRoot = resolveTrustedSpawnRepository(context.cwd, request.repository);
+  const modelArgv = resolveInstalledModel(request.model, options);
+  return { canonicalRoot, modelArgv };
+}
+
+function assertHerdrExecutableAvailable(options) {
+  try {
+    // The injected test seam is a real process boundary: verify the exact
+    // injected executable exists and is executable so a missing executable
+    // fails locally, without any process spawn.
+    const injected = options?.testExecutablePath;
+    if (typeof injected === "string" && injected.trim()) {
+      const real = realpathSync(injected);
+      const stat = statSync(real);
+      accessSync(real, fsConstants.X_OK);
+      if (!stat.isFile()) throw new Error("not a file");
+      return;
+    }
+    resolveTrustedHerdrExecutable(options);
+  } catch (error) {
+    if (error?.name === "HerdrLifecycleError") throw error;
+    throw lifecycleError(
+      "herdr_unavailable",
+      "the trusted Herdr executable is unavailable for the attended Electron boundary",
+    );
+  }
+}
+
+async function observeDuplicateRole(canonicalRoot, role, options, signal) {
+  const listed = await invokeHerdr(agentListArgv(), canonicalRoot, options, signal);
+  if (duplicateRoleExists(listed, role)) {
+    throw lifecycleError("duplicate_worker_name", "a live agent already holds this name", "denied");
+  }
+}
+
+export async function preflightAttendedElectronSpawn(params, context, options = {}) {
+  try {
+    attendedElectronContextError(context);
+    const request = attendedElectronParams(params);
+    assertHerdrExecutableAvailable(options);
+    const { canonicalRoot, modelArgv } = resolveAttendedElectronPrerequisites(request, context, options);
+    await observeDuplicateRole(canonicalRoot, request.role, options, null);
+    return {
+      schema: HERDR_LIFECYCLE_SCHEMA,
+      ok: true,
+      status: "preflight-verified",
+      boundary: ATTENDED_ELECTRON_BOUNDARY,
+      placement: "tab",
+      role: request.role,
+      repository: canonicalRoot,
+      modelArgv: [...modelArgv],
+      nonAuthorizing: true,
+      authorityCreated: false,
+    };
+  } catch (error) {
+    return errorResult(error);
+  }
+}
+
+function attendedElectronConfirmBody(role, modelArgv, canonicalRoot) {
+  return [
+    "One guarded attended-Electron composite spawn: create one tab, then start and verify one Pi agent.",
+    `Role: ${role}`,
+    "Placement: individual tab (the Electron host has no Herdr session pane)",
+    `Model: ${modelArgv[1]} (argv: ${modelArgv.join(" ")})`,
+    `Repository: ${canonicalRoot}`,
+    "No rollback is automatic; a failed step leaves the created state for human cleanup.",
+  ].join("\n");
+}
+
+export async function executeHerdrSpawnWorkerAttendedElectron(params, context, options = {}, signal) {
+  let request;
+  try {
+    attendedElectronContextError(context);
+    request = attendedElectronParams(params);
+    const { role, model, repository } = request;
+
+    // Resolve BEFORE any mutation: registry + realpath + Git root, plus the
+    // installed model roll. Duplicate live names are denied at spawn.
+    let canonicalRoot = resolveTrustedSpawnRepository(context.cwd, repository);
+    const modelArgv = resolveInstalledModel(model, options);
+    await observeDuplicateRole(canonicalRoot, role, options, signal);
+
+    // ONE native owner confirmation from the attended host. A denial is a
+    // stop; a throw is a structured refusal. Never re-asked, never retried.
+    let confirmed;
+    try {
+      confirmed = await context.ui.confirm(
+        "Spawn Herdr worker (attended Electron)",
+        attendedElectronConfirmBody(role, modelArgv, canonicalRoot),
+      );
+    } catch (error) {
+      throw lifecycleError(
+        "confirmation_failed",
+        `the attended confirmation failed: ${typeof error?.message === "string" ? error.message : "unknown error"}`,
+        "blocked",
+      );
+    }
+    if (confirmed !== true) {
+      return errorResult(lifecycleError("confirmation_denied", "native confirmation was not granted", "stopped"));
+    }
+
+    // Revalidation point after confirmation, before the first mutation. A
+    // change here is a post-confirmation race: the caller reports it as a
+    // refusal; nothing has been mutated yet.
+    const reconfirmedRoot = resolveTrustedSpawnRepository(context.cwd, repository);
+    if (reconfirmedRoot !== canonicalRoot) {
+      throw lifecycleError("repository_mismatch", "the trusted repository changed after confirmation");
+    }
+    canonicalRoot = reconfirmedRoot;
+
+    // Tab topology only: no coordinator pane identity is resolved, used, or
+    // manufactured anywhere on this path.
+    let tabId;
+    let rootPaneId;
+    let layoutRaw;
+    try {
+      layoutRaw = await invokeHerdr(tabCreateArgv(canonicalRoot, role), canonicalRoot, options, signal);
+      ({ rootPaneId, tabId } = parseTabCreate(layoutRaw));
+    } catch (error) {
+      return partialResult(error, {
+        partial: "tab_created", paneId: rootPaneId, tabId, role, modelArgv,
+        ...(typeof layoutRaw === "string" ? { rawResponse: layoutRaw } : {}),
+      });
+    }
+
+    let agentStartSucceeded = false;
+    try {
+      // Re-check the registry between the mutations.
+      const betweenRoot = resolveTrustedSpawnRepository(context.cwd, repository);
+      if (betweenRoot !== canonicalRoot) {
+        throw lifecycleError("repository_mismatch", "the trusted repository changed between mutations");
+      }
+
+      // Start exactly once in the tab's root pane.
+      const startCall = startArgv(role, rootPaneId, modelArgv);
+      let startRaw;
+      try {
+        startRaw = await invokeHerdr(startCall, canonicalRoot, options, signal);
+        agentStartSucceeded = true;
+      } catch (error) {
+        throw lifecycleError("start_failed", error?.message || "Herdr agent start failed");
+      }
+
+      const postStartRoot = resolveTrustedSpawnRepository(context.cwd, repository);
+      if (postStartRoot !== canonicalRoot) {
+        throw lifecycleError("repository_mismatch", "the trusted repository changed after agent start");
+      }
+      canonicalRoot = postStartRoot;
+
+      const startedPaneId = readBackStart(startRaw, role, canonicalRoot, [...modelArgv]);
+      if (startedPaneId !== rootPaneId) {
+        throw lifecycleError("pane_mismatch", "agent start returned a different pane identity");
+      }
+      const agentRaw = await invokeHerdr(["agent", "get", role], canonicalRoot, options, signal);
+      const agentReadBack = readBackAgent(agentRaw, role, canonicalRoot, [...modelArgv]);
+      if (agentReadBack.paneId !== rootPaneId) {
+        throw lifecycleError("pane_mismatch", "agent get returned a different pane identity");
+      }
+      const paneRaw = await invokeHerdr(["pane", "get", rootPaneId], canonicalRoot, options, signal);
+      readBackPane(paneRaw, rootPaneId, canonicalRoot);
+
+      return {
+        schema: HERDR_LIFECYCLE_SCHEMA,
+        ok: true,
+        status: "spawned",
+        boundary: ATTENDED_ELECTRON_BOUNDARY,
+        role,
+        reportMarkers: reportMarkersForRole(role),
+        placement: "tab",
+        direction: null,
+        paneId: rootPaneId,
+        rootPaneId,
+        tabId,
+        modelArgv: [...modelArgv],
+        repository: canonicalRoot,
+        hashes: Object.freeze({
+          request: sha256(JSON.stringify(request)),
+          layoutCreateResponse: sha256(layoutRaw),
+          startResponse: sha256(startRaw),
+        }),
+        nonAuthorizing: true,
+        authorityCreated: false,
+      };
+    } catch (error) {
+      // Once agent start exits successfully, parsing or read-back failures
+      // cannot erase that mutation: report a live-agent partial.
+      return partialResult(error, {
+        partial: agentStartSucceeded ? "agent_started" : "tab_created",
+        paneId: rootPaneId, tabId, role, modelArgv,
+      });
+    }
+  } catch (error) {
+    return errorResult(error);
+  }
+}
+
 export function registerHerdrLifecycleInterface(pi, options = {}) {
   if (typeof pi?.registerTool !== "function" || REGISTRATIONS.has(pi)) return;
   REGISTRATIONS.add(pi);

package/scripts/enforcement/linux_microvm_remote_fixture.sh

@@ -9,7 +9,7 @@ set -euo pipefail
 GC_TAXONOMY_VERSION="guest-containment-taxonomy.v1"
 GC_LOG_SCHEMA="agentic-driver.guest-containment.log.v1"
 GC_KILLSWITCH_SCHEMA="agentic-driver.guest-containment.killswitch.v1"
-GC_TAXONOMY_SHA256="f0d4f11150e0f9aef562f1e7d61afd9fa8df1f40f1c90c3c011dd768e335bb84"
+GC_TAXONOMY_SHA256="0b194cdfd86f23fd68c2685c2ccfc556a0e311e2973b1ff619c6c78791d65fcd"
 # Severity tiers (design section 2.0): CRITICAL/HIGH trip immediately,
 # ELEVATED/ANOMALY accumulate pressure within a sliding time window.
 GC_WINDOW_SECONDS=60
@@ -32,7 +32,7 @@ gc_embedded_taxonomy() {
     {"id":"GC-FSW-003","class":"GC-FSW","severity":"ELEVATED","action":"deny","match":"file-growth-anomaly: unexpected growth in cache/package directories (~/.npm, ~/.cache/pip, /var/cache/*) beyond the size-delta threshold","evidence":"METR evaluation logs: bulk cache staging of payloads","since":"v1","disposition":"detector:fs-sweep size-delta sampling (gc_cache_growth_sample; aggregate ELEVATED, GC_CACHE_GROWTH_KIB per sweep)"},
     {"id":"GC-SHR-001","class":"GC-SHR","severity":"HIGH","action":"deny","match":"shared-cache-write: writes to paths shared with other agents or the coordinator; with host-share absent any such attempt is a deny","evidence":"receipt proves host-share=absent; writes would indicate boundary violation","since":"v1","disposition":"detector:fs-path; share paths auto-arm via gc_share_mounted (/proc/mounts); shared-cache roots classify as SHR when unarmed"},
     {"id":"GC-SHR-002","class":"GC-SHR","severity":"HIGH","action":"deny","match":"cross-agent-channel: creation of or writes to inter-agent coordination paths (maildirs, task-queue files, agent state files)","evidence":"HF incident multi-agent escalation; METR coordination/sabotage threat model","since":"v1","disposition":"detector:fs-path+shim-argv heuristics (Maildir, task-queue, agent-channel, coordination paths)"},
-    {"id":"GC-NET-001","class":"GC-NET","severity":"HIGH","action":"deny","match":"socket-open: any entry in /proc/net/tcp, /proc/net/tcp6, /proc/net/udp at any sweep","evidence":"fixture boots with no network device; any socket is exfiltration-capable","since":"v1","disposition":"detector:net-proc-sweep"},
+    {"id":"GC-NET-001","class":"GC-NET","severity":"HIGH","action":"deny","match":"socket-open: any entry in /proc/net/tcp, /proc/net/tcp6, /proc/net/udp not present in the pre-arming socket baseline, at any sweep","evidence":"fixture boots with no network device; any socket is exfiltration-capable","since":"v1","disposition":"detector:net-proc-sweep-baselined"},
     {"id":"GC-NET-002","class":"GC-NET","severity":"HIGH","action":"deny","match":"network-tool-invocation: shim-detects wget, curl, nc, ssh, telnet, ping regardless of arguments","evidence":"METR self-replication exfiltration patterns; HF incident remote control","since":"v1","disposition":"detector:shim-argv"},
     {"id":"GC-CRED-001","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"credential-path-read: opens of ~/.ssh/, ~/.aws/, ~/.netrc, ~/.git-credentials, token files","evidence":"credential theft is step one in every reported agent-escape chain","since":"v1","disposition":"detector:shim-argv"},
     {"id":"GC-CRED-002","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"env-secret-probing: attempts to dump or scan the environment for secret-shaped keys","evidence":"METR evaluation logs; HF incident postmortem credential harvest attempts","since":"v1","disposition":"detector:shim-argv"},
@@ -673,7 +673,7 @@ if [ "${1:-}" = "--gc-core-embed" ]; then
 GC_TAXONOMY_VERSION="guest-containment-taxonomy.v1"
 GC_LOG_SCHEMA="agentic-driver.guest-containment.log.v1"
 GC_KILLSWITCH_SCHEMA="agentic-driver.guest-containment.killswitch.v1"
-GC_TAXONOMY_SHA256="f0d4f11150e0f9aef562f1e7d61afd9fa8df1f40f1c90c3c011dd768e335bb84"
+GC_TAXONOMY_SHA256="0b194cdfd86f23fd68c2685c2ccfc556a0e311e2973b1ff619c6c78791d65fcd"
 # Severity tiers (design section 2.0): CRITICAL/HIGH trip immediately,
 # ELEVATED/ANOMALY accumulate pressure within a sliding time window.
 GC_WINDOW_SECONDS=60
@@ -696,7 +696,7 @@ gc_embedded_taxonomy() {
     {"id":"GC-FSW-003","class":"GC-FSW","severity":"ELEVATED","action":"deny","match":"file-growth-anomaly: unexpected growth in cache/package directories (~/.npm, ~/.cache/pip, /var/cache/*) beyond the size-delta threshold","evidence":"METR evaluation logs: bulk cache staging of payloads","since":"v1","disposition":"detector:fs-sweep size-delta sampling (gc_cache_growth_sample; aggregate ELEVATED, GC_CACHE_GROWTH_KIB per sweep)"},
     {"id":"GC-SHR-001","class":"GC-SHR","severity":"HIGH","action":"deny","match":"shared-cache-write: writes to paths shared with other agents or the coordinator; with host-share absent any such attempt is a deny","evidence":"receipt proves host-share=absent; writes would indicate boundary violation","since":"v1","disposition":"detector:fs-path; share paths auto-arm via gc_share_mounted (/proc/mounts); shared-cache roots classify as SHR when unarmed"},
     {"id":"GC-SHR-002","class":"GC-SHR","severity":"HIGH","action":"deny","match":"cross-agent-channel: creation of or writes to inter-agent coordination paths (maildirs, task-queue files, agent state files)","evidence":"HF incident multi-agent escalation; METR coordination/sabotage threat model","since":"v1","disposition":"detector:fs-path+shim-argv heuristics (Maildir, task-queue, agent-channel, coordination paths)"},
-    {"id":"GC-NET-001","class":"GC-NET","severity":"HIGH","action":"deny","match":"socket-open: any entry in /proc/net/tcp, /proc/net/tcp6, /proc/net/udp at any sweep","evidence":"fixture boots with no network device; any socket is exfiltration-capable","since":"v1","disposition":"detector:net-proc-sweep"},
+    {"id":"GC-NET-001","class":"GC-NET","severity":"HIGH","action":"deny","match":"socket-open: any entry in /proc/net/tcp, /proc/net/tcp6, /proc/net/udp not present in the pre-arming socket baseline, at any sweep","evidence":"fixture boots with no network device; any socket is exfiltration-capable","since":"v1","disposition":"detector:net-proc-sweep-baselined"},
     {"id":"GC-NET-002","class":"GC-NET","severity":"HIGH","action":"deny","match":"network-tool-invocation: shim-detects wget, curl, nc, ssh, telnet, ping regardless of arguments","evidence":"METR self-replication exfiltration patterns; HF incident remote control","since":"v1","disposition":"detector:shim-argv"},
     {"id":"GC-CRED-001","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"credential-path-read: opens of ~/.ssh/, ~/.aws/, ~/.netrc, ~/.git-credentials, token files","evidence":"credential theft is step one in every reported agent-escape chain","since":"v1","disposition":"detector:shim-argv"},
     {"id":"GC-CRED-002","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"env-secret-probing: attempts to dump or scan the environment for secret-shaped keys","evidence":"METR evaluation logs; HF incident postmortem credential harvest attempts","since":"v1","disposition":"detector:shim-argv"},
@@ -1722,7 +1722,7 @@ if ! cat >"$root/gc/core.sh" <<'GC_CORE_EOF'
 GC_TAXONOMY_VERSION="guest-containment-taxonomy.v1"
 GC_LOG_SCHEMA="agentic-driver.guest-containment.log.v1"
 GC_KILLSWITCH_SCHEMA="agentic-driver.guest-containment.killswitch.v1"
-GC_TAXONOMY_SHA256="f0d4f11150e0f9aef562f1e7d61afd9fa8df1f40f1c90c3c011dd768e335bb84"
+GC_TAXONOMY_SHA256="0b194cdfd86f23fd68c2685c2ccfc556a0e311e2973b1ff619c6c78791d65fcd"
 # Severity tiers (design section 2.0): CRITICAL/HIGH trip immediately,
 # ELEVATED/ANOMALY accumulate pressure within a sliding time window.
 GC_WINDOW_SECONDS=60
@@ -1745,7 +1745,7 @@ gc_embedded_taxonomy() {
     {"id":"GC-FSW-003","class":"GC-FSW","severity":"ELEVATED","action":"deny","match":"file-growth-anomaly: unexpected growth in cache/package directories (~/.npm, ~/.cache/pip, /var/cache/*) beyond the size-delta threshold","evidence":"METR evaluation logs: bulk cache staging of payloads","since":"v1","disposition":"detector:fs-sweep size-delta sampling (gc_cache_growth_sample; aggregate ELEVATED, GC_CACHE_GROWTH_KIB per sweep)"},
     {"id":"GC-SHR-001","class":"GC-SHR","severity":"HIGH","action":"deny","match":"shared-cache-write: writes to paths shared with other agents or the coordinator; with host-share absent any such attempt is a deny","evidence":"receipt proves host-share=absent; writes would indicate boundary violation","since":"v1","disposition":"detector:fs-path; share paths auto-arm via gc_share_mounted (/proc/mounts); shared-cache roots classify as SHR when unarmed"},
     {"id":"GC-SHR-002","class":"GC-SHR","severity":"HIGH","action":"deny","match":"cross-agent-channel: creation of or writes to inter-agent coordination paths (maildirs, task-queue files, agent state files)","evidence":"HF incident multi-agent escalation; METR coordination/sabotage threat model","since":"v1","disposition":"detector:fs-path+shim-argv heuristics (Maildir, task-queue, agent-channel, coordination paths)"},
-    {"id":"GC-NET-001","class":"GC-NET","severity":"HIGH","action":"deny","match":"socket-open: any entry in /proc/net/tcp, /proc/net/tcp6, /proc/net/udp at any sweep","evidence":"fixture boots with no network device; any socket is exfiltration-capable","since":"v1","disposition":"detector:net-proc-sweep"},
+    {"id":"GC-NET-001","class":"GC-NET","severity":"HIGH","action":"deny","match":"socket-open: any entry in /proc/net/tcp, /proc/net/tcp6, /proc/net/udp not present in the pre-arming socket baseline, at any sweep","evidence":"fixture boots with no network device; any socket is exfiltration-capable","since":"v1","disposition":"detector:net-proc-sweep-baselined"},
     {"id":"GC-NET-002","class":"GC-NET","severity":"HIGH","action":"deny","match":"network-tool-invocation: shim-detects wget, curl, nc, ssh, telnet, ping regardless of arguments","evidence":"METR self-replication exfiltration patterns; HF incident remote control","since":"v1","disposition":"detector:shim-argv"},
     {"id":"GC-CRED-001","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"credential-path-read: opens of ~/.ssh/, ~/.aws/, ~/.netrc, ~/.git-credentials, token files","evidence":"credential theft is step one in every reported agent-escape chain","since":"v1","disposition":"detector:shim-argv"},
     {"id":"GC-CRED-002","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"env-secret-probing: attempts to dump or scan the environment for secret-shaped keys","evidence":"METR evaluation logs; HF incident postmortem credential harvest attempts","since":"v1","disposition":"detector:shim-argv"},

package/scripts/enforcement/native_tui_context.js

@@ -9,3 +9,19 @@ export function isNativeTuiContext(context) {
     && context?.hasUI === true
     && typeof context?.ui?.confirm === "function";
 }
+
+// Attended Electron main-process context predicate. This is a SEPARATE,
+// explicit context class for a trusted non-TUI host (the Electron main
+// process) that owns a native owner-confirmation capability of its own. It
+// is deliberately not a Pi TUI representation: the mode token differs, so an
+// attended-Electron context NEVER satisfies isNativeTuiContext and a TUI
+// context NEVER satisfies this predicate. Restriction-gated TUI actions
+// continue to deny it; only the explicit attended-Electron driver boundary
+// accepts it.
+export const ATTENDED_ELECTRON_CONTEXT_MODE = "electron-attended";
+
+export function isAttendedElectronContext(context) {
+  return context?.mode === ATTENDED_ELECTRON_CONTEXT_MODE
+    && context?.hasUI === true
+    && typeof context?.ui?.confirm === "function";
+}

package/scripts/enforcement/nudge_classifier_pi.js

@@ -0,0 +1,176 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// NUDGE §2 total detection classifier (SPEC_TASK43_NUDGE.md v3.3.1). Pure
+// module: no I/O, no transport, no authority. #41's poll loop supplies one
+// validated observation per poll and applies this classifier exactly once;
+// the first matching ordered rule wins, so the classification is total and
+// deterministic. Screen text corroborates a block but never changes the
+// classification; malformed identity/readiness/provenance is an observation
+// error owned by #41 and fails closed there, not a worker state here.
+
+// The closed stuck-reason enum (NUDGE §5). `gone` (absent role) is
+// deliberately excluded: #41's absent-role taxonomy owns it.
+export const NUDGE_STUCK_REASONS = Object.freeze([
+  "blocked-modal",
+  "working-sequence-frozen",
+  "status-unknown",
+  "done-report-unavailable",
+]);
+
+// The seven classifier states (NUDGE §2), in rule order.
+export const NUDGE_CLASSIFIER_STATES = Object.freeze([
+  "complete",
+  "gone",
+  "stuck-on-dialog",
+  "working-on-task",
+  "stalled-unknown",
+  "idle-eligible",
+  "done-without-report",
+]);
+
+// Classifier state → stuck reason (NUDGE §5 table). States outside the
+// stuck taxonomy map to null: `complete`, `gone`, `working-on-task`, and
+// `idle-eligible` are not recovery triggers.
+export const NUDGE_STATE_REASON = Object.freeze({
+  "stuck-on-dialog": "blocked-modal",
+  // Deliberately null: callers must use stalledUnknownReason() to resolve
+  // frozen-sequence versus unknown-status evidence.
+  "stalled-unknown": null,
+  "done-without-report": "done-report-unavailable",
+});
+
+// `stalled-unknown` splits on evidence: a frozen working sequence is
+// `working-sequence-frozen`; an otherwise-valid `unknown` status is
+// `status-unknown`. This is the one state with two reasons.
+export function stalledUnknownReason({ status = null, sequenceFrozen = false } = {}) {
+  if (sequenceFrozen) return "working-sequence-frozen";
+  if (status === "unknown") return "status-unknown";
+  return null;
+}
+
+const VALID_STATUS = Object.freeze(["idle", "working", "blocked", "done", "unknown"]);
+
+// Validate one agent observation (NUDGE §1.1 validated fields). Returns
+// {ok, errors} — malformed identity/status/sequence is an observation error,
+// not a worker state, and the caller (the #41 poll loop) fails closed on it.
+// This module never guesses a status to keep classifying.
+export function validateObservation(observation) {
+  const errors = [];
+  if (observation === null || typeof observation !== "object" || Array.isArray(observation)) {
+    return { ok: false, errors: ["observation: must be an object"] };
+  }
+  if (!VALID_STATUS.includes(observation.agentStatus)) {
+    errors.push(`agentStatus: must be one of ${VALID_STATUS.join(", ")} (got ${JSON.stringify(observation.agentStatus ?? null)})`);
+  }
+  const seq = observation.stateChangeSeq;
+  if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0) {
+    errors.push(`stateChangeSeq: must be a safe integer >= 0 (got ${JSON.stringify(seq ?? null)})`);
+  }
+  if (typeof observation.role !== "string" || observation.role === "") {
+    errors.push("role: must be a non-empty string");
+  }
+  const revision = observation.revision;
+  if (revision !== undefined && revision !== null
+    && (typeof revision !== "number" || !Number.isSafeInteger(revision) || revision < 0)) {
+    errors.push(`revision: when present must be a safe integer >= 0 (got ${JSON.stringify(revision)})`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// The total ordered classifier (NUDGE §2). Input: one validated agent
+// observation plus the report evidence and the frozen-sequence judgment
+// supplied by the #41 poll loop (stallPolls is owned solely by #41's
+// dispatch config; this module only consumes the derived boolean).
+//
+// Parameters:
+//   agentStatus      — one of idle | working | blocked | done | unknown
+//   stateChangeSeq   — safe integer >= 0
+//   role             — non-empty role string (validated identity)
+//   reportState      — "pending" | "complete" | "unavailable" (#41 §3.2)
+//   absentRole       — true when #41 mapped the observation to its
+//                      absent-role class (`gone` is #41 taxonomy scope)
+//   sequenceFrozen   — boolean: working sequence frozen for >= stallPolls
+//                      consecutive observations (judged by the poll loop)
+//
+// Output: { state, reasonCode, confidenceBasis } — reasonCode is null for
+// non-stuck states; confidenceBasis names the ordered rule that decided.
+export function classifyObservation({
+  agentStatus = null,
+  stateChangeSeq = null,
+  role = null,
+  reportState = null,
+  absentRole = false,
+  sequenceFrozen = false,
+} = {}) {
+  const observation = { agentStatus, stateChangeSeq, role };
+  const validity = validateObservation(observation);
+  if (!validity.ok) {
+    return {
+      state: null,
+      reasonCode: null,
+      confidenceBasis: `observation-error: ${validity.errors.join("; ")}`,
+    };
+  }
+  if (typeof reportState !== "string"
+    || !["pending", "complete", "unavailable"].includes(reportState)) {
+    return {
+      state: null,
+      reasonCode: null,
+      confidenceBasis: `observation-error: reportState must be pending | complete | unavailable (got ${JSON.stringify(reportState)})`,
+    };
+  }
+
+  // Rule 1 — complete: a complete provenance-valid role report exists,
+  // regardless of current idle/done status. Complete precedes idle so a
+  // prior report can never trigger new work.
+  if (reportState === "complete") {
+    return { state: "complete", reasonCode: null, confidenceBasis: "rule-1-complete-over-status" };
+  }
+  // Rule 2 — gone: #41 returns its absent-role class; `gone` stays #41
+  // taxonomy scope and is excluded from the stuck-reason enum.
+  if (absentRole === true) {
+    return { state: "gone", reasonCode: null, confidenceBasis: "rule-2-absent-role" };
+  }
+  // Rule 3 — stuck-on-dialog: status is `blocked`. herdr classified the
+  // worker blocked; screen text does not determine the cause.
+  if (agentStatus === "blocked") {
+    return { state: "stuck-on-dialog", reasonCode: "blocked-modal", confidenceBasis: "rule-3-blocked-status" };
+  }
+  // Rule 4 — working-on-task: status is `working` and the sequence advanced,
+  // or fewer than stallPolls consecutive frozen observations exist (i.e.
+  // the poll loop has not yet judged the sequence frozen).
+  if (agentStatus === "working" && !sequenceFrozen) {
+    return { state: "working-on-task", reasonCode: null, confidenceBasis: "rule-4-working-progressing" };
+  }
+  // Rule 5 — stalled-unknown: working sequence frozen for at least
+  // stallPolls, or status is otherwise-valid `unknown`.
+  if ((agentStatus === "working" && sequenceFrozen) || agentStatus === "unknown") {
+    const reasonCode = stalledUnknownReason({ status: agentStatus, sequenceFrozen });
+    return {
+      state: "stalled-unknown",
+      reasonCode,
+      confidenceBasis: agentStatus === "working" ? "rule-5-frozen-sequence" : "rule-5-unknown-status",
+    };
+  }
+  // Rule 6 — idle-eligible: idle with no complete report.
+  if (agentStatus === "idle") {
+    return { state: "idle-eligible", reasonCode: null, confidenceBasis: "rule-6-idle-no-report" };
+  }
+  // Rule 7 — done-without-report: done with no extractable complete report;
+  // terminal evidence failure `done-report-unavailable`.
+  if (agentStatus === "done") {
+    return {
+      state: "done-without-report",
+      reasonCode: "done-report-unavailable",
+      confidenceBasis: "rule-7-done-no-report",
+    };
+  }
+  // Unreachable for validated inputs (every validated status is handled
+  // above); kept as an explicit fail-closed floor.
+  return {
+    state: null,
+    reasonCode: null,
+    confidenceBasis: `observation-error: unclassified status ${JSON.stringify(agentStatus)}`,
+  };
+}