@starci/hfs 4.7.32 → 4.7.34

package/runtime/scripts/api/git/index-lock.mjs

@@ -0,0 +1,78 @@
+// index-lock.mjs — the ONE recovery of a stale `.git/index.lock` in a shared product checkout.
+//
+// Every workflow of a product repo works in one checkout (one shared checkout per product). A git process that
+// dies mid-write (a host terminal wipe, a killed worker) leaves `<gitdir>/index.lock` behind, and from then on
+// every `git add` / `git commit` in that checkout refuses "Unable to create .../index.lock: File exists" - for
+// every workflow at once. One op once settled blocked on
+// a 403 KB lock left over with no git process alive; the worker rightly would not delete a shared lock.
+//
+// indexLock removes such a lock only when all of these hold:
+//   - it is a plain file (never a link), older than allocation.housekeeping.gitIndexLockStaleMs (runtimes.yaml);
+//   - the host process table was read (a failed probe removes nothing), and no git process may be working on
+//     this repository: a git-family process whose command line names this repo (-C, --git-dir, --work-tree) or
+//     names no repository at all (its cwd cannot be read, so it may be this repo's) keeps the lock;
+//   - the lock is the same file (mtime and size) after the probe as before it.
+// The caller reads the process table (`list`) and records a removal (`record`): scripts/machine/lock-recovery.mjs composes
+// both, as a `git-index-lock-removed` Supervisor audit event (machine.sqlite sup_events); every other outcome is returned,
+// never thrown. Callers: the command guard before an op worker's git command runs (scripts/guards/command-guard.mjs,
+// through lock-recovery.mjs preflightIndexLock) and the housekeeping area `gitlocks` (scripts/housekeeping/hk-git-locks.mjs).
+import fs from 'node:fs';
+import path from 'node:path';
+import { gitDirOf, lockStat, processOnRepo } from '../../lib/git-dir.mjs';
+
+// A lock younger than `staleMs` (or one with no usable threshold) is not stale yet.
+const notStale = (ageMs, staleMs) => {
+  const threshold = Number(staleMs);
+  return Number.isNaN(threshold) || threshold <= 0 || ageMs < threshold;
+};
+
+const initialLockState = (repo, staleMs, now) => {
+  const gitDir = gitDirOf(repo);
+  const lock = gitDir ? path.join(gitDir, 'index.lock') : null;
+  const out = { repo: path.resolve(String(repo ?? '')), lock, state: 'absent' };
+  const before = lock ? lockStat(lock) : null;
+  if (!before) return { out, before, result: out };
+  out.ageMs = Math.max(0, now - before.mtimeMs);
+  out.bytes = before.size;
+  if (before.isSymbolicLink() || !before.isFile()) return { out, before, result: { ...out, state: 'not-a-file' } };
+  if (notStale(out.ageMs, staleMs)) return { out, before, result: { ...out, state: 'fresh' } };
+  return { out, before, result: null };
+};
+
+const processHoldersOnRepo = (list, repo) => {
+  let procs = null;
+  try { procs = typeof list === 'function' ? list() : null; } catch { procs = null; }
+  return Array.isArray(procs) ? procs.filter((p) => processOnRepo(p, repo) !== 'other') : null;
+};
+
+const removeVerifiedLock = ({ lock, out, before, apply, record }) => {
+  const after = lockStat(lock);
+  if (!after) return { ...out, state: 'absent' };
+  if (after.mtimeMs !== before.mtimeMs || after.size !== before.size) return { ...out, state: 'changed' };
+  if (!apply) return { ...out, state: 'would-remove' };
+  try { fs.unlinkSync(lock); } catch (error) {
+    if (error?.code !== 'ENOENT') return { ...out, state: 'error', error: `${error?.code ?? 'ERROR'}: ${error?.message ?? error}` };
+  }
+  const removed = { ...out, state: 'removed', mtime: new Date(before.mtimeMs).toISOString() };
+  if (typeof record === 'function') { try { record(removed); } catch { /* the removal stands without its event */ } }
+  return removed;
+};
+
+/**
+ * Recover `repo`'s stale index lock. `staleMs` is the age a lock must pass (allocation.housekeeping.
+ * gitIndexLockStaleMs); `apply` false reports `would-remove` and removes nothing; `list()` is the caller's git-process
+ * probe ([{pid, name, commandLine}] or null; none given: probe-failed, nothing removed); `record(result)` is called once
+ * for a removal.
+ * Returns {repo, lock, state, ageMs?, holders?, error?}; state is one of absent | fresh | not-a-file | probe-failed |
+ * held | changed | would-remove | removed | error.
+ */
+export function indexLock({ repo, staleMs, now = Date.now(), apply = true, list = null, record = null } = {}) {
+  const initial = initialLockState(repo, staleMs, now);
+  if (initial.result) return initial.result;
+  const { out, before } = initial;
+  const { lock } = out;
+  const holders = processHoldersOnRepo(list, out.repo);
+  if (holders === null) return { ...out, state: 'probe-failed' };
+  if (holders.length) return { ...out, state: 'held', holders: holders.map((p) => ({ pid: p.pid, name: p.name, commandLine: String(p.commandLine ?? '').slice(0, 200) })) };
+  return removeVerifiedLock({ lock, out, before, apply, record });
+}

package/runtime/scripts/api/git/is-ancestor.mjs

@@ -0,0 +1,5 @@
+// is-ancestor.mjs — `git merge-base --is-ancestor <a> <b>`: whether commit `a` is in the history of `b`.
+import { gitRunner } from './lib.mjs';
+
+/** True when `a` is an ancestor of (or equal to) `b`; false otherwise, and when a ref does not resolve. git: the caller's runner or null. */
+export const isAncestor = (cwd, a, b, { git = null } = {}) => gitRunner(git)(['merge-base', '--is-ancestor', a, b], { cwd }).ok;

package/runtime/scripts/api/git/log.mjs

@@ -0,0 +1,5 @@
+// log.mjs — `git log <args>`: the commit history in a caller-chosen format.
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git log ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const log = (args = [], options = {}) => runGit(['log', ...args], options);

package/runtime/scripts/api/git/merge-base-query.mjs

@@ -0,0 +1,5 @@
+// merge-base-query.mjs — `git merge-base <args>`: one merge-base query (the best common ancestor, or --is-ancestor's exit status).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git merge-base ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const mergeBaseQuery = (args = [], options = {}) => runGit(['merge-base', ...args], options);

package/runtime/scripts/api/git/merge-tree.mjs

@@ -0,0 +1,5 @@
+// merge-tree.mjs — `git merge-tree <args>`: a merge computed without touching the index or the working tree.
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git merge-tree ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const mergeTree = (args = [], options = {}) => runGit(['merge-tree', ...args], options);

package/runtime/scripts/api/git/rev-list.mjs

@@ -0,0 +1,5 @@
+// rev-list.mjs — `git rev-list <args>`: the commits reachable from one set of refs and not another.
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git rev-list ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const revList = (args = [], options = {}) => runGit(['rev-list', ...args], options);

package/runtime/scripts/api/git/rev-parse.mjs

@@ -0,0 +1,13 @@
+// rev-parse.mjs — the commit-resolution read used by runtime Git consumers.
+import { gitRunner } from './lib.mjs';
+
+/**
+ * Resolve a Git revision to a commit in `cwd`, peeling tags with `^{commit}`.
+ * Returns the trimmed commit ID only when Git succeeds with output; unresolved
+ * or non-commit revisions, failed reads and empty output return null.
+ * `git` may supply a caller-owned runner instead of the native read.
+ */
+export const revParse = (cwd, ref, { git = null } = {}) => {
+  const r = gitRunner(git)(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { cwd });
+  return r.ok && r.stdout ? r.stdout : null;
+};

package/runtime/scripts/api/git/status-query.mjs

@@ -0,0 +1,5 @@
+// status-query.mjs — `git status <args>`: what a checkout changed (--porcelain, untracked-files mode, pathspecs).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git status ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const statusQuery = (args = [], options = {}) => runGit(['status', ...args], options);

package/runtime/scripts/api/git/worktree-list-query.mjs

@@ -0,0 +1,5 @@
+// worktree-list-query.mjs — `git worktree list <args>`: the registered worktrees of a repository (--porcelain for records).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git worktree list ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const worktreeListQuery = (args = [], options = {}) => runGit(['worktree', 'list', ...args], options);

package/runtime/scripts/api/node/spawn-node.mjs

@@ -0,0 +1,6 @@
+// spawn-node.mjs — `node <args>` with this process's node binary, started and not waited for: a long-running runtime
+// process (a server, an engine, a detached helper). Returns the ChildProcess.
+import { nodeStart } from './lib.mjs';
+
+/** Starts `node <args>`; options (cwd, env, stdio, detached) pass through. */
+export const spawnNode = (args, options = {}) => nodeStart(args, options);

package/runtime/scripts/api/npm/dist-tag.mjs

@@ -0,0 +1,8 @@
+// The release owner's npm dist-tag mutation edge; reads remain owned by view.mjs.
+import { npmSpawn } from './lib.mjs';
+
+/** Set one declared tag on an already confirmed package version; report incomplete effects as failure. */
+export function distTag(name, version, tag, { cwd, run = npmSpawn } = {}) {
+  const result = run(['dist-tag', 'add', `${name}@${version}`, tag], { cwd, timeout: 120_000 });
+  return { ok: !result.error && !result.signal && result.status === 0, status: result.status ?? null };
+}

package/runtime/scripts/api/npm/lib.mjs

@@ -0,0 +1,32 @@
+// scripts/api/npm/lib.mjs — the runner of npm and npx: the npm-cli.js / npx-cli.js that ship with this node install, run by
+// that node, or the npm / npx executable beside the node binary (no .cmd shim, no shell, no PATH lookup). Utf8 text, a hidden window. The call
+// files beside it (ci.mjs, pack-dry-run.mjs, run-npm.mjs, run-npx.mjs) each name one use; nothing outside scripts/api/npm
+// imports this runner.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { withTempEnv } from '../../../engine/temp-root.mjs';
+import { withoutTestRunner } from '../../lib/env.mjs';
+
+/** The `<tool>-cli.js` (npm or npx) of this node install (Windows: beside node; elsewhere: <prefix>/lib/node_modules) run by node, else the `<tool>` executable beside the node binary: an absolute spawn target fixed by the node install, never a PATH lookup; null when the node has neither. */
+const bundledCli = (tool = 'npm', platform = process.platform, execPath = process.execPath, exists = fs.existsSync) => {
+  const dir = path.dirname(execPath);
+  const cli = path.join(dir, ...(platform === 'win32' ? [] : ['..', 'lib']), 'node_modules', 'npm', 'bin', `${tool}-cli.js`);
+  if (exists(cli)) return { file: execPath, args: [cli] };
+  const sibling = path.join(dir, tool);
+  return platform !== 'win32' && exists(sibling) ? { file: sibling, args: [] } : null;
+};
+
+const toolSpawn = (tool, args, options) => {
+  // npm runs a package's test script, which is node --test: the child never carries an enclosing spec run's mark (scripts/lib/env.mjs withoutTestRunner).
+  const spawn = withTempEnv({ encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024, ...options, env: withoutTestRunner(options.env ?? process.env) });
+  const run = bundledCli(tool);
+  return run ? spawnSync(run.file, [...run.args, ...args], spawn)
+    : { status: null, stdout: '', stderr: '', signal: null, error: Object.assign(new Error(`${tool} was not found beside this node binary`), { code: 'ENOENT' }) };
+};
+
+/** `npm <args>`; options pass through last (cwd, timeout, env, maxBuffer, stdio). */
+export const npmSpawn = (args, options = {}) => toolSpawn('npm', args, options);
+
+/** `npx <args>`; options pass through last (cwd, timeout, env, maxBuffer, stdio). */
+export const npxSpawn = (args, options = {}) => toolSpawn('npx', args, options);

package/runtime/scripts/api/npm/pack-dry-run.mjs

@@ -0,0 +1,9 @@
+// pack-dry-run.mjs — `npm pack --dry-run --json --ignore-scripts` in a package directory: the file list npm would
+// publish (scripts/gates/canon-digest.mjs packedFiles shapes it).
+import { npmSpawn } from './lib.mjs';
+
+/** {status, stdout, stderr, error} of the dry run. npm runs through the runner's absolute node + npm-cli.js target: no shell, no PATH lookup. */
+export function packDryRun(directory, { spawn = npmSpawn } = {}) {
+  const r = spawn(['pack', '--dry-run', '--json', '--ignore-scripts'], { cwd: directory });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
+}

package/runtime/scripts/api/npm/run-npm.mjs

@@ -0,0 +1,6 @@
+// run-npm.mjs — `npm <args>` waited for: a package script (`run <script>`, `test`) or an install (`ci`, `install`) whose
+// status and output the caller reads. Returns the spawnSync result {status, stdout, stderr, error, signal} (utf8 text).
+import { npmSpawn } from './lib.mjs';
+
+/** Runs `npm <args>`; options (cwd, env, timeout, maxBuffer, stdio) pass through. */
+export const runNpm = (args, options = {}) => npmSpawn(args, options);

package/runtime/scripts/api/npm/view.mjs

@@ -0,0 +1,30 @@
+// view.mjs - `npm view`: what the npm registry says about one package version. The release gate reads it to know whether a
+// version is published and which integrity the registry holds; it never writes.
+import { npmSpawn } from './lib.mjs';
+
+/** The JSON `npm view <spec> <field> --json` printed, or null when it printed none. */
+const parsed = (text) => { try { return JSON.parse(String(text ?? '').trim() || 'null'); } catch { return null; } };
+
+/**
+ * {state: 'present' | 'absent' | 'unreachable', integrity?, latest?, versions?, distTags?, detail?} of `name@version`. A package the registry does not
+ * know (E404) or a version it does not list is `absent` (with the registry's latest when it has one); any other failure
+ * (network, auth, a broken npm) is `unreachable`, never a guess. `run` is the spawn seam of a spec.
+ */
+export function view(name, version, { cwd, run = npmSpawn } = {}) {
+  const listed = run(['view', name, 'versions', 'dist-tags', '--json'], { cwd, timeout: 120_000 });
+  const err = `${listed.stderr ?? ''}${listed.error?.message ?? ''}`;
+  if (listed.error || listed.signal || listed.status === null) return { state: 'unreachable', detail: err.trim().slice(0, 200) || 'npm did not run' };
+  if (listed.status !== 0) {
+    return /\bE404\b|404 Not Found|code E404/.test(err) ? { state: 'absent', latest: '-', versions: [], distTags: {} } : { state: 'unreachable', detail: err.trim().split(/\r?\n/)[0].slice(0, 200) };
+  }
+  const doc = parsed(listed.stdout);
+  const versions = [doc?.versions].flat();
+  const distTags = doc?.['dist-tags'];
+  if (!versions.length || versions.some((entry) => typeof entry !== 'string') || !distTags || Array.isArray(distTags) || typeof distTags !== 'object' || Object.values(distTags).some((entry) => typeof entry !== 'string'))
+    return { state: 'unreachable', detail: 'the registry returned an unreadable version or dist-tag inventory' };
+  const inventory = { versions, distTags, latest: distTags.latest ?? '-' };
+  if (!versions.includes(version)) return { state: 'absent', ...inventory };
+  const dist = run(['view', `${name}@${version}`, 'dist.integrity', '--json'], { cwd, timeout: 120_000 });
+  const integrity = !dist.error && !dist.signal && dist.status === 0 ? parsed(dist.stdout) : null;
+  return typeof integrity === 'string' ? { state: 'present', integrity, ...inventory } : { state: 'unreachable', detail: 'the registry lists the version but gave no integrity' };
+}

package/runtime/scripts/api/npm/whoami.mjs

@@ -0,0 +1,8 @@
+// whoami.mjs - `npm whoami`: the npm account logged in on this host (release-publish.mjs refuses a publish from another one).
+import { npmSpawn } from './lib.mjs';
+
+/** The npm account logged in on this host, or null. `run` is the spawn seam of a spec. */
+export function whoami({ cwd, run = npmSpawn } = {}) {
+  const r = run(['whoami'], { cwd, timeout: 60_000 });
+  return !r.error && !r.signal && r.status === 0 ? String(r.stdout ?? '').trim() || null : null;
+}

package/runtime/scripts/api/process/hide-child-windows.mjs

@@ -0,0 +1,31 @@
+// hide-child-windows.mjs — the child-process defaults for background Windows entry points.
+import cp from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { withWindowsHide } from './lib.mjs';
+
+const MARK = Symbol.for('starci.hideChildWindows');
+
+/**
+ * Install process-wide hidden-window defaults for Windows child-process calls.
+ * Explicit `windowsHide` options survive, and builtin ESM exports are synced
+ * so their named imports use the wrappers. Importing this module installs the
+ * patch; detached entry points load it before spawning to avoid visible consoles.
+ * Returns true on the first Windows installation, false elsewhere or once patched.
+ */
+export function hideChildWindows({ platform = process.platform } = {}) {
+  if (platform !== 'win32' || cp[MARK]) return false;
+  for (const [name, hasArgv] of [['spawn', true], ['spawnSync', true], ['execFile', true], ['execFileSync', true], ['exec', false], ['execSync', false]]) {
+    const original = cp[name];
+    const wrapped = function (...list) { return original.apply(this, withWindowsHide(list, hasArgv)); };
+    for (const key of Reflect.ownKeys(original)) {
+      if (key === 'length' || key === 'name' || key === 'prototype') continue;
+      try { Object.defineProperty(wrapped, key, Object.getOwnPropertyDescriptor(original, key)); } catch { /* non-configurable */ }
+    }
+    cp[name] = wrapped;
+  }
+  cp[MARK] = true;
+  syncBuiltinESMExports();
+  return true;
+}
+
+hideChildWindows();

package/runtime/scripts/api/process/kill-tree.mjs

@@ -0,0 +1,22 @@
+// kill-tree.mjs — the host API for a forced Windows process-tree stop.
+import { spawnSync } from 'node:child_process';
+
+const KILL_TREE_COMMAND = 'taskkill.exe';
+const killTreeArgs = (pid) => ['/F', '/T', '/PID', String(pid)];
+
+/**
+ * Force-stop a caller-owned PID and its descendants with Windows taskkill.
+ * The caller proves ownership and validates the PID; this API checks neither.
+ * Non-Windows calls stop nothing and return `{ok:false,status:null,output}`.
+ * Returns `{ok,status,output}` with bounded diagnostic text; spawn failures become
+ * failure results. `ok` reflects taskkill's exit status without rechecking liveness.
+ */
+export function killTree(pid, { timeoutMs = 60_000, run = spawnSync, platform = process.platform } = {}) {
+  if (platform !== 'win32') return { ok: false, status: null, output: 'not windows' };
+  try {
+    const r = run(KILL_TREE_COMMAND, killTreeArgs(pid), { encoding: 'utf8', windowsHide: true, timeout: timeoutMs });
+    return { ok: r?.status === 0, status: r?.status ?? null, output: String(r?.stdout || r?.stderr || r?.error?.message || '').trim().slice(0, 300) };
+  } catch (error) {
+    return { ok: false, status: null, output: String(error?.message ?? error).slice(0, 300) };
+  }
+}

package/runtime/scripts/api/process/lib.mjs

@@ -0,0 +1,125 @@
+// scripts/api/process/lib.mjs — what the process call files beside it share: the spawn options every child of the
+// runtime carries. The call files (process-list.mjs, kill-tree.mjs, run-shell.mjs, spawn-detached.mjs, set-priority.mjs,
+// hide-child-windows.mjs, ...) each name one use of the host's process table or a child process.
+
+/**
+ * `list` with windowsHide: true added to its options argument. `hasArgv`:
+ * the call's second argument may be an argv array (spawn, execFile) rather
+ * than options (exec). An explicit windowsHide (true or false) is kept.
+ */
+export function withWindowsHide(list, hasArgv) {
+  const out = [...list];
+  let slot = 1;
+  if (hasArgv && (Array.isArray(out[1]) || (out[1] == null && out.length > 2))) slot = 2;
+  const options = out[slot];
+  if (options == null) out.splice(slot, out.length > slot ? 1 : 0, { windowsHide: true });
+  else if (typeof options === 'function') out.splice(slot, 0, { windowsHide: true });
+  else if (typeof options === 'object' && !('windowsHide' in options)) out[slot] = { ...options, windowsHide: true };
+  return out;
+}
+
+// ---- the host process table (process-list.mjs, process-list-async.mjs) ------------------------------------------
+
+const psQuote = (s) => String(s).replaceAll("'", "''");
+
+/** The PowerShell script of one process-table read: Win32_Process rows (optionally filtered), with CPU when asked. */
+export function processListScript({ where = null, cmdMax = 4000, cpu = false } = {}) {
+  const filter = where ? ` -Filter '${psQuote(where)}'` : '';
+  return [
+    ...(cpu ? ['$perf = @{}', 'Get-CimInstance Win32_PerfFormattedData_PerfProc_Process | ForEach-Object { if ($_.IDProcess -gt 0) { $perf[[int]$_.IDProcess] = [double]$_.PercentProcessorTime } }'] : []),
+    `Get-CimInstance Win32_Process${filter} | ForEach-Object { $c = [string]$_.CommandLine; [pscustomobject]@{ pid = [int]$_.ProcessId; ppid = [int]$_.ParentProcessId; name = [string]$_.Name; exe = [string]$_.ExecutablePath;`,
+    `  cmd = $c.Substring(0, [Math]::Min(${Number(cmdMax) || 4000}, $c.Length)); ws = [int64]$_.WorkingSetSize;`,
+    `  created = $(if ($_.CreationDate) { ([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds() } else { 0 })${cpu ? '; cpu = $perf[[int]$_.ProcessId]' : ''} } } | ConvertTo-Json -Compress`,
+  ].join('\n');
+}
+
+/** The rows of the PowerShell read's JSON (one object or an array). */
+export const processRowsOfJson = (text) => {
+  const t = String(text ?? '').trim();
+  const v = t ? JSON.parse(t) : [];
+  return (Array.isArray(v) ? v : [v]).map((p) => ({ ...p, pid: Number(p.pid), ppid: Number(p.ppid), cmd: String(p.cmd ?? '') }));
+};
+
+/** The rows of `ps -eo pid=,ppid=,comm=,args=` (exe/created/ws are null there). */
+const PS_ROW_PARTS = [String.raw`^\s*`, String.raw`(\d+)`, String.raw`\s+`, String.raw`(\d+)`, String.raw`\s+`, String.raw`(\S+)`, String.raw`\s+`, '(.*)', '$'];
+const PS_ROW = new RegExp(PS_ROW_PARTS.join(''));
+export const processRowsOfPs = (text, cmdMax = 4000) => String(text ?? '').split(/\r?\n/).map((line) => PS_ROW.exec(line)).filter(Boolean)
+  .map((m) => ({ pid: Number(m[1]), ppid: Number(m[2]), name: m[3].split('/').pop(), exe: null, cmd: m[4].slice(0, cmdMax), created: null, ws: null }));
+
+// ---- the environment of other processes (process-env.mjs) -------------------------------------------------------
+
+// Windows keeps a process's environment block in its PEB: PEB.ProcessParameters (+0x20) -> Environment (+0x80) and
+// EnvironmentSize (+0x3F0), x64 only. A same-user process opens with PROCESS_QUERY_INFORMATION | PROCESS_VM_READ (0x0410).
+export const PROCESS_ENV_NATIVE = String.raw`
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Text;
+public static class StarciProcessEnv {
+  [StructLayout(LayoutKind.Sequential)] struct PBI { public IntPtr Reserved1; public IntPtr PebBaseAddress; public IntPtr Reserved2a; public IntPtr Reserved2b; public IntPtr UniqueProcessId; public IntPtr Reserved3; }
+  [DllImport("ntdll.dll")] static extern int NtQueryInformationProcess(IntPtr h, int cls, ref PBI pbi, int len, out int ret);
+  [DllImport("kernel32.dll")] static extern bool ReadProcessMemory(IntPtr h, IntPtr addr, byte[] buf, IntPtr size, out IntPtr read);
+  [DllImport("kernel32.dll")] static extern IntPtr OpenProcess(int access, bool inherit, int pid);
+  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr h);
+  [DllImport("kernel32.dll")] static extern bool IsWow64Process(IntPtr h, out bool wow);
+  static byte[] Read(IntPtr h, IntPtr addr, int size) {
+    var buf = new byte[size]; IntPtr n;
+    if (!ReadProcessMemory(h, addr, buf, (IntPtr)size, out n) || (int)n != size) return null;
+    return buf;
+  }
+  public static Dictionary<string, string> Env(int pid) {
+    var h = OpenProcess(0x0410, false, pid);
+    if (h == IntPtr.Zero) return null;
+    try { return EnvHandle(h); } finally { CloseHandle(h); }
+  }
+  public static Dictionary<string, string> EnvHandle(IntPtr h) {
+      bool wow; if (IsWow64Process(h, out wow) && wow) return null;
+      var pbi = new PBI(); int ret;
+      if (NtQueryInformationProcess(h, 0, ref pbi, Marshal.SizeOf(pbi), out ret) != 0) return null;
+      var peb = Read(h, pbi.PebBaseAddress + 0x20, 8); if (peb == null) return null;
+      var parameters = (IntPtr)BitConverter.ToInt64(peb, 0);
+      var envPtr = Read(h, parameters + 0x80, 8); if (envPtr == null) return null;
+      var sizeBuf = Read(h, parameters + 0x3F0, 8); if (sizeBuf == null) return null;
+      long size = BitConverter.ToInt64(sizeBuf, 0);
+      if (size <= 0 || size > 4 * 1024 * 1024) return null;
+      var block = Read(h, (IntPtr)BitConverter.ToInt64(envPtr, 0), (int)size); if (block == null) return null;
+      var d = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+      foreach (var entry in Encoding.Unicode.GetString(block).Split('\0')) {
+        if (entry.Length == 0) continue;
+        int i = entry.IndexOf('=', 1); if (i < 0) continue;
+        d[entry.Substring(0, i)] = entry.Substring(i + 1);
+      }
+      return d;
+  }
+}`;
+
+/** The PowerShell script reading `names` from the environment of `pids` (every process when null): JSON [{pid, readable, values}]. */
+export function processEnvScript({ names, pids = null }) {
+  const wanted = JSON.stringify([...names].map(String));
+  const ids = pids ? `@(${[...pids].map(Number).filter(Number.isInteger).join(',')})` : '(Get-Process).Id';
+  return [
+    `Add-Type -TypeDefinition @'${PROCESS_ENV_NATIVE}\n'@ -Language CSharp`,
+    `$names = '${psQuote(wanted)}' | ConvertFrom-Json`,
+    `$rows = foreach ($id in ${ids}) { $e = [StarciProcessEnv]::Env([int]$id); $v = [ordered]@{}; foreach ($n in $names) { $v[$n] = if ($null -ne $e -and $e.ContainsKey($n)) { $e[$n] } else { $null } }; [pscustomobject]@{ pid = [int]$id; readable = ($null -ne $e); values = $v } }`,
+    '@($rows) | ConvertTo-Json -Compress -Depth 4',
+  ].join('\n');
+}
+
+/** The rows of that script's JSON. */
+export const processEnvRowsOfJson = (text) => {
+  const t = String(text ?? '').trim();
+  const v = t ? JSON.parse(t) : [];
+  return (Array.isArray(v) ? v : [v]).map((r) => ({ pid: Number(r.pid), readable: r.readable === true, values: r.values ?? {} }));
+};
+
+/** The spawnSync-shaped result of a system tool the host does not carry (status null + error), for a caller that returns a spawn result. `refusal`: a systemTool refusal. */
+export const toolUnavailableResult = (refusal) => ({ status: null, stdout: '', stderr: '', error: Object.assign(new Error(`${refusal.tool} is not in its fixed system location on ${refusal.platform}`), { code: refusal.code }) });
+
+/** Promise<string | null>: stdout of one system tool run without blocking the calling thread (hidden window, 1 MiB), or null when the tool is absent, failed or timed out. `tool`: systemTool; `exec`: execFile. */
+export const execSystemTool = (name, args, timeout, { exec, tool }) => new Promise((resolve) => {
+  try {
+    const found = tool(name);
+    if (!found.ok) { resolve(null); return; }
+    exec(found.path, args, { timeout, windowsHide: true, maxBuffer: 1 << 20 }, (error, stdout) => resolve(error ? null : String(stdout)));
+  } catch { resolve(null); }
+});

package/runtime/scripts/api/process/probe-guard-command.mjs

@@ -0,0 +1,74 @@
+// probe-guard-command.mjs — run a registered guard hook command the way an agent host runs it, and say whether it resolves.
+//
+// The host runs a hook command through a shell and treats a failure to start it as non-blocking, so an unresolvable
+// guard command leaves every guarded command unguarded without any error the seat acts on. The probe runs the exact
+// command text, with the empty request `{}` the guard allows, once through each shell the host family uses: bash (Git Bash
+// on Windows, the shell Claude Code runs hooks in) and cmd on Windows, sh on POSIX. The environment is the caller's without
+// the seat identity and without the per-user launcher directory on PATH, so only the command's own spelling can resolve.
+// A shell the machine does not carry is skipped with its reason; the probe is ok when every shell that ran exited 0.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readEnv } from '../../lib/env.mjs';
+import { withoutSeatEnv } from '../../lib/seat-env.mjs';
+import { resolveRealTool } from './resolve-real-tool.mjs';
+import { runProgram } from './run-program.mjs';
+import { systemTool } from './system-tool.mjs';
+
+const PROBE_REQUEST = '{}';
+const PROBE_TIMEOUT_MS = 30_000;
+const DETAIL_CHARS = 200;
+
+/** `env` without the per-user launcher directory on its PATH entry. */
+function withoutLauncherDir(env, { home, platform }) {
+  const key = Object.keys(env).find((name) => name.toLowerCase() === 'path');
+  if (!key) return env;
+  const comparable = (entry) => (platform === 'win32' ? path.resolve(entry).toLowerCase() : path.resolve(entry));
+  const launcher = comparable(path.join(home, '.starci', 'bin'));
+  const kept = String(env[key]).split(platform === 'win32' ? ';' : ':').filter((entry) => entry && comparable(entry.replace(/^"(.*)"$/, '$1')) !== launcher);
+  return { ...env, [key]: kept.join(platform === 'win32' ? ';' : ':') };
+}
+
+/** The Git Bash a Windows seat runs hooks in: Claude Code's own override, else the `bin/bash.exe` of the Git installation `git` resolves to; null when none. */
+function gitBashOf({ env, home, platform, exists }) {
+  const named = readEnv('CLAUDE_CODE_GIT_BASH_PATH', env);
+  if (named) return exists(named) ? named : null;
+  const git = resolveRealTool('git', { env, home, platform });
+  if (!git) return null;
+  const root = path.dirname(path.dirname(git));
+  return [root, path.dirname(root)].map((dir) => path.join(dir, 'bin', 'bash.exe')).find((file) => exists(file)) ?? null;
+}
+
+/** The shells this host family runs hooks in: [{shell, file (null when absent), argv(command), verbatim}]. */
+function shellsOf({ env, home, platform, exists }) {
+  const toolPath = (name) => { const found = systemTool(name, { platform, env, exists }); return found.ok ? found.path : null; };
+  if (platform !== 'win32') return [{ shell: 'sh', file: toolPath('sh'), argv: (command) => ['-c', command], verbatim: false }];
+  return [
+    { shell: 'cmd', file: toolPath('cmd'), argv: (command) => ['/d', '/s', '/c', `"${command}"`], verbatim: true },
+    { shell: 'bash', file: gitBashOf({ env, home, platform, exists }), argv: (command) => ['-c', command], verbatim: false },
+  ];
+}
+
+const detailOf = (result) => {
+  const text = String(result.stderr || result.stdout || result.error?.message || '').trim().replace(/\s+/g, ' ');
+  return text.slice(0, DETAIL_CHARS);
+};
+
+/**
+ * Run `command` through every shell of the platform. Returns {ok, reason, shells: [{shell, ok, skipped?, status?, detail?}]};
+ * `reason` is null when ok, else one line naming each failing shell with its exit status and output.
+ * Seams: `exists` (file probe), `run` (the spawn).
+ */
+export function probeGuardCommand({ command, home = os.homedir(), platform = process.platform, env = process.env, exists = fs.existsSync, run = runProgram } = {}) {
+  const probeEnv = withoutLauncherDir(withoutSeatEnv(env), { home, platform });
+  const shells = shellsOf({ env, home, platform, exists }).map((spec) => {
+    if (!spec.file) return { shell: spec.shell, ok: true, skipped: `${spec.shell} is not installed on this machine` };
+    const result = run(spec.file, spec.argv(command), { input: PROBE_REQUEST, env: probeEnv, timeout: PROBE_TIMEOUT_MS, ...(spec.verbatim ? { windowsVerbatimArguments: true } : {}) });
+    return { shell: spec.shell, ok: result.status === 0, status: result.status, detail: detailOf(result) };
+  });
+  const ran = shells.filter((entry) => !entry.skipped);
+  const failed = ran.filter((entry) => !entry.ok);
+  const ok = ran.length > 0 && failed.length === 0;
+  const reason = ok ? null : (failed.map((entry) => `${entry.shell} exit ${entry.status}: ${entry.detail}`).join('; ') || 'no shell on this machine can run the guard command');
+  return { ok, reason, shells };
+}

package/runtime/scripts/api/process/process-list.mjs

@@ -0,0 +1,28 @@
+// process-list.mjs — the synchronous host process-table read.
+import { spawnSync } from 'node:child_process';
+import { processListScript, processRowsOfJson, processRowsOfPs } from './lib.mjs';
+
+/**
+ * Synchronously read the host process table for caller-owned filtering.
+ * `where` is a Windows WQL filter; `cpu` requests Windows per-core CPU values.
+ * Other platforms use ps, with `exe`, `created` and `ws` left null. `cmdMax`
+ * truncates command lines before the optional `match` RegExp filters rows.
+ * Returns process rows, including an empty list, or null on query or parsing
+ * failure. A caller must treat null as an unreadable table rather than no processes.
+ */
+export function processList({ where = null, match = null, cmdMax = 4000, cpu = false, run = spawnSync, platform = process.platform, timeoutMs = 120_000 } = {}) {
+  try {
+    let rows;
+    if (platform === 'win32') {
+      const r = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', processListScript({ where, cmdMax, cpu })],
+        { encoding: 'utf8', windowsHide: true, timeout: timeoutMs, maxBuffer: 256 * 1024 * 1024 });
+      if (!r || r.error || r.status !== 0) return null;
+      rows = processRowsOfJson(r.stdout);
+    } else {
+      const r = run('ps', ['-eo', 'pid=,ppid=,comm=,args='], { encoding: 'utf8', timeout: Math.min(timeoutMs, 30_000) });
+      if (!r || r.error || r.status !== 0) return null;
+      rows = processRowsOfPs(r.stdout, cmdMax);
+    }
+    return match ? rows.filter((p) => match.test(p.cmd)) : rows;
+  } catch { return null; }
+}

package/runtime/scripts/api/process/system-tool.mjs

@@ -0,0 +1,37 @@
+// system-tool.mjs — the absolute path of one OS system tool, taken from FIXED directories no ordinary user can write:
+// Windows <SystemRoot>\System32 (and the NVIDIA driver's own folders), POSIX /usr/bin, /bin, /usr/sbin, /sbin. A tool is
+// never looked up through PATH, so a writable directory early on PATH cannot stand in for it. The process call files
+// spawn the returned path; a tool the host does not carry is a typed refusal, which each caller turns into its own
+// degraded answer (null, "unknown"), never a crash.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readEnv } from '../../lib/env.mjs';
+
+const DEFAULT_SYSTEM_ROOT = ['C:', 'Windows'].join(path.win32.sep);
+const POSIX_DIRS = ['/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+// Windows: path segments under <SystemRoot>\System32 (nvidia-smi also under <drive>\Program Files\NVIDIA Corporation\NVSMI, its legacy home).
+const WINDOWS_TOOLS = {
+  cmd: [['cmd.exe']], powershell: [['WindowsPowerShell', 'v1.0', 'powershell.exe']], schtasks: [['schtasks.exe']], netstat: [['NETSTAT.EXE']], tasklist: [['tasklist.exe']],
+  'nvidia-smi': [['nvidia-smi.exe'], ['..', '..', 'Program Files', 'NVIDIA Corporation', 'NVSMI', 'nvidia-smi.exe']],
+};
+const POSIX_TOOLS = { sh: 'sh', lsof: 'lsof', ps: 'ps', 'nvidia-smi': 'nvidia-smi' };
+
+const refusal = (tool, platform) => ({ ok: false, code: 'SYSTEM_TOOL_UNAVAILABLE', tool, platform });
+
+/** {ok: true, path} (absolute, existing) or the typed refusal {ok: false, code: 'SYSTEM_TOOL_UNAVAILABLE', tool, platform}. `exists` is the file probe. */
+export function systemTool(tool, { platform = process.platform, env = process.env, exists = (file) => fs.existsSync(file) } = {}) {
+  if (platform === 'win32') {
+    const root = readEnv('SystemRoot', env) ?? readEnv('SYSTEMROOT', env) ?? readEnv('windir', env) ?? readEnv('WINDIR', env) ?? DEFAULT_SYSTEM_ROOT;
+    const system32 = path.win32.join(root, 'System32');
+    for (const rel of Object.hasOwn(WINDOWS_TOOLS, tool) ? WINDOWS_TOOLS[tool] : []) {
+      const file = path.win32.join(system32, ...rel);
+      if (exists(file)) return { ok: true, path: file };
+    }
+    return refusal(tool, platform);
+  }
+  for (const dir of Object.hasOwn(POSIX_TOOLS, tool) ? POSIX_DIRS : []) {
+    const file = path.posix.join(dir, POSIX_TOOLS[tool]);
+    if (exists(file)) return { ok: true, path: file };
+  }
+  return refusal(tool, platform);
+}