chainlesschain 0.162.175 → 0.162.176

package/src/lib/secret-store.js

@@ -0,0 +1,159 @@
+/**
+ * Small OS-backed secret store used by plugin options and other user-scoped
+ * credentials.  Secrets never fall back to plaintext JSON:
+ *   - Windows: DPAPI (CurrentUser) encrypted blobs in the user data dir
+ *   - macOS:   Keychain via `security`
+ *   - Linux:   Secret Service via `secret-tool`
+ *
+ * The command runner is injectable so the protocol is deterministic in unit
+ * tests and so callers can route it through ProcessExecutionBroker.
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getElectronUserDataDir } from "./paths.js";
+import { executionBroker } from "./process-execution-broker/index.js";
+
+const DPAPI_SCRIPT = [
+  "$ErrorActionPreference='Stop'",
+  "Add-Type -AssemblyName System.Security",
+  "$raw=[Console]::In.ReadToEnd()",
+  "$b=[Convert]::FromBase64String($raw)",
+  "$p=[Security.Cryptography.ProtectedData]::Protect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser)",
+  "[Console]::Write([Convert]::ToBase64String($p))",
+].join("; ");
+
+const DPAPI_UNPROTECT_SCRIPT = [
+  "$ErrorActionPreference='Stop'",
+  "Add-Type -AssemblyName System.Security",
+  "$raw=[Console]::In.ReadToEnd()",
+  "$b=[Convert]::FromBase64String($raw)",
+  "$p=[Security.Cryptography.ProtectedData]::Unprotect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser)",
+  "[Console]::Write([Convert]::ToBase64String($p))",
+].join("; ");
+
+function defaultRunner(file, args, input = undefined) {
+  const result = executionBroker.spawnSync(file, args, {
+    origin: "secret-store",
+    policy: "allow",
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    windowsHide: true,
+    ...(input !== undefined ? { input } : {}),
+  });
+  if (result.status !== 0) {
+    throw new Error(String(result.stderr || "secret store command failed").trim());
+  }
+  return String(result.stdout || "").trim();
+}
+
+function safeToken(value) {
+  return crypto
+    .createHash("sha256")
+    .update(String(value || ""))
+    .digest("hex")
+    .slice(0, 32);
+}
+
+function chooseBackend(platform = process.platform) {
+  if (platform === "win32") return "dpapi";
+  if (platform === "darwin") return "keychain";
+  if (platform === "linux" || platform === "freebsd") return "secret-service";
+  return "unavailable";
+}
+
+function readJson(file, readFile = fs.readFileSync) {
+  try {
+    const value = JSON.parse(readFile(file, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? value
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeJson(file, value, deps = {}) {
+  const mkdirSync = deps.mkdirSync || fs.mkdirSync;
+  const writeFileSync = deps.writeFileSync || fs.writeFileSync;
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(value, null, 2), { encoding: "utf8", mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch {}
+}
+
+function createDpapiBackend({ file, runner, readFile, writeFile, mkdirSync } = {}) {
+  const storeFile = file || path.join(getElectronUserDataDir(), "plugin-secrets.dpapi.json");
+  const load = () => readJson(storeFile, readFile);
+  const save = (v) => writeJson(storeFile, v, { writeFileSync: writeFile, mkdirSync });
+  return {
+    name: "dpapi",
+    set(key, value) {
+      const payload = Buffer.from(String(value), "utf8").toString("base64");
+      const encoded = runner("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", DPAPI_SCRIPT], payload);
+      const data = load(); data[key] = encoded; save(data);
+    },
+    get(key) {
+      const encoded = load()[key];
+      if (!encoded) return null;
+      const plain = runner("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", DPAPI_UNPROTECT_SCRIPT], encoded);
+      return Buffer.from(plain, "base64").toString("utf8");
+    },
+    delete(key) {
+      const data = load();
+      if (!Object.prototype.hasOwnProperty.call(data, key)) return false;
+      delete data[key]; save(data); return true;
+    },
+  };
+}
+
+function createKeychainBackend({ service, runner } = {}) {
+  const name = service || "com.chainlesschain.plugin";
+  return {
+    name: "keychain",
+    set(key, value) {
+      runner("security", ["add-generic-password", "-a", key, "-s", name, "-w", String(value), "-U"]);
+    },
+    get(key) {
+      try { return runner("security", ["find-generic-password", "-a", key, "-s", name, "-w"]) || null; } catch { return null; }
+    },
+    delete(key) {
+      try { runner("security", ["delete-generic-password", "-a", key, "-s", name]); return true; } catch { return false; }
+    },
+  };
+}
+
+function createSecretServiceBackend({ service, runner } = {}) {
+  const name = service || "chainlesschain-plugin";
+  return {
+    name: "secret-service",
+    set(key, value) {
+      runner("secret-tool", ["store", "--label", `${name}:${key}`, "service", name, "account", key], String(value));
+    },
+    get(key) {
+      try { return runner("secret-tool", ["lookup", "service", name, "account", key]) || null; } catch { return null; }
+    },
+    delete(key) {
+      try { runner("secret-tool", ["clear", "service", name, "account", key]); return true; } catch { return false; }
+    },
+  };
+}
+
+/** Create a fail-closed secret store. `memory` is intended for tests only. */
+export function createSecretStore(options = {}) {
+  const backend = options.backend || chooseBackend(options.platform);
+  const runner = options.runner || defaultRunner;
+  if (backend === "memory") {
+    const values = options.values || new Map();
+    return { name: "memory", set: (k, v) => values.set(k, String(v)), get: (k) => values.get(k) ?? null, delete: (k) => values.delete(k) };
+  }
+  if (backend === "dpapi") return createDpapiBackend({ ...options, runner });
+  if (backend === "keychain") return createKeychainBackend({ ...options, runner });
+  if (backend === "secret-service") return createSecretServiceBackend({ ...options, runner });
+  throw new Error(`No OS secret store available for platform ${options.platform || process.platform}`);
+}
+
+export function secretRef(key) { return { __cc_secret_ref: String(key) }; }
+export function isSecretRef(value) { return Boolean(value && typeof value === "object" && value.__cc_secret_ref); }
+export { chooseBackend };

package/src/lib/service-manager.js

@@ -1,11 +1,26 @@
-import { execSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import logger from "./logger.js";
+import { executionBroker } from "./process-execution-broker/index.js";
+
+export const _deps = {
+  execFileSync: (...args) => executionBroker.execFileSync(...args),
+  spawn: (...args) => executionBroker.spawn(...args),
+};
+
+function syncDocker(command, args, options = {}, origin = "service:docker") {
+  return _deps.execFileSync(command, args, {
+    ...options,
+    origin,
+    policy: "allow",
+    scope: "service",
+    shell: false,
+  });
+}
 
 export function isDockerAvailable() {
   try {
-    execSync("docker --version", { stdio: "ignore" });
+    syncDocker("docker", ["--version"], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -14,11 +29,11 @@ export function isDockerAvailable() {
 
 export function isDockerComposeAvailable() {
   try {
-    execSync("docker compose version", { stdio: "ignore" });
+    syncDocker("docker", ["compose", "version"], { stdio: "ignore" });
     return true;
   } catch {
     try {
-      execSync("docker-compose --version", { stdio: "ignore" });
+      syncDocker("docker-compose", ["--version"], { stdio: "ignore" });
       return true;
     } catch {
       return false;
@@ -26,12 +41,12 @@ export function isDockerComposeAvailable() {
   }
 }
 
-function getComposeCommand() {
+export function getComposeInvocation() {
   try {
-    execSync("docker compose version", { stdio: "ignore" });
-    return "docker compose";
+    syncDocker("docker", ["compose", "version"], { stdio: "ignore" });
+    return { command: "docker", prefixArgs: ["compose"] };
   } catch {
-    return "docker-compose";
+    return { command: "docker-compose", prefixArgs: [] };
   }
 }
 
@@ -54,30 +69,37 @@ export function findComposeFile(searchPaths) {
 }
 
 export function servicesUp(composePath, options = {}) {
-  const cmd = getComposeCommand();
+  const invocation = getComposeInvocation();
   const args = ["-f", composePath, "up", "-d"];
   if (options.services) {
     args.push(...options.services);
   }
-  return runCompose(cmd, args);
+  return runCompose(invocation, args);
 }
 
 export function servicesDown(composePath) {
-  const cmd = getComposeCommand();
-  return runCompose(cmd, ["-f", composePath, "down"]);
+  const invocation = getComposeInvocation();
+  return runCompose(invocation, ["-f", composePath, "down"]);
 }
 
 export function servicesLogs(composePath, options = {}) {
-  const cmd = getComposeCommand();
+  const invocation = getComposeInvocation();
   const args = ["-f", composePath, "logs"];
   if (options.follow) args.push("-f");
   if (options.tail) args.push("--tail", String(options.tail));
   if (options.services) args.push(...options.services);
 
-  const parts = cmd.split(" ");
-  const child = spawn(parts[0], [...parts.slice(1), ...args], {
-    stdio: "inherit",
-  });
+  const child = _deps.spawn(
+    invocation.command,
+    [...invocation.prefixArgs, ...args],
+    {
+      stdio: "inherit",
+      origin: "service:compose-logs",
+      policy: "allow",
+      scope: "service",
+      shell: false,
+    },
+  );
 
   return new Promise((resolve, reject) => {
     child.on("close", (code) => {
@@ -89,17 +111,22 @@ export function servicesLogs(composePath, options = {}) {
 }
 
 export function servicesPull(composePath) {
-  const cmd = getComposeCommand();
-  return runCompose(cmd, ["-f", composePath, "pull"]);
+  const invocation = getComposeInvocation();
+  return runCompose(invocation, ["-f", composePath, "pull"]);
 }
 
 export function getServiceStatus(composePath) {
-  const cmd = getComposeCommand();
+  const invocation = getComposeInvocation();
   try {
-    const output = execSync(`${cmd} -f "${composePath}" ps --format json`, {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "ignore"],
-    });
+    const output = syncDocker(
+      invocation.command,
+      [...invocation.prefixArgs, "-f", composePath, "ps", "--format", "json"],
+      {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "ignore"],
+      },
+      "service:compose-status",
+    );
     try {
       return JSON.parse(`[${output.trim().split("\n").join(",")}]`);
     } catch {
@@ -110,14 +137,22 @@ export function getServiceStatus(composePath) {
   }
 }
 
-function runCompose(cmd, args) {
-  const fullCmd = `${cmd} ${args.map((a) => (a.includes(" ") ? `"${a}"` : a)).join(" ")}`;
-  logger.verbose(`Running: ${fullCmd}`);
+function runCompose(invocation, args) {
+  const fullArgs = [...invocation.prefixArgs, ...args];
+  const display = [invocation.command, ...fullArgs]
+    .map((part) => JSON.stringify(String(part)))
+    .join(" ");
+  logger.verbose(`Running: ${display}`);
   try {
-    execSync(fullCmd, { stdio: "inherit" });
+    syncDocker(
+      invocation.command,
+      fullArgs,
+      { stdio: "inherit" },
+      "service:compose",
+    );
     return true;
   } catch (err) {
-    logger.error(`Command failed: ${fullCmd}`);
+    logger.error(`Command failed: ${display}`);
     throw err;
   }
 }

package/src/lib/settings-hook-events.cjs

@@ -21,6 +21,26 @@ const { runHooks } = require("./hook-runner.cjs");
 const { buildHookEnvelope } = require("./hook-event-bus.cjs");
 const hookEventLog = require("./hook-event-log.cjs");
 
+/**
+ * Publish lifecycle events to Hooks v2 without making the legacy settings hook
+ * path depend on the ESM runtime. Payloads are deliberately reduced before
+ * publication: prompt text and file contents must never become durable hook
+ * context merely because a lifecycle producer fired.
+ */
+function publishHooksV2Event(event, payload = {}) {
+  const safe = { ...payload };
+  delete safe.prompt;
+  delete safe.content;
+  delete safe.files;
+  void import("./hooks-v2-producers.js")
+    .then(({ emitHooksV2Event }) => {
+      emitHooksV2Event(event, safe);
+    })
+    .catch(() => {
+      // Optional producer bridge; legacy settings hooks remain authoritative.
+    });
+}
+
 /**
  * Stamp a unified-bus delivery id (event_id) onto a hook payload (P2 event bus).
  * Additive — a hook that ignores it is unaffected; a hook that reads it gets a
@@ -104,6 +124,10 @@ function runUserPromptSubmitHooks(
   settingsHooks,
   { prompt, cwd, sessionId } = {},
 ) {
+  publishHooksV2Event("UserPromptSubmit", {
+    cwd: cwd || null,
+    session_id: sessionId || null,
+  });
   if (!settingsHooks) return { blocked: false, additionalContext: null };
   const matched = collectHooks(settingsHooks, "UserPromptSubmit", "");
   if (matched.length === 0) return { blocked: false, additionalContext: null };
@@ -159,7 +183,7 @@ function dispatchAsyncHooks(settingsHooks, event, payload = {}, opts = {}) {
   return supervisor.dispatch(
     asyncHooks,
     { hook_event_name: event, cwd: opts.cwd, ...payload },
-    { cwd: opts.cwd },
+    { cwd: opts.cwd, broker: opts.broker },
   );
 }
 
@@ -169,6 +193,11 @@ function dispatchAsyncHooks(settingsHooks, event, payload = {}, opts = {}) {
  * @returns {{ additionalContext:string|null }}
  */
 function runSessionStartHooks(settingsHooks, { source, cwd, sessionId } = {}) {
+  publishHooksV2Event("SessionStart", {
+    source: source || "startup",
+    cwd: cwd || null,
+    session_id: sessionId || null,
+  });
   if (!settingsHooks) return { additionalContext: null };
   const matched = collectHooks(settingsHooks, "SessionStart", source || "");
   if (matched.length === 0) return { additionalContext: null };
@@ -199,6 +228,11 @@ function runCwdChangedHooks(
   settingsHooks,
   { oldCwd, newCwd, cwd, sessionId } = {},
 ) {
+  publishHooksV2Event("CwdChanged", {
+    old_cwd: oldCwd || null,
+    cwd: newCwd || cwd || null,
+    session_id: sessionId || null,
+  });
   if (!settingsHooks) return { additionalContext: null };
   const matched = collectHooks(settingsHooks, "CwdChanged", newCwd || "");
   const { sync } = partitionAsyncHooks(matched);
@@ -234,6 +268,13 @@ function runWorktreeCreateHooks(
   settingsHooks,
   { worktreePath, branch, baseSha, cwd, sessionId } = {},
 ) {
+  publishHooksV2Event("WorktreeCreate", {
+    worktree_path: worktreePath || null,
+    branch: branch || null,
+    base_sha: baseSha || null,
+    cwd: cwd || worktreePath || null,
+    session_id: sessionId || null,
+  });
   if (!settingsHooks) return { additionalContext: null };
   const matched = collectHooks(settingsHooks, "WorktreeCreate", branch || "");
   const { sync } = partitionAsyncHooks(matched);
@@ -271,6 +312,14 @@ function runWorktreeRemoveHooks(
   settingsHooks,
   { worktreePath, branch, removed, reason, cwd, sessionId } = {},
 ) {
+  publishHooksV2Event("WorktreeRemove", {
+    worktree_path: worktreePath || null,
+    branch: branch || null,
+    removed: removed === true,
+    reason: reason || null,
+    cwd: cwd || worktreePath || null,
+    session_id: sessionId || null,
+  });
   if (!settingsHooks) return { additionalContext: null };
   const matched = collectHooks(settingsHooks, "WorktreeRemove", branch || "");
   const { sync } = partitionAsyncHooks(matched);
@@ -312,6 +361,11 @@ function runInstructionsLoadedHooks(
   settingsHooks,
   { files, cwd, sessionId } = {},
 ) {
+  publishHooksV2Event("InstructionsLoaded", {
+    count: Array.isArray(files) ? files.length : 0,
+    cwd: cwd || null,
+    session_id: sessionId || null,
+  });
   if (!settingsHooks) return { additionalContext: null };
   const matched = collectHooks(settingsHooks, "InstructionsLoaded", "");
   const { sync } = partitionAsyncHooks(matched);
@@ -353,6 +407,12 @@ function runObserveHooks(
   payload = {},
   { cwd, matchTarget, traceId, parentId } = {},
 ) {
+  publishHooksV2Event(event, {
+    ...payload,
+    cwd: cwd || payload.cwd || null,
+    trace_id: traceId || payload.trace_id || null,
+    parent_id: parentId || payload.parent_id || null,
+  });
   if (!settingsHooks) return { decision: "continue", results: [] };
   const matched = collectHooks(settingsHooks, event, matchTarget || "");
   const { sync } = partitionAsyncHooks(matched);

package/src/lib/settings-hooks.cjs

@@ -252,6 +252,10 @@ function collectHooks(hooksBlock, event, toolName) {
           event,
           async: h.async === true,
           asyncRewake: h.asyncRewake === true,
+          origin: h.origin || "hook",
+          pluginId: h.pluginId || null,
+          pluginVersion: h.pluginVersion || null,
+          pluginSource: h.pluginSource || null,
         });
     }
   }

package/src/lib/side-effect-ledger.js

@@ -56,6 +56,8 @@ const KIND_IDEMPOTENT = new Map([
   ["network-mutation", false],
   ["payment", false],
   ["file-write", false],
+  ["file-delete", false],
+  ["file-move", false],
   ["file-write-checkpointed", true],
   ["read", true],
   ["compute", true],
@@ -99,6 +101,18 @@ export function classifyToolSideEffect(toolName, args = {}) {
         kind: "file-write",
         key: shortKey(a.path || a.file || a.notebook_path),
       };
+    case "delete_file":
+      return {
+        kind: "file-delete",
+        key: shortKey(a.path || a.file),
+      };
+    case "move_file":
+      return {
+        kind: "file-move",
+        key: shortKey(
+          `${a.path || a.file || ""} -> ${a.target_path || a.targetPath || ""}`,
+        ),
+      };
     case "edit_file_hashed":
       // Hash-guarded: re-applying over an already-changed tree fails safely, so
       // a replay cannot silently double-apply — idempotent-by-construction.
@@ -201,6 +215,14 @@ export class SideEffectLedger {
     ]);
   }
 
+  /** Merge bounded correlation metadata discovered after an effect started. */
+  annotate(opId, metadata = {}) {
+    const rec = this._rec(opId);
+    if (!rec || !metadata || typeof metadata !== "object") return this;
+    rec.meta = { ...rec.meta, ...metadata };
+    return this;
+  }
+
   /** Confirm the effect applied. Only from `started`. */
   commit(opId) {
     return this._advance(

package/src/lib/sub-agent-context.js

@@ -83,6 +83,10 @@ export class SubAgentContext {
     // nested spawns (threaded into the loop options so a nested spawn_sub_agent
     // reads it as ctx.subAgentContract).
     this.subAgentContract = options.subAgentContract || null;
+    // Optional session-level Extension Tier admission policy. Keep it as an
+    // explicit inherited capability so child loops cannot silently bypass the
+    // parent's admission decision.
+    this.toolAdmission = options.toolAdmission || null;
     // Skill capability INTERSECT: null = unrestricted; a list (possibly empty)
     // restricts run_skill/list_skills in this context's loop to those skills.
     this.skillAllowlist =
@@ -335,6 +339,7 @@ export class SubAgentContext {
       subAgentBudget: this.subAgentBudget,
       // This context's effective contract = the ceiling for its nested spawns.
       subAgentContract: this.subAgentContract,
+      toolAdmission: this.toolAdmission,
       // Skill allow-list restricting run_skill/list_skills in this loop.
       skillAllowlist: this.skillAllowlist,
       // Parent trace for hook envelopes (absent → key omitted, no parent_id).

package/src/lib/sub-agent-profiles.js

@@ -30,6 +30,8 @@ const FULL_TOOLS = Object.freeze([
   "write_file",
   "edit_file",
   "edit_file_hashed",
+  "delete_file",
+  "move_file",
   "list_dir",
   "search_files",
   "search_sessions",
@@ -49,6 +51,8 @@ const DESIGN_TOOLS = Object.freeze([
   "write_file",
   "edit_file",
   "edit_file_hashed",
+  "delete_file",
+  "move_file",
   "list_dir",
   "search_files",
   "web_fetch",

package/src/lib/turn-context.js

@@ -11,21 +11,23 @@
  * @module turn-context
  */
 
-import { execSync } from "child_process";
 import path from "path";
+import { executionBroker } from "./process-execution-broker/index.js";
 
-const _deps = { execSync };
+const _deps = {
+  execFileSync: (...args) => executionBroker.execFileSync(...args),
+};
 
 /**
  * Run a git command with stdio pipe and return stdout or null.
- * @param {string} cmd
+ * @param {string[]} args
  * @param {string} cwd
  * @returns {string|null}
  */
-function _git(cmd, cwd) {
+function _git(args, cwd) {
   try {
     return _deps
-      .execSync(`git ${cmd}`, {
+      .execFileSync("git", args, {
         cwd,
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "ignore"],
@@ -33,6 +35,10 @@ function _git(cmd, cwd) {
         // `status --porcelain` on a dirty repo with many files can exceed the
         // 1 MB execSync default → ENOBUFS → null → "(clean)" misreport below.
         maxBuffer: 16 * 1024 * 1024,
+        origin: "context:git",
+        policy: "allow",
+        scope: "context",
+        shell: false,
       })
       .trim();
   } catch (_e) {
@@ -60,10 +66,10 @@ export function buildTurnContext({
   lines.push(`## Turn context (iteration ${iteration})`);
   lines.push(`- cwd: ${path.resolve(cwd)}`);
 
-  const branch = _git("rev-parse --abbrev-ref HEAD", cwd);
+  const branch = _git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
   if (branch) {
-    const head = _git("rev-parse --short HEAD", cwd);
-    const status = _git("status --porcelain", cwd);
+    const head = _git(["rev-parse", "--short", "HEAD"], cwd);
+    const status = _git(["status", "--porcelain"], cwd);
     // Distinguish "command failed" (null — timeout / huge output) from "" (truly
     // clean): the old `status && …` reported a repo as "(clean)" whenever status
     // couldn't be determined, which is a wrong signal to the model.

package/src/lib/unattended-action-policy.js

@@ -121,6 +121,89 @@ export function classifyActionRisk(actionClass) {
   return "conditional"; // push — depends on branch protection
 }
 
+/**
+ * Classify a shell command before it reaches the process broker. This is a
+ * deliberately conservative, token-free classifier: compound commands use
+ * the highest-risk segment and unknown commands remain unknown so an
+ * unattended caller can fail closed.
+ */
+export function classifyShellAction(command) {
+  if (typeof command !== "string" || !command.trim()) return null;
+  const segments = command
+    .split(/&&|\|\||[;\n]|\|/)
+    .map((part) =>
+      part
+        .trim()
+        .replace(/^(?:env\s+)?(?:sudo\s+)?(?:command\s+)?/i, "")
+        .toLowerCase(),
+    )
+    .filter(Boolean);
+  const classifySegment = (segment) => {
+    if (/^git\s+push\b/.test(segment)) return ACTION_CLASS.PUSH;
+    if (/^git\s+(?:merge|rebase|cherry-pick)\b/.test(segment)) {
+      return ACTION_CLASS.MERGE;
+    }
+    if (/^(?:npm|pnpm|yarn|bun)\s+publish\b/.test(segment)) {
+      return ACTION_CLASS.PUBLISH;
+    }
+    if (
+      /^(?:terraform\s+(?:apply|destroy)|pulumi\s+up|kubectl\s+(?:apply|delete|rollout)|helm\s+(?:install|upgrade)|docker\s+push)\b/.test(
+        segment,
+      )
+    ) {
+      return segment.startsWith("docker push")
+        ? ACTION_CLASS.DEPLOY
+        : ACTION_CLASS.INFRA_MUTATION;
+    }
+    if (/\b(?:deploy|rollout)\b/.test(segment)) return ACTION_CLASS.DEPLOY;
+    if (/^(?:git\s+(?:status|diff|log|show|branch)|ls\b|dir\b|pwd\b|cat\b|type\b|rg\b|grep\b|find\b|where\b)/.test(segment)) {
+      return ACTION_CLASS.READ;
+    }
+    if (/^(?:npm|pnpm|yarn|bun)\s+(?:test|run\s+(?:test|lint|build)|install\b)/.test(segment) || /^(?:pytest|vitest|jest|cargo\s+test|go\s+test)\b/.test(segment)) {
+      return ACTION_CLASS.LOCAL_WRITE;
+    }
+    if (/^echo\b/.test(segment) && />/.test(segment)) {
+      return ACTION_CLASS.LOCAL_WRITE;
+    }
+    return null;
+  };
+  const rank = [
+    ACTION_CLASS.READ,
+    ACTION_CLASS.LOCAL_WRITE,
+    ACTION_CLASS.COMMIT,
+    ACTION_CLASS.PUSH,
+    ACTION_CLASS.PUBLISH,
+    ACTION_CLASS.MERGE,
+    ACTION_CLASS.DEPLOY,
+    ACTION_CLASS.INFRA_MUTATION,
+    ACTION_CLASS.EXTERNAL_MESSAGE,
+  ];
+  const classified = segments.map(classifySegment);
+  return classified.reduce((highest, current) => {
+    if (!current) return null;
+    if (!highest) return current;
+    return rank.indexOf(current) > rank.indexOf(highest) ? current : highest;
+  }, null);
+}
+
+/** Apply the unattended policy to a shell command, including protected push targets. */
+export function evaluateUnattendedShellAction(command, params = {}) {
+  const actionClass = classifyShellAction(command);
+  const protectedBranch =
+    params.protectedBranch === true ||
+    /\bgit\s+push\b[^\n]*(?:^|\s)(?:main|master|develop|production)(?:\s|$)/i.test(
+      command || "",
+    );
+  return {
+    actionClass,
+    ...evaluateUnattendedAction({
+    ...params,
+    actionClass,
+    protectedBranch,
+    }),
+  };
+}
+
 /**
  * Decide whether a fired task may perform one action. Fail-closed.
  *