@starci/hfs 1.0.0 → 2.0.0

package/runtime/scripts/lib/redact.mjs

@@ -0,0 +1,148 @@
+// redact.mjs — the ONE redaction module (alpha.3, ARCHITECTURE-DB §4.2). Every blob put of text bytes
+// (report attachments, check stdout/stderr/output, terminal transcripts, CLI sessions) and every log write
+// passes through here first; the harness UI server reuses it. A blob whose bytes went through redactText is
+// stamped blobs.redaction = REDACTION_VERSION; bytes that cannot be filtered (images, video, archives) are
+// stamped 'binary'.
+//
+// It blanks: provider tokens and JWTs (secret-patterns.mjs, the push scan's list), auth headers, URL query
+// secrets, URL credentials (scheme://user:pass@host), PEM private-key blocks (the whole block), KEY=value /
+// KEY: value pairs whose key names a secret (FOO_API_KEY=..., password: ...), and the declared secrets of a
+// product repo's .starcistacks (their env-style names as keys, and their values wherever they appear).
+// Keys and surrounding words stay, so a redacted transcript still reads.
+import fs from 'node:fs';
+import path from 'node:path';
+import { FORBIDDEN_FILES, SECRET_PATTERNS } from './secret-patterns.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+export const REDACTION_VERSION = 'v1';
+export const MARK = '[redacted]';
+
+const withGlobal = (re) => new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
+const PATTERNS = SECRET_PATTERNS.filter((rule) => rule.name !== 'private-key-block').map((rule) => ({ ...rule, g: withGlobal(rule.re) }));
+// Words that make an env-style key a secret, matched per `_`-separated segment of the name (FOO_API_KEY,
+// KEYCLOAK_ADMIN_PASSWORD, GH_TOKEN, MINIO_SECRET_KEY, DATABASE_URL is not; TESTS_PASSED is not).
+const SECRET_SEGMENTS = new Set(['PASSWORD', 'PASSWD', 'PWD', 'PASS', 'SECRET', 'SECRETS', 'TOKEN', 'APIKEY', 'KEY', 'CREDENTIAL', 'CREDENTIALS', 'COOKIE', 'OTP', 'DSN', 'PAT']);
+export const isSecretEnvName = (name) => String(name).replace(/^export\s+/, '').replace(/_FILE$/, '').split('_').some((seg) => SECRET_SEGMENTS.has(seg));
+const PEM_BLOCK = /-----BEGIN ((?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?)-----[\s\S]*?(?:-----END \1-----|$)/g;
+const RULES = [
+  { name: 'url-credentials', re: /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:@/"'<>]+):([^\s@/"'<>]+)@/gi, to: (m, scheme, user) => `${scheme}${user}:${MARK}@` },
+  { name: 'auth-header', re: /\b(Bearer|Basic|Token)(\s+)[A-Za-z0-9._~+/=-]{8,}/gi, to: (m, a, b) => `${a}${b}${MARK}` },
+  { name: 'url-secret', re: /([?&#](?:access_token|refresh_token|id_token|token|key|api_key|apikey|secret|code|password|otp|sig|signature)=)([^&#\s"']+)/gi, to: (m, a) => `${a}${MARK}` },
+  { name: 'otp', re: /\b(otp|one[-_ ]?time[-_ ]?(?:code|password|pin)|verification[-_ ]?code|2fa[-_ ]?code|mã[ _-]?(?:otp|xác[ _-]?(?:thực|minh)))(\s*[:=]?\s*["']?)(\d{4,8})\b/giu, to: (m, a, b) => `${a}${b}${MARK}` },
+  // ENV_STYLE_KEY=value / ENV_STYLE_KEY: value (shell exports, dotenv, compose, CLI echo).
+  { name: 'env-secret', re: /\b((?:export\s+)?[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*)(\s*[:=]\s*["']?)((?!\[redacted)[^\s"'`]{3,})/g,
+    to: (m, a, b, c) => (isSecretEnvName(a) && !c.startsWith('/run/secrets/') && !c.startsWith('$') ? `${a}${b}${MARK}` : m) },
+  { name: 'keyed-secret', re: /\b(password|passwd|pwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|auth[_-]?token|session[_-]?token|private[_-]?key|otp|pin[_-]?code|cookie|set-cookie)(["']?\s*[:=]\s*["']?)((?!\[redacted)[^\s"',;&}]{3,})/gi, to: (m, a, b) => `${a}${b}${MARK}` },
+];
+
+/** Keys whose value is a secret whatever it looks like; the key stays, the value goes. */
+export const SECRET_KEY = /^(?:password|passwd|pwd|pass|secret|otp|pin|pincode|pin_code|credential|credentials|authorization|cookie|cookies|set-cookie|private[_-]?key|client[_-]?secret|api[_-]?key|apikey|[a-z_-]*token|[a-z_-]*secret)$/i;
+
+// ------------------------------------------------------------------------------ declared stack secrets
+// A product repo's .starcistacks/<stack>/stack.yaml `secrets:` block names each secret and the runtime file
+// that holds its value. Both are learned once per repo root per process; values never leave this module.
+const STACK_DIRS = ['.starcistacks'];
+const learnedRoots = new Set();
+const secretValues = new Set();
+const secretNames = new Set();
+const envName = (name) => String(name).replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '').toUpperCase();
+const readSafe = (file) => { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } };
+const listSafe = (dir) => { try { return fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; } };
+
+/** A value this process must never write out (a secret it resolved itself). Values under 6 chars are ignored. */
+export function addSecretValue(value) {
+  const v = typeof value === 'string' ? value.trim() : '';
+  if (v.length >= 6 && !/^\[redacted/.test(v)) secretValues.add(v);
+}
+
+/** Learn the declared secrets of every .starcistacks stack under `repoRoot` (idempotent). */
+export function learnStackSecrets(repoRoot) {
+  if (typeof repoRoot !== 'string' || !repoRoot) return;
+  const root = path.resolve(repoRoot);
+  if (learnedRoots.has(root)) return;
+  learnedRoots.add(root);
+  for (const stackDir of STACK_DIRS) {
+    for (const entry of listSafe(path.join(root, stackDir))) {
+      if (!entry.isDirectory()) continue;
+      const dir = path.join(root, stackDir, entry.name);
+      const text = readSafe(path.join(dir, 'stack.yaml'));
+      let doc = null;
+      try { doc = text ? parseYaml(text) : null; } catch { doc = null; }
+      const secrets = doc && typeof doc.secrets === 'object' && doc.secrets ? doc.secrets : {};
+      for (const [name, spec] of Object.entries(secrets)) {
+        secretNames.add(envName(name));
+        if (spec && typeof spec.file === 'string') addSecretValue(readSafe(path.resolve(dir, spec.file)));
+      }
+      // Plaintext runtime copies of the secrets (git-ignored): their values are secrets too.
+      for (const file of listSafe(path.join(dir, 'runtime', 'files'))) if (file.isFile()) addSecretValue(readSafe(path.join(dir, 'runtime', 'files', file.name)));
+    }
+  }
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+let namesRe = null, namesSize = -1;
+const declaredNameRule = () => {
+  if (namesSize !== secretNames.size) {
+    namesSize = secretNames.size;
+    namesRe = secretNames.size ? new RegExp(`\\b((?:${[...secretNames].map(escapeRe).join('|')})(?:_FILE)?)(\\s*[:=]\\s*["']?)((?!\\[redacted)[^\\s"'\`]{3,})`, 'g') : null;
+  }
+  return namesRe;
+};
+
+// --------------------------------------------------------------------------------------------- text
+/**
+ * `text` with every secret value blanked. `repoRoots` (optional) are product repos whose .starcistacks
+ * declarations are learned first.
+ */
+export function redactText(text, { repoRoots = [] } = {}) {
+  if (typeof text !== 'string' || !text) return text;
+  for (const root of repoRoots) learnStackSecrets(root);
+  let out = text.replace(PEM_BLOCK, (m, kind) => `[redacted:pem ${kind}]`);
+  for (const value of secretValues) if (out.includes(value)) out = out.split(value).join('[redacted:stack-secret]');
+  for (const rule of PATTERNS) {
+    rule.g.lastIndex = 0;
+    out = out.replace(rule.g, (match, value) => {
+      if (rule.name === 'assigned-secret') return rule.placeholder?.test(value ?? '') ? match : match.replace(value, MARK);
+      return `[redacted:${rule.name}]`;
+    });
+  }
+  const declared = declaredNameRule();
+  if (declared) { declared.lastIndex = 0; out = out.replace(declared, (m, a, b) => `${a}${b}${MARK}`); }
+  for (const rule of RULES) { rule.re.lastIndex = 0; out = out.replace(rule.re, rule.to); }
+  return out;
+}
+
+/** A path that is a secret by being one (an env file, a key file, .secrets/): blanked, its rule named. */
+export function redactPath(p) {
+  if (typeof p !== 'string') return p;
+  const slashed = p.replace(/\\/g, '/');
+  const rule = FORBIDDEN_FILES.find((r) => r.test(slashed));
+  return rule ? `[redacted:${rule.name}]` : redactText(p);
+}
+
+/** A deep copy of `value` with secret-named keys blanked and every string redacted. */
+export function redactData(value, key = null, depth = 0) {
+  if (depth > 8) return '[depth]';
+  if (key && SECRET_KEY.test(key) && value != null && typeof value !== 'object' && typeof value !== 'boolean') return MARK;
+  if (typeof value === 'string') return /(?:path|ref|file)$/i.test(key ?? '') ? redactPath(value) : redactText(value);
+  if (Array.isArray(value)) return value.map((v) => redactData(v, null, depth + 1));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactData(v, k, depth + 1)]));
+  return value;
+}
+
+// -------------------------------------------------------------------------------------------- bytes
+/** True for media types whose bytes are text the filter can read. */
+export const isTextMedia = (mediaType) => /^text\/|[/+](?:json|xml|yaml|x-yaml|javascript|x-ndjson|x-diff|x-patch|csv|sql|x-sh)\b|^application\/(?:json|xml|yaml|javascript|x-ndjson|x-diff|x-patch|sql)$/i
+  .test(String(mediaType ?? ''));
+
+/**
+ * Bytes ready for a blob put: text bytes redacted ({redaction:'v1'}), anything else untouched
+ * ({redaction:'binary'}). The blob sha is then taken over the returned bytes.
+ */
+export function redactBytes(bytes, mediaType, { repoRoots = [] } = {}) {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  if (!isTextMedia(mediaType)) return { bytes: buf, redaction: 'binary' };
+  const text = buf.toString('utf8');
+  const clean = redactText(text, { repoRoots });
+  return { bytes: clean === text ? buf : Buffer.from(clean, 'utf8'), redaction: REDACTION_VERSION };
+}

package/runtime/scripts/lib/repo-identity.mjs

@@ -0,0 +1,50 @@
+// repo-identity.mjs - who a repository is, independent of the folder it is checked out in.
+// A git worktree (D:/starci-lanes/<lane>/<name>) and the main checkout of the same repository are ONE repository:
+// they carry the same README title, the same stack-declaration project name and the same sibling repositories.
+import fs from 'node:fs';
+import path from 'node:path';
+import { gitOutput } from './git.mjs';
+
+const git = (root, args) => gitOutput(args, { cwd: root }).trim();
+const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+/** { repositoryRoot, inWorkTree, home } for `root`: home is the main checkout folder when root is a repository top level. */
+function identityOf(root) {
+  let inWorkTree = false, repositoryRoot = false, home = null;
+  try {
+    // Identity comes from Git only when root IS a repository (or worktree) top level, never a folder inside one.
+    repositoryRoot = real(git(root, ['rev-parse', '--show-toplevel'])) === real(root);
+    inWorkTree = true;
+    const common = path.resolve(root, git(root, ['rev-parse', '--git-common-dir']));
+    if (repositoryRoot && path.basename(common) === '.git') home = path.dirname(common);
+  } catch { /* Not a Git work tree; the caller falls back to the folder and package name. */ }
+  return { inWorkTree, repositoryRoot, home };
+}
+
+/**
+ * The product repository name: the main checkout's folder name (so a worktree and its main checkout agree), else the
+ * origin remote's name, else package.json name outside Git, else the folder name. A folder inside a larger repository
+ * (a nested product, an example) is named by its own folder.
+ */
+export function repositoryName(root) {
+  const { inWorkTree, repositoryRoot, home } = identityOf(root);
+  if (home) return path.basename(home);
+  if (repositoryRoot) {
+    try {
+      const remote = git(root, ['remote', 'get-url', 'origin']).replace(/[\/]+$/u, '').replace(/\.git$/iu, '');
+      const name = remote.split(/[\/:]/u).pop();
+      if (name) return name;
+    } catch { /* No origin remote. */ }
+  }
+  if (inWorkTree && !repositoryRoot) return path.basename(root);
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (typeof pkg.name === 'string' && pkg.name) return pkg.name.replace(/^@[^/]+\//u, '');
+  } catch { /* No readable package.json. */ }
+  return path.basename(root);
+}
+
+/** The folder whose siblings are this repository's sibling repositories: the main checkout for a worktree, else root. */
+export function repositoryHome(root) {
+  return identityOf(root).home ?? path.resolve(root);
+}

package/runtime/scripts/lib/safe-remove.mjs

@@ -0,0 +1,179 @@
+// safe-remove.mjs — the ONE way the runtime deletes a directory tree (nivo-fe inc-c8fbf76aa499).
+//
+// At 05:47 on 2026-09-25 D:/Repositories/nivo-fe 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
+// 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.
+//
+// safeRemoveWorktree removes a git worktree's directory with safeRemoveTree and then prunes the registration,
+// so `git worktree remove --force` never walks the tree.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sleepSync } from './sleep-sync.mjs';
+import { samePath } from './path-key.mjs';
+import { gitSpawn } from './git.mjs';
+import { artifactHoldReason } from './artifact-hold.mjs';
+import { realpathOr } from './fs-kind.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`. */
+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) {
+      if (error?.code === 'ENOENT') return null;
+      if (attempt >= retries || !['EBUSY', 'EPERM', 'EACCES', '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);
+
+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.
+ * A tree holding an indexed job artifact, or inside an evidence directory holding one, is refused whatever the
+ * workflow's phase (artifact-hold.mjs).
+ */
+export function forbiddenRoot(p, { checkoutsUnder = null } = {}) {
+  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;
+  }
+  const held = artifactHoldReason(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` is forbiddenRoot's disposable root. 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 } = {}) {
+  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 }) : '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;
+}
+
+/**
+ * Remove a git worktree without letting git walk it: its directory goes through safeRemoveTree, then
+ * `git worktree prune` (run in `repo`) drops the registration. `git(args, {cwd})` is the caller's git runner;
+ * omitted, git is spawned directly.
+ */
+export function safeRemoveWorktree(worktree, { repo, git = null, retries = 5 } = {}) {
+  const removed = safeRemoveTree(worktree, { retries });
+  if (repo) {
+    const run = git ?? ((args, opts) => gitSpawn('git', args, { cwd: opts.cwd }));
+    try { run(['worktree', 'prune'], { cwd: repo }); } catch { /* the registration is pruned on the next prune */ }
+  }
+  return removed;
+}

package/runtime/scripts/lib/secret-patterns.mjs

@@ -0,0 +1,44 @@
+// secret-patterns.mjs — the one list of secret shapes the runtime refuses to carry: the push secret scan
+// (scripts/supervisor/push-mains.mjs scanDiff) refuses an outgoing range that adds one, and the typed-log
+// redaction (scripts/kernel/typed-logs.mjs redactText) blanks the value before a log row is stored.
+// FORBIDDEN_FILES name paths that are secrets by being (an env file, a key file); SECRET_PATTERNS match values.
+
+export const FORBIDDEN_FILES = [
+  { name: 'env-file', test: (f) => /(^|\/)\.env(\.[^/]*)?$/i.test(f) && !/\.env\.(example|sample|template)$/i.test(f) },
+  { name: 'secrets-dir', test: (f) => /(^|\/)\.secrets\//i.test(f) },
+  { name: 'private-key-file', test: (f) => /\.(pem|key|p12|pfx)$/i.test(f) || /(^|\/)id_(rsa|ed25519|ecdsa)$/i.test(f) },
+  // .starcistacks/<stack>/secrets/ commits sops twins only (owner ruling push-scan-test-secrets-encrypted): a plaintext
+  // credential there - a test password included - is git-ignored by the product repo and never pushed.
+  { name: 'starcistacks-secret-plaintext', test: (f) => /(^|\/)\.starcistacks\/[^/]+\/secrets\//i.test(f) && !/(\.enc|\/\.gitkeep|\/KEYS\.md)$/i.test(f) },
+  { name: 'credentials-json', test: (f) => /(^|\/)(credentials|service-account|client_secret)[^/]*\.json$/i.test(f) },
+];
+export const SECRET_PATTERNS = [
+  { name: 'private-key-block', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
+  { name: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { name: 'github-token', re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{50,}\b/ },
+  { name: 'anthropic-key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}/ },
+  { name: 'openai-key', re: /\bsk-(?:proj-)?[A-Za-z0-9]{32,}\b/ },
+  { name: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/ },
+  { name: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { name: 'telegram-bot-token', re: /\b\d{8,10}:AA[0-9A-Za-z_-]{33}\b/ },
+  { name: 'stripe-secret', re: /\b(?:sk|rk)_live_[0-9A-Za-z]{20,}\b/ },
+  { name: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+  // A keyword-assigned value that names itself a stand-in (a test stub's `accessToken: "fixture-..."`) is no
+  // candidate; only this heuristic takes the exemption, never a provider-shaped token above.
+  // A spec file's keyword-assigned values are test inputs (nivo-fe AuthenticationPage/index.spec.tsx: the sign-in
+  // form's password and a mocked accessToken refused the push, 2026-09-24): the heuristic skips spec files too.
+  { name: 'assigned-secret', re: /\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|client[_-]?secret)\b\s*[:=]\s*['"]([^'"\s$<{]{12,})['"]/i, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+    skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$/ },
+];
+
+
+/** The names of the patterns one line of `file` matches (never the value). A stand-in value and a spec file's keyword assignment are no hit. */
+export function secretHits(file, text) {
+  const names = [];
+  for (const rule of SECRET_PATTERNS) {
+    if (rule.skipFile?.test(file ?? '')) continue;
+    const hit = rule.re.exec(text);
+    if (hit && !rule.placeholder?.test(hit[1] ?? '')) names.push(rule.name);
+  }
+  return names;
+}

package/runtime/scripts/lib/sleep-sync.mjs

@@ -0,0 +1,17 @@
+// sleep-sync.mjs — the blocking wait synchronous code (lock polls, retry backoff) uses.
+
+/**
+ * Test seam: STARCI_SLEEP_SCALE (a number >= 0, default 1) multiplies every wait. A spec that drives a real
+ * dispatch/boot against a fake host sets it small so the card's settle/attestation windows (seconds of pure
+ * waiting, counted logically by their callers, not by the wall clock) cost milliseconds and the run no longer
+ * depends on machine load. Unset in production.
+ */
+const scaleOf = () => {
+  const raw = process.env.STARCI_SLEEP_SCALE;
+  if (raw === undefined || raw === '') return 1;
+  const value = Number(raw);
+  return Number.isFinite(value) && value >= 0 ? value : 1;
+};
+
+/** Block the thread for `ms` milliseconds (scaled by STARCI_SLEEP_SCALE). */
+export const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.round(ms * scaleOf()));

package/runtime/scripts/lib/stack-declaration.mjs

@@ -0,0 +1,52 @@
+// stack-declaration.mjs - the one reader of a repository's stack declaration (.starcistacks/application-stacks.yaml): where it
+// lives, its bounded read and parse, and the stack block of one service as declared. scripts/checks/check-starcistacks.mjs (the
+// services contract) and scripts/lib/hfs-rules/stacks.mjs (the .starcistacks shape, R10) both read it here; this file imports
+// nothing of the kernel, so the published @starci/hfs bundle carries it without the ledger.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { isDir, isFile } from './fs-kind.mjs';
+import { posixPath } from './path-key.mjs';
+
+export const DECLARATION = 'application-stacks.yaml';
+/** The one stack root a repository owns. */
+export const STACK_ROOT = '.starcistacks';
+const MAX_BYTES = 2 * 1024 * 1024;
+
+/** A non-blank string, trimmed; anything else is null. */
+export const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+
+/** The text of `file`, or null when it is absent or larger than 2 MiB. */
+export const readText = (file) => { try { return fs.statSync(file).size > MAX_BYTES ? null : fs.readFileSync(file, 'utf8'); } catch { return null; } };
+
+/** The parsed declaration file: {doc} or {error}. */
+export function readDeclaration(file) {
+  const raw = readText(file);
+  if (raw === null) return { error: 'unreadable or larger than 2 MiB' };
+  try { const doc = parseYaml(raw); return plain(doc) ? { doc } : { error: 'not a YAML mapping' }; }
+  catch (error) { return { error: `YAML does not parse: ${String(error?.message ?? error).split('\n')[0]}` }; }
+}
+
+/**
+ * The stack declaration a repository owns: {root, file, rooted, doc|error} - or {missing:true, rooted}
+ * when .starcistacks/application-stacks.yaml does not exist. `rooted` says the .starcistacks tree exists.
+ */
+export function findStackDeclaration(repoRoot) {
+  const repo = path.resolve(String(repoRoot ?? ''));
+  const rooted = isDir(path.join(repo, STACK_ROOT));
+  const file = path.join(repo, STACK_ROOT, DECLARATION);
+  if (isFile(file)) return { repo, root: STACK_ROOT, file, rooted, ...readDeclaration(file) };
+  return { repo, missing: true, rooted };
+}
+
+/**
+ * The stack block of one declared service, or null when it has none: {owner, root, repository, hostOwned}. A stack is
+ * host-owned when it says `owner: host` (it lives in the installed runtime tree, `.claude/ext/<service>`); `root` is posix.
+ */
+export function declaredStack(entry) {
+  const stack = plain(entry) && plain(entry.stack) ? entry.stack : null;
+  if (!stack) return null;
+  const root = text(stack.root);
+  return { owner: text(stack.owner), root: root === null ? null : posixPath(root), repository: text(stack.repository), hostOwned: text(stack.owner) === 'host' };
+}