@starci/hfs 4.0.8 → 4.0.10

package/runtime/modules/ops/_labels.yaml

@@ -0,0 +1,53 @@
+# _labels.yaml — the human name of every operation, one shared map.
+# The underscore prefix keeps this file out of the op catalog scan, like
+# _common.yaml: scripts/route/build-ops-registry.mjs and route-op.mjs skip
+# modules/ops/*.yaml files whose names start with "_".
+#
+# Owner request 2026-09-27: kernels, workflows and op workers carry names a person understands. The
+# op id (interface.draw) stays the key everywhere — the ledger, the api, job ids, contracts; this map
+# only says what a human reads for it. Every reader goes through scripts/lib/display-names.mjs
+# (opLabel): Orca [Op] worker titles, starci kernel status legs/nextActions `label`, the supervisor digest and
+# progress report, Telegram notices and the harness UI (ui/server.mjs sends the map in the snapshot
+# as `opLabels`, so the UI shows exactly these words). tests/lib/display-names.spec.mjs keeps one entry per
+# modules/ops/ops/*.yaml. `vi` is what the owner reads; `en` is the UI's English rendering of it.
+schema: starci/op-labels@1
+
+labels:
+  request.analyze: { vi: Phân tích yêu cầu, en: Analyze request }
+  task.execute: { vi: Chọn luồng việc, en: Select workflow }
+  scope.define: { vi: Xác định phạm vi, en: Define scope }
+  scope.finish: { vi: Kết thúc phạm vi, en: Finish scope }
+  goal.revise: { vi: Sửa mục tiêu, en: Revise goal }
+  business.decide: { vi: Chốt nghiệp vụ, en: Decide business rules }
+  architecture.decide: { vi: Thiết kế kiến trúc, en: Design architecture }
+  brand.decide: { vi: Chốt thương hiệu, en: Decide brand }
+  decision.prepare: { vi: Chuẩn bị quyết định, en: Prepare decision }
+  provision.ask: { vi: Xin thông tin, en: Request information }
+  work.author: { vi: Chia việc chi tiết, en: Plan work }
+  workspace.manage: { vi: Dựng workspace, en: Manage workspace }
+  knowledge.repair: { vi: Sửa tri thức, en: Repair knowledge }
+  grammar.update: { vi: Bổ sung Grammar, en: Update grammar }
+  interface.draw: { vi: Vẽ giao diện, en: Draw interface }
+  interface.asset: { vi: Làm hình ảnh, en: Make assets }
+  interface.scaffold: { vi: Dựng khung giao diện, en: Scaffold interface }
+  interface.implement: { vi: Code giao diện, en: Implement interface }
+  interface.audit: { vi: Soát giao diện, en: Audit interface }
+  backend.scaffold: { vi: Dựng khung backend, en: Scaffold backend }
+  backend.implement: { vi: Code backend, en: Implement backend }
+  package.scaffold: { vi: Dựng khung package, en: Scaffold package }
+  code.refactor: { vi: Chỉnh sửa mã nguồn, en: Refactor code }
+  content.generate: { vi: Soạn nội dung, en: Generate content }
+  docs.author: { vi: Viết tài liệu, en: Write docs }
+  test.author: { vi: Viết test, en: Write tests }
+  integration.verify: { vi: Kiểm thử tích hợp, en: Integration test }
+  e2e.verify: { vi: Kiểm thử đầu cuối, en: End-to-end test }
+  perf.verify: { vi: Kiểm thử hiệu năng, en: Performance test }
+  unit.verify: { vi: Chạy toàn bộ unit test, en: Full unit test run }
+  security.verify: { vi: Soát bảo mật, en: Security review }
+  uat.verify: { vi: Kiểm thử UAT, en: UAT test }
+  uat.assisted.prepare: { vi: Chuẩn bị UAT có người, en: Prepare assisted UAT }
+  uat.assisted.verify: { vi: Xác minh UAT có người, en: Verify assisted UAT }
+  review.verify: { vi: Review cuối, en: Final review }
+  handover.review: { vi: Bàn giao, en: Handover }
+  release.deliver: { vi: Phát hành, en: Release }
+  runtime.operate: { vi: Vận hành môi trường, en: Operate runtime }

package/runtime/scripts/api/fs/forbidden-root.mjs

@@ -0,0 +1,51 @@
+// forbidden-root.mjs — the paths the runtime must never remove whole (safe-remove.mjs safeRemove refuses them before it
+// deletes anything; scripts/machine/worktree-git.mjs asks it before a worktree removal).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { samePath } from '../../lib/path-key.mjs';
+import { realpathOr } from '../../lib/fs-kind.mjs';
+
+const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+/**
+ * True when `p` sits strictly below `root` by real path: no link on the way, not `root` itself. The one place a
+ * primary checkout may be removed is a disposable fixture a caller names by its temp root (hk-tmp).
+ */
+function strictlyInsideReal(p, root) {
+  if (!root) return false;
+  const rel = path.relative(path.resolve(root), path.resolve(p));
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
+  const real = realpathOr(p);
+  const rootReal = realpathOr(root);
+  // Its real path must be the same relative place under the root's real path: no link between them.
+  return Boolean(real && rootReal) && samePath(real, path.join(rootReal, rel));
+}
+
+/**
+ * A path the runtime must never remove whole: a filesystem root, the home or temp directory, the runtime, the
+ * repository that hosts it, the repositories root, or a primary git checkout (its .git is a directory; the
+ * scratch trees the runtime removes are temp directories and linked worktrees, whose .git is a file).
+ * `checkoutsUnder` names a disposable root (hk-tmp's temp root): a checkout strictly inside it by real path
+ * is a spec fixture, not a live repository, and is not refused for its .git. Every other refusal stands.
+ * `hold(path)` is the caller's artifact-hold check (scripts/machine/artifact-hold.mjs artifactHoldReason: a tree holding
+ * an indexed job artifact, or inside an evidence directory holding one, whatever the workflow's phase), its refusal line
+ * or null. It is required: without one every path is refused (fail closed); a caller that removes only a scratch tree
+ * it made itself, outside every ledger's repository, says so with `hold: () => null`.
+ */
+export function forbiddenRoot(p, { checkoutsUnder = null, hold } = {}) {
+  const resolved = path.resolve(p);
+  if (path.parse(resolved).root === resolved || samePath(path.dirname(resolved), resolved)) return 'a filesystem root';
+  for (const [name, dir] of [['the home directory', os.homedir()], ['the temp directory', os.tmpdir()], ['the runtime', SKILL_ROOT],
+    ['the repository hosting the runtime', path.dirname(SKILL_ROOT)], ['the repositories root', path.dirname(path.dirname(SKILL_ROOT))]]) {
+    if (dir && samePath(path.resolve(dir), resolved)) return name;
+  }
+  if (typeof hold !== 'function') return 'a tree no artifact-hold check cleared (pass hold)';
+  const held = hold(resolved);
+  if (held) return held;
+  let checkout = false;
+  try { checkout = fs.lstatSync(path.join(resolved, '.git')).isDirectory(); } catch { /* no .git directory */ }
+  if (checkout && !strictlyInsideReal(resolved, checkoutsUnder)) return 'a git checkout';
+  return null;
+}

package/runtime/scripts/api/fs/is-link-like.mjs

@@ -0,0 +1,25 @@
+// is-link-like.mjs — whether a path is a link of any kind (a symlink, a junction, or another reparse point that
+// redirects it), read with lstat, readlink and real paths. Every tree walk of the runtime asks it before it enters a
+// directory (safe-remove.mjs, links-under.mjs, the housekeeping collectors), so no walk ever follows a link
+// (inc-c8fbf76aa499).
+import fs from 'node:fs';
+import path from 'node:path';
+import { samePath } from '../../lib/path-key.mjs';
+import { realpathOr } from '../../lib/fs-kind.mjs';
+
+/**
+ * True when `p` is a link of any kind: a symlink, a junction, or another reparse point that redirects it.
+ * `parentReal` (the real path of p's parent, when the caller walked to it through real directories) lets the
+ * real-path test catch a reparse point lstat and readlink do not report. A missing path is not a link.
+ */
+export function isLinkLike(p, { parentReal = null, stat = null } = {}) {
+  let st = stat;
+  if (!st) { try { st = fs.lstatSync(p); } catch { return false; } }
+  if (st.isSymbolicLink()) return true;
+  if (!st.isDirectory()) return false;
+  try { fs.readlinkSync(p); return true; } catch { /* not a link readlink can read */ }
+  const parent = parentReal ?? realpathOr(path.dirname(p));
+  const real = realpathOr(p);
+  if (!parent || !real) return true; // cannot prove it is a plain directory: treat it as a link
+  return !samePath(real, path.join(parent, path.basename(p)));
+}

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

@@ -1,6 +1,20 @@
 // scripts/api/fs/lib.mjs — what the fs call files beside it share: the error codes Windows returns while another
-// process holds a path open. The call files (safe-remove.mjs, rename-over.mjs, rmdir-link.mjs, zip-write.mjs) each
-// name one filesystem use.
+// process holds a path open, and the verified unlink of one link. The call files (safe-remove.mjs, remove-links-under.mjs,
+// rename-over.mjs, zip-write.mjs, ...) each name one filesystem use.
+import fs from 'node:fs';
 
 /** The rename and unlink errors Windows returns while another process holds the target open: retried, never final. */
 export const FS_BUSY = Object.freeze(['EPERM', 'EBUSY', 'EACCES']);
+
+/** Remove a link itself, never its target. True when nothing is left at `p`. */
+export function unlinkOnly(p) {
+  try { fs.lstatSync(p); } catch (error) { return error?.code === 'ENOENT'; }
+  try { fs.unlinkSync(p); } catch { try { fs.rmdirSync(p); } catch { /* verified below */ } }
+  try { fs.lstatSync(p); return false; } catch (error) { return error?.code === 'ENOENT'; }
+}
+
+/** Construct an archive-reader refusal with its existing error code. */
+export const zipRefuse = (message, code = 'zip-corrupt') => Object.assign(new Error(message), { code });
+
+/** Relative ZIP entry names exclude traversal, drive roots and control characters. */
+export const validZipName=name=>Boolean(name)&&!name.startsWith('/')&&!/^[A-Za-z]:/.test(name)&&!/[\0\r\n\\]/.test(name)&&!name.split('/').includes('..');

package/runtime/scripts/api/fs/safe-remove.mjs

@@ -1,75 +1,35 @@
-// safe-remove.mjs — the ONE way the runtime deletes a directory tree (nivo-fe inc-c8fbf76aa499).
+// safe-remove.mjs — the ONE way the runtime deletes a directory tree.
 //
-// At 05:47 on 2026-09-25 D:/Repositories/nivo-fe lost 674 tracked working-tree files and its node_modules: a
+// A product repository once lost 674 tracked working-tree files and its node_modules: a
 // recursive delete of a scratch tree followed directory links (Windows junctions) into the live repository.
 // Git for Windows' `git worktree remove --force` follows a junction inside the worktree and empties its target
 // (proven on this host, git 2.52), and a PowerShell/cmd/third-party recursive delete may do the same. A tree
 // that holds links to live checkouts is exactly what the runtime makes (node_modules junctions in land and
 // worker staging checkouts, push-mains scratch worktrees, dependency mirrors).
 //
-// safeRemoveTree walks the tree itself with lstat and NEVER descends into a link: every symlink, junction or
+// safeRemove walks the tree itself with lstat and NEVER descends into a link: every symlink, junction or
 // other reparse point is unlinked as a link (the link only, never what it points at) and verified gone. A
 // directory counts as a link when lstat says so, when readlink resolves it, or when its real path is not
 // its own path under its parent's real path (any name-surrogate reparse point). A link that cannot be
 // unlinked stops the removal of everything above it; nothing is ever deleted through it.
 //
 // A worktree's removal composes this with git (scripts/machine/worktree-git.mjs safeRemoveWorktree, the Orca home in
-// scripts/machine/worktree-orca.mjs): every link removed as a link first (removeLinksUnder), zero asserted, only then git
-// or Orca. Whether a tree holds an indexed job artifact is the caller's decision (`hold`: scripts/machine/artifact-hold.mjs
-// artifactHoldReason), taken before anything is deleted.
+// scripts/machine/worktree-orca.mjs): every link removed as a link first (remove-links-under.mjs), zero asserted, only then
+// git or Orca. The link test is is-link-like.mjs, the refused roots forbidden-root.mjs. Whether a tree holds an indexed
+// job artifact is the caller's decision (`hold`: scripts/machine/artifact-hold.mjs artifactHoldReason), taken before
+// anything is deleted.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { sleepSync } from '../../lib/sleep-sync.mjs';
 import { samePath } from '../../lib/path-key.mjs';
-import { rmdirLink } from './rmdir-link.mjs';
-import { FS_BUSY } from './lib.mjs';
 import { realpathOr } from '../../lib/fs-kind.mjs';
+import { FS_BUSY, unlinkOnly } from './lib.mjs';
+import { isLinkLike } from './is-link-like.mjs';
+import { forbiddenRoot } from './forbidden-root.mjs';
 
 const WIN = process.platform === 'win32';
 const same = samePath;
 
-/**
- * True when `p` is a link of any kind: a symlink, a junction, or another reparse point that redirects it.
- * `parentReal` (the real path of p's parent, when the caller walked to it through real directories) lets the
- * real-path test catch a reparse point lstat and readlink do not report. A missing path is not a link.
- */
-export function isLinkLike(p, { parentReal = null, stat = null } = {}) {
-  let st = stat;
-  if (!st) { try { st = fs.lstatSync(p); } catch { return false; } }
-  if (st.isSymbolicLink()) return true;
-  if (!st.isDirectory()) return false;
-  try { fs.readlinkSync(p); return true; } catch { /* not a link readlink can read */ }
-  const parent = parentReal ?? realpathOr(path.dirname(p));
-  const real = realpathOr(p);
-  if (!parent || !real) return true; // cannot prove it is a plain directory: treat it as a link
-  return !same(real, path.join(parent, path.basename(p)));
-}
-
-/** Remove a link itself, never its target. True when nothing is left at `p`. */
-/** Every link (symlink, junction, other reparse point) under root, found with lstat; the walk never enters one. */
-export function linksUnder(root) {
-  const found = [];
-  const visit = (p, parentReal) => {
-    let stat;
-    try { stat = fs.lstatSync(p); } catch { return; }
-    if (isLinkLike(p, { parentReal, stat })) { found.push(p); return; }
-    if (!stat.isDirectory()) return;
-    let real, names;
-    try { real = fs.realpathSync.native(p); names = fs.readdirSync(p); } catch { return; }
-    for (const name of names) visit(path.join(p, name), real);
-  };
-  visit(path.resolve(root), null);
-  return found;
-}
-
-export function unlinkOnly(p) {
-  try { fs.lstatSync(p); } catch (error) { return error?.code === 'ENOENT'; }
-  try { fs.unlinkSync(p); } catch { try { fs.rmdirSync(p); } catch { /* verified below */ } }
-  try { fs.lstatSync(p); return false; } catch (error) { return error?.code === 'ENOENT'; }
-}
-
 const retrying = (fn, retries) => {
   for (let attempt = 0; ; attempt += 1) {
     try { fn(); return null; } catch (error) {
@@ -85,54 +45,12 @@ const removeFile = (p, retries) => retrying(() => {
   }
 }, retries);
 
-const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
-/**
- * True when `p` sits strictly below `root` by real path: no link on the way, not `root` itself. The one place a
- * primary checkout may be removed is a disposable fixture a caller names by its temp root (hk-tmp).
- */
-export function strictlyInsideReal(p, root) {
-  if (!root) return false;
-  const rel = path.relative(path.resolve(root), path.resolve(p));
-  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
-  const real = realpathOr(p);
-  const rootReal = realpathOr(root);
-  // Its real path must be the same relative place under the root's real path: no link between them.
-  return Boolean(real && rootReal) && same(real, path.join(rootReal, rel));
-}
-
-/**
- * A path the runtime must never remove whole: a filesystem root, the home or temp directory, the runtime, the
- * repository that hosts it, the repositories root, or a primary git checkout (its .git is a directory; the
- * scratch trees the runtime removes are temp directories and linked worktrees, whose .git is a file).
- * `checkoutsUnder` names a disposable root (hk-tmp's temp root): a checkout strictly inside it by real path
- * is a spec fixture, not a live repository, and is not refused for its .git. Every other refusal stands.
- * `hold(path)` is the caller's artifact-hold check (scripts/machine/artifact-hold.mjs artifactHoldReason: a tree holding
- * an indexed job artifact, or inside an evidence directory holding one, whatever the workflow's phase), its refusal line
- * or null. It is required: without one every path is refused (fail closed); a caller that removes only a scratch tree
- * it made itself, outside every ledger's repository, says so with `hold: () => null`.
- */
-export function forbiddenRoot(p, { checkoutsUnder = null, hold } = {}) {
-  const resolved = path.resolve(p);
-  if (path.parse(resolved).root === resolved || same(path.dirname(resolved), resolved)) return 'a filesystem root';
-  for (const [name, dir] of [['the home directory', os.homedir()], ['the temp directory', os.tmpdir()], ['the runtime', SKILL_ROOT],
-    ['the repository hosting the runtime', path.dirname(SKILL_ROOT)], ['the repositories root', path.dirname(path.dirname(SKILL_ROOT))]]) {
-    if (dir && same(path.resolve(dir), resolved)) return name;
-  }
-  if (typeof hold !== 'function') return 'a tree no artifact-hold check cleared (pass hold)';
-  const held = hold(resolved);
-  if (held) return held;
-  let checkout = false;
-  try { checkout = fs.lstatSync(path.join(resolved, '.git')).isDirectory(); } catch { /* no .git directory */ }
-  if (checkout && !strictlyInsideReal(resolved, checkoutsUnder)) return 'a git checkout';
-  return null;
-}
-
 /**
  * Remove `root` and everything under it without ever following a link. Links are unlinked (the link only);
- * plain files and directories are deleted bottom-up. `checkoutsUnder` and `hold` (required) are forbiddenRoot's. Returns {ok, root, removed: {files, dirs, links},
+ * plain files and directories are deleted bottom-up. `checkoutsUnder` and `hold` (required) are forbidden-root.mjs forbiddenRoot's. Returns {ok, root, removed: {files, dirs, links},
  * errors: [{path, code, message}]}; ok is true only when `root` is gone. A missing root is ok.
  */
-export function safeRemoveTree(root, { retries = 5, checkoutsUnder = null, hold } = {}) {
+export function safeRemove(root, { retries = 5, checkoutsUnder = null, hold } = {}) {
   const target = path.resolve(String(root ?? ''));
   const out = { ok: false, root: target, removed: { files: 0, dirs: 0, links: 0 }, errors: [] };
   const fail = (p, error) => { out.errors.push({ path: p, code: error?.code ?? 'ERROR', message: String(error?.message ?? error) }); };
@@ -184,41 +102,3 @@ export function safeRemoveTree(root, { retries = 5, checkoutsUnder = null, hold
   out.ok = !fs.existsSync(target) && (() => { try { fs.lstatSync(target); return false; } catch { return true; } })();
   return out;
 }
-
-/** Remove one link as a link, never its target: `cmd /c rmdir <link>` on Windows (no /s), then unlinkOnly. */
-export function removeLink(p) {
-  if (WIN) {
-    let st = null;
-    try { st = fs.lstatSync(p); } catch { return true; }
-    if (st.isDirectory() || st.isSymbolicLink()) rmdirLink(p);
-  }
-  return unlinkOnly(p);
-}
-
-/**
- * The link step of every worktree removal (scripts/machine/worktree-git.mjs safeRemoveWorktree, worktree-orca.mjs removeOrcaWorktree): every link
- * under `target` found WITHOUT following one (linksUnder), each removed as a link (removeLink: `cmd /c rmdir <link>`, never
- * /s), outermost first, then a re-scan that must find ZERO. {ok, links, errors: [{path, code, message}]}; ok false: a link
- * is stuck and the caller removes nothing.
- */
-export function removeLinksUnder(target) {
-  const out = { ok: false, links: 0, errors: [] };
-  if (!fs.existsSync(target)) { out.ok = true; return out; }
-  for (const link of linksUnder(target)) { if (removeLink(link)) out.links += 1; else out.errors.push({ path: link, code: 'LINK_STUCK', message: 'a link could not be removed' }); }
-  for (const l of linksUnder(target)) if (!out.errors.some((e) => e.path === l)) out.errors.push({ path: l, code: 'LINK_STUCK', message: 'a link is still there after removal' });
-  out.ok = out.errors.length === 0;
-  return out;
-}
-
-/**
- * Unlink `<dir>/node_modules` when it is a link (one an older runtime made; no runtime code makes one, RT_NODE_MODULES_LINK).
- * true when no link is left there; a real directory is left alone (true: it is the checkout's own).
- */
-export function unlinkNodeModulesLink(dir) {
-  const nm = path.join(dir, 'node_modules');
-  let st;
-  try { st = fs.lstatSync(nm); } catch { return true; }
-  if (!st.isSymbolicLink()) return true;
-  try { fs.unlinkSync(nm); } catch { try { fs.rmdirSync(nm); } catch { /* checked below */ } }
-  try { fs.lstatSync(nm); return false; } catch { return true; }
-}

package/runtime/scripts/api/git/config-get.mjs

@@ -0,0 +1,10 @@
+// config-get.mjs — `git config [--local] --get <key>`: one configuration value of a checkout (empty when unset).
+import { gitRunner } from './lib.mjs';
+
+/**
+ * {ok, stdout, stderr}; `local` reads the repository's own config only; `env` replaces the process env (a caller drops
+ * git's repository-local variables). git: the caller's runner or null.
+ */
+export function configGet(cwd, key, { local = false, env = undefined, git = null } = {}) {
+  return gitRunner(git)(['config', ...(local ? ['--local'] : []), '--get', key], env ? { cwd, env } : { cwd });
+}

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

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

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

@@ -1,12 +1,14 @@
 // scripts/api/git/lib.mjs — the one place the runtime spawns git (RT_EXTERNAL_OWNER of scripts/hfs/runtime-rules/external-owner.mjs enforces it).
 //
 // Every caller spelt the same options by hand - encoding:'utf8', windowsHide:true, sometimes a timeout - with two shapes:
-// `git args` in a cwd and `git -C dir args`. gitOutput is the throwing shape (stdout text, or an Error on a non-zero exit).
-// gitSpawn keeps the spawnSync(file, args, options) signature so an injected runner or a spec's fake takes the same three
-// arguments; runGit is the `-C` convenience; gitResult folds the result into the {ok, stdout, error} envelope; gitRunner
-// folds any caller's runner into {ok, stdout, stderr}. The call files beside this one (worktree-*.mjs, rev-parse.mjs, ...)
-// each name one git verb.
+// `git args` in a cwd and `git -C dir args`. gitSpawn keeps the spawnSync(file, args, options) signature so an injected
+// runner or a spec's fake takes the same three arguments; runGit is the `-C` / `-c` convenience; gitRunner folds any
+// caller's runner into {ok, stdout, stderr}. Only the call files beside this one import it: each names one git verb
+// (diff.mjs, ls-files.mjs, worktree-*.mjs, ...), and a caller folds the spawn result it gets back with the pure
+// helpers of scripts/lib/git.mjs (gitResultOf, gitOutputOf).
+import { assertMutationFence } from '../../lib/mutation-fence.mjs';
 import { spawnSync } from 'node:child_process';
+import { withoutGitLocalEnv } from '../../lib/git.mjs';
 
 /**
  * Spawn `file` (the git binary) once with `args`: utf8 text, a hidden window, never a shell.
@@ -15,32 +17,22 @@ import { spawnSync } from 'node:child_process';
  * ERR_UNKNOWN_ENCODING, so it reaches spawnSync as encoding:null (Buffer output either way).
  */
 export const gitSpawn = (file, args, options = {}) => {
+  assertMutationFence({ kind: 'git-effect', args });
   const spawn = { encoding: 'utf8', windowsHide: true, ...options };
   if (spawn.encoding === 'buffer') spawn.encoding = null;
   return spawnSync(file, args, spawn);
 };
 
-/** `git args` in `cwd`, or `git -C dir args` when `dir` is given. `git` overrides the binary. */
-export const runGit = (args, { cwd = null, dir = null, git = 'git', ...options } = {}) =>
-  gitSpawn(git, [...(dir ? ['-C', dir] : []), ...args], cwd ? { cwd, ...options } : options);
-
-/** runGit's stdout as text; throws the spawn error, or an Error carrying git's stderr and exit status, unless git exits 0. */
-export function gitOutput(args, options = {}) {
-  const r = runGit(args, options);
-  if (r.error) throw r.error;
-  if (r.status !== 0) throw Object.assign(new Error(`git ${args.join(' ')} exited ${r.status}: ${(r.stderr ?? '').trim()}`), { status: r.status, stderr: r.stderr });
-  return r.stdout;
-}
-
-/** runGit's result as {ok, stdout, error}: ok only on a clean exit, error from stderr or the spawn. */
-export function gitResult(args, options = {}) {
-  const r = runGit(args, options);
-  return {
-    ok: !r.error && r.status === 0,
-    stdout: r.stdout ?? '',
-    error: (r.stderr ?? '').trim() || String(r.error?.message ?? (r.status == null ? 'timed out' : `exit ${r.status}`)),
-  };
-}
+/**
+ * `git args` in `cwd`, or `git -C dir args` when `dir` is given. `git` overrides the binary; `config` ({key: value})
+ * prefixes one `-c key=value` per entry (core.quotepath=off, a committer identity). Scoped calls discard ambient
+ * hook repository variables; an explicit env remains authoritative, including an intentional temporary index.
+ */
+export const runGit = (args, { cwd = null, dir = null, git = 'git', config = null, ...options } = {}) =>
+  gitSpawn(git, [...(dir ? ['-C', dir] : []), ...Object.entries(config ?? {}).flatMap(([key, value]) => ['-c', `${key}=${value}`]), ...args], {
+    ...(cwd ? { cwd } : {}), ...options,
+    ...((cwd || dir) && options.env === undefined ? { env: withoutGitLocalEnv(process.env) } : {}),
+  });
 
 /**
  * A caller's git runner folded to (args, opts) -> {ok, stdout, stderr}. `git`: the caller's runner (args, {cwd}) ->

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/ls-files.mjs

@@ -0,0 +1,6 @@
+// ls-files.mjs — `git ls-files <args>`: the paths the index tracks (--cached), or the untracked / deleted / ignored ones
+// the flags ask for (-z keeps any file name intact).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git ls-files ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const lsFiles = (args = [], options = {}) => runGit(['ls-files', ...args], options);

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

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

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

@@ -0,0 +1,9 @@
+// merge-base.mjs — `git merge-base <a> <b>`: the best common ancestor of two commits. Whether one commit is in another
+// is is-ancestor.mjs.
+import { gitRunner } from './lib.mjs';
+
+/** The best common ancestor of commits `a` and `b` (a sha), or null when they share none or a ref does not resolve. */
+export const mergeBase = (cwd, a, b, { git = null } = {}) => {
+  const r = gitRunner(git)(['merge-base', a, b], { cwd });
+  return r.ok && r.stdout ? r.stdout : null;
+};

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

@@ -0,0 +1,5 @@
+// remote.mjs — `git remote <args>`: the configured remotes (get-url <name>).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git remote ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const remote = (args = [], options = {}) => runGit(['remote', ...args], options);

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

@@ -0,0 +1,5 @@
+// rev-parse-query.mjs — `git rev-parse <args>`: one rev-parse query (--show-toplevel, --git-common-dir, --git-path, a ref): the text it prints.
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git rev-parse ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const revParseQuery = (args = [], options = {}) => runGit(['rev-parse', ...args], options);

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

@@ -0,0 +1,6 @@
+// show.mjs — `git show <args>`: an object of a repository - a file at a revision (`<rev>:<path>`), or a commit's
+// header and message (-s --format=...).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git show ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const show = (args = [], options = {}) => runGit(['show', ...args], options);

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

@@ -0,0 +1,14 @@
+// scripts/api/node/lib.mjs — the runner of the runtime's own scripts as child processes: the node binary that runs this
+// process (process.execPath), a hidden window, utf8 text. The call files beside it (run-script.mjs, syntax-check.mjs,
+// run-node.mjs, spawn-node.mjs, exec-node.mjs) each name one use; nothing outside scripts/api/node imports this runner.
+import { assertMutationFence } from '../../lib/mutation-fence.mjs';
+import { execFile, spawn, spawnSync } from 'node:child_process';
+
+/** `node <args>` with this process's node binary, waited for; options pass through last (cwd, stdio, env, timeout, maxBuffer, input). */
+export const nodeSpawn = (args, options = {}) => { assertMutationFence({ kind: 'node-effect', args }); return spawnSync(process.execPath, args, { encoding: 'utf8', windowsHide: true, ...options }); };
+
+/** `node <args>` with this process's node binary, started and not waited for: the ChildProcess (detached, stdio, env pass through). */
+export const nodeStart = (args, options = {}) => { assertMutationFence({ kind: 'node-effect', args }); return spawn(process.execPath, args, { windowsHide: true, ...options }); };
+
+/** `node <args>` with this process's node binary, waited for without blocking the thread: callback(error, stdout, stderr). */
+export const nodeExecFile = (args, options, callback) => { assertMutationFence({ kind: 'node-effect', args }); return execFile(process.execPath, args, { encoding: 'utf8', windowsHide: true, ...options }, callback); };

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/process/lib.mjs

@@ -0,0 +1,111 @@
+// 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).replace(/'/g, "''");
+
+/** 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). */
+export const processRowsOfPs = (text, cmdMax = 4000) => String(text ?? '').split(/\r?\n/).map((line) => /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.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 = `
+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((p) => Number(p)).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 ?? {} }));
+};