@starci/hfs 4.0.7 → 4.0.9

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

@@ -0,0 +1,14 @@
+// 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, 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'; }
+}

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

@@ -0,0 +1,104 @@
+// safe-remove.mjs — the ONE way the runtime deletes a directory tree.
+//
+// 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).
+//
+// 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 (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 path from 'node:path';
+import { sleepSync } from '../../lib/sleep-sync.mjs';
+import { samePath } from '../../lib/path-key.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;
+
+const retrying = (fn, retries) => {
+  for (let attempt = 0; ; attempt += 1) {
+    try { fn(); return null; } catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      if (attempt >= retries || ![...FS_BUSY, 'ENOTEMPTY'].includes(error?.code)) return error;
+      sleepSync(25 * (attempt + 1));
+    }
+  }
+};
+const removeFile = (p, retries) => retrying(() => {
+  try { fs.unlinkSync(p); } catch (error) {
+    if (WIN && (error?.code === 'EPERM' || error?.code === 'EACCES')) { fs.chmodSync(p, 0o666); fs.unlinkSync(p); } else throw error;
+  }
+}, retries);
+
+/**
+ * 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 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 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) }); };
+  const refused = root ? forbiddenRoot(target, { checkoutsUnder, hold }) : 'no path';
+  if (refused) { fail(target, { code: 'REFUSED', message: `refusing to remove ${refused}` }); return out; }
+  let st;
+  try { st = fs.lstatSync(target); } catch (error) {
+    if (error?.code === 'ENOENT') { out.ok = true; return out; }
+    fail(target, error); return out;
+  }
+  // CONTAINMENT (the .claude/node_modules wipe, 2026-09-28): nothing is ever deleted whose real path is not
+  // the root itself or strictly under the root's real path. A link is unlinked above (the link only); any other
+  // entry that resolves outside the tree is refused, whatever made it look like a plain entry.
+  const rootReal = realpathOr(target);
+  const insideRoot = (p) => { const real = realpathOr(p); if (!real || !rootReal) return false; if (same(real, rootReal)) return true;
+    const rel = path.relative(rootReal, real); return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel); };
+  const walk = (dir, st, parentReal) => {
+    if (isLinkLike(dir, { parentReal, stat: st })) {
+      if (unlinkOnly(dir)) { out.removed.links += 1; return true; }
+      fail(dir, { code: 'LINK_STUCK', message: 'a link could not be unlinked; nothing above it is removed' });
+      return false;
+    }
+    if (!insideRoot(dir)) {
+      fail(dir, { code: 'OUTSIDE_ROOT', message: `refusing to delete ${dir}: its real path ${realpathOr(dir) ?? '?'} is outside ${rootReal ?? target}` });
+      return false;
+    }
+    if (!st.isDirectory()) {
+      const error = removeFile(dir, retries);
+      if (error) { fail(dir, error); return false; }
+      out.removed.files += 1; return true;
+    }
+    const real = realpathOr(dir);
+    if (!real) { fail(dir, { code: 'REALPATH', message: 'cannot resolve the directory' }); return false; }
+    let entries;
+    try { entries = fs.readdirSync(dir); } catch (error) { fail(dir, error); return false; }
+    let clear = true;
+    for (const name of entries) {
+      const child = path.join(dir, name);
+      let childStat;
+      try { childStat = fs.lstatSync(child); } catch (error) { if (error?.code !== 'ENOENT') { fail(child, error); clear = false; } continue; }
+      if (!walk(child, childStat, real)) clear = false;
+    }
+    if (!clear) return false;
+    const error = retrying(() => fs.rmdirSync(dir), retries);
+    if (error) { fail(dir, error); return false; }
+    out.removed.dirs += 1; return true;
+  };
+  walk(target, st, null);
+  out.ok = !fs.existsSync(target) && (() => { try { fs.lstatSync(target); return false; } catch { return true; } })();
+  return out;
+}

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,13 @@
-// scripts/api/git/lib.mjs — the one place the runtime spawns git (scripts/checks/check-layers.mjs enforces it).
+// 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 { 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.
@@ -20,27 +21,16 @@ export const gitSpawn = (file, args, options = {}) => {
   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/sops/decrypt.mjs

@@ -1,15 +1,19 @@
-// decrypt.mjs — one `sops` decryption: the custody reads (scripts/lib/sops-exec-env.mjs readCustody) and the test
-// secrets (scripts/lib/test-secrets.mjs testSecret). The plaintext stays in this process's memory (stdout over a pipe).
+// decrypt.mjs — one `sops` decryption: the custody reads (scripts/api/sops/exec-env.mjs execEnv) and the test
+// secrets (scripts/uat/test-secret.mjs testSecret). The plaintext stays in this process's memory (stdout over a pipe).
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { resolveSops } from './lib.mjs';
 
 /**
- * Run `<bin> <args>` with SOPS_AGE_KEY_FILE defaulted to ~/.starci/master.identity. {status, stdout, stderr, error}.
+ * Run `<bin> <args>` (bin null: the sops resolveSops finds) with SOPS_AGE_KEY_FILE defaulted to ~/.starci/master.identity.
+ * {status, stdout, stderr, error}; a missing sops is {status: null, error: SOPS_MISSING}.
  */
-export function sopsDecrypt(bin, args, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024 } = {}) {
-  const r = spawnSync(bin, args, {
-    cwd, encoding: 'utf8', windowsHide: true, maxBuffer,
+export function decrypt(bin, args, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024, timeout = undefined } = {}) {
+  const exe = bin ?? resolveSops(env);
+  if (!exe) return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
+  const r = spawnSync(exe, args, {
+    cwd, encoding: 'utf8', windowsHide: true, maxBuffer, timeout,
     env: { ...env, SOPS_AGE_KEY_FILE: env.SOPS_AGE_KEY_FILE || path.join(os.homedir(), '.starci', 'master.identity') },
   });
   return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };

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

@@ -0,0 +1,35 @@
+// scripts/api/sops/lib.mjs — what the sops call files beside it share: the input type a custody file's name states.
+// Custody members are committed as `<name>.<fmt>.enc`; sops infers a format from the LAST extension, so `.enc` reads as
+// binary and every read states the format (--input-type). The call files (decrypt.mjs, encrypt.mjs, exec-env.mjs) each
+// name one sops use.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FORMATS = { yaml: 'yaml', yml: 'yaml', json: 'json', env: 'dotenv', dotenv: 'dotenv' };
+
+/** The sops input type `<name>.<format>.enc` states, or the explicit override. Throws when neither names one. */
+export function custodyInputType(file, override) {
+  if (override) {
+    if (!Object.values(FORMATS).includes(override)) throw new Error(`unsupported --input-type ${override}`);
+    return override;
+  }
+  const match = /\.([a-z]+)\.enc$/iu.exec(String(file));
+  const type = match ? FORMATS[match[1].toLowerCase()] : undefined;
+  if (!type) throw new Error(`${file}: name it <name>.<yaml|json|env>.enc or pass --input-type`);
+  return type;
+}
+
+/** The sops binary: PATH, then winget's Links and Packages (spawn without a shell ignores PATHEXT). */
+export function resolveSops(env = process.env) {
+  const win = process.platform === 'win32';
+  const names = win ? ['sops.exe', 'sops'] : ['sops'];
+  const dirs = String(env.PATH ?? '').split(win ? ';' : ':').filter(Boolean);
+  if (win && env.LOCALAPPDATA) {
+    const winget = path.join(env.LOCALAPPDATA, 'Microsoft', 'WinGet');
+    dirs.push(path.join(winget, 'Links'));
+    const packages = path.join(winget, 'Packages');
+    try { for (const e of fs.readdirSync(packages)) if (/sops/i.test(e)) dirs.push(path.join(packages, e)); } catch { /* none */ }
+  }
+  for (const dir of dirs) for (const n of names) { const f = path.join(dir, n); try { if (fs.statSync(f).isFile()) return f; } catch { /* next */ } }
+  return null;
+}

package/runtime/scripts/api/sops/seal.mjs

@@ -0,0 +1,18 @@
+// seal.mjs - one `sops encrypt` of a plaintext document held in memory: the canon command `starci app secret set` and `starci app secret gen`
+// (scripts/hfs/secret.mjs). The plaintext travels on the child's stdin and never on its argument list, so it is not visible in a
+// process listing; the ciphertext comes back on stdout.
+import { spawnSync } from 'node:child_process';
+import { resolveSops } from './lib.mjs';
+
+/**
+ * Run `<bin> encrypt` (bin null: the sops resolveSops finds) over `plaintext` of format `inputType` (json, yaml or dotenv). Sops reads stdin only with a `--filename-override`, the path the sealed
+ * file will have: recipients are age keys (`--age`), and when none are given sops picks them from the repository's .sops.yaml for that path. {status, stdout, stderr, error}.
+ */
+export function seal(bin, { inputType, plaintext, recipients = [], filenameOverride }, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024 } = {}) {
+  const args = ['encrypt', '--input-type', inputType, '--output-type', inputType, '--filename-override', filenameOverride];
+  if (recipients.length) args.push('--age', recipients.join(','));
+  const exe = bin ?? resolveSops(env);
+  if (!exe) return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
+  const r = spawnSync(exe, args, { cwd, env, input: plaintext, encoding: 'utf8', windowsHide: true, maxBuffer });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
+}

package/runtime/scripts/{lib/hfs-allows.mjs → hfs/allows.mjs}

@@ -1,10 +1,10 @@
 import path from 'node:path';
-import { braceVariants, globExpression } from './glob.mjs';
+import { braceVariants, globExpression } from '../lib/glob.mjs';
 
 /**
  * What a slot's `requires`, `allows` and `forbids` entries (knowledge/hfs/slots.yaml) say about a file, read through the
- * resolver of scripts/lib/hfs-slots.mjs. The machine checks that judge "this folder holds only what its slot allows"
- * (feature-shape, fe-slot-allows) and the front-end lint rules (through `hfs.allows(file)` of scripts/lib/hfs-view.mjs) read it here so no check keeps a path list.
+ * resolver of scripts/hfs/slots.mjs. The machine checks that judge "this folder holds only what its slot allows"
+ * (feature-shape, fe-slot-allows) and the front-end lint rules (through `hfs.allows(file)` of scripts/hfs/view.mjs) read it here so no check keeps a path list.
  *
  * An entry is a name relative to the slot instance root: `<var>` is the instance's bound variable when the slot binds it
  * (`<feature>`, `<capability>`) and one path segment of any text otherwise (`<action>`), `*` and `?` stay inside a segment,