@starci/hfs 4.7.31 → 4.7.33

package/runtime/scripts/lib/runtime-publication-tags.mjs

@@ -0,0 +1,99 @@
+// The release owner's dist-tag judgment and idempotent reconciliation, independent of npm processes.
+
+/** Parsed SemVer identifiers, used only to order registry releases and prevent tag rollback. */
+function versionParts(version) {
+  const identifiers = /^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
+  const parts = typeof version === 'string' ? version.split('+') : [];
+  if (!parts.length || parts.length > 2 || (parts.length === 2 && !identifiers.test(parts[1]))) throw new Error(`unreadable registry release version ${version}`);
+  const boundary = parts[0].indexOf('-');
+  const core = (boundary < 0 ? parts[0] : parts[0].slice(0, boundary)).split('.');
+  const prerelease = boundary < 0 ? null : parts[0].slice(boundary + 1);
+  if (core.length !== 3 || core.some((part) => !/^(0|[1-9]\d*)$/.test(part)) || (prerelease !== null && !identifiers.test(prerelease))) throw new Error(`unreadable registry release version ${version}`);
+  const pre = prerelease?.split('.') ?? [];
+  if (pre.some((part) => /^0\d+$/.test(part))) throw new Error(`invalid numeric prerelease identifier in ${version}`);
+  return { core: core.map(BigInt), pre };
+}
+
+const compareIdentifier = (a, b) => {
+  const numericA = /^\d+$/.test(a), numericB = /^\d+$/.test(b);
+  if (numericA && numericB) return BigInt(a) < BigInt(b) ? -1 : Number(BigInt(a) > BigInt(b));
+  if (numericA !== numericB) return numericA ? -1 : 1;
+  return a < b ? -1 : Number(a > b);
+};
+
+/** SemVer precedence, including numeric prerelease ordering; build metadata has no precedence. */
+function compareVersions(a, b) {
+  const left = versionParts(a), right = versionParts(b);
+  for (const i of left.core.keys()) {
+    if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
+  }
+  if (!left.pre.length || !right.pre.length) return Number(!left.pre.length) - Number(!right.pre.length);
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
+    if (left.pre[i] === undefined) return -1;
+    if (right.pre[i] === undefined) return 1;
+    const compared = compareIdentifier(left.pre[i], right.pre[i]);
+    if (compared) return compared;
+  }
+  return 0;
+}
+
+/** Numbered prereleases share their core and nonnumeric prefix; stable releases share major/minor. */
+const releaseLine = (version) => {
+  const { core, pre } = versionParts(version);
+  if (!pre.length) return `${core.slice(0, 2).join('.')}-stable`;
+  const prefix = /^\d+$/.test(pre.at(-1)) ? pre.slice(0, -1) : pre;
+  return `${core.join('.')}-${prefix.join('.')}`;
+};
+
+/**
+ * Plan the release's declared tags from a complete registry read. Unknown reads and historical
+ * releases fail closed; a newer tag on another release line is preserved rather than rolled back.
+ * Returns serializable {tag, version, current, action} entries for the native dry-run plan.
+ */
+export function runtimeTagPlan({ version, tags, state, uploadTag = null }) {
+  versionParts(version);
+  if (!Array.isArray(tags) || !tags.length || tags.some((tag) => typeof tag !== 'string' || !/^[a-z][a-z0-9-]*$/i.test(tag)))
+    throw new Error('runtime publication requires declared npm dist-tags');
+  if (!['present', 'absent'].includes(state?.state) || !Array.isArray(state.versions) || !state.distTags || Array.isArray(state.distTags) || typeof state.distTags !== 'object')
+    throw new Error('runtime dist-tags and version inventory could not be read');
+  if (state.state === 'present' && !state.versions.includes(version)) throw new Error('runtime version inventory omits the published release');
+  const newer = state.versions.find((entry) => releaseLine(entry) === releaseLine(version) && compareVersions(entry, version) > 0);
+  if (newer) throw new Error(`runtime release ${version} is behind ${newer} on its release line; dist-tags cannot move backwards`);
+  const plan = [...new Set(tags)].map((tag) => {
+    const current = state.distTags[tag] ?? null;
+    if (current !== null && typeof current !== 'string') throw new Error(`unreadable npm dist-tag ${tag}`);
+    const compared = current === null ? -1 : compareVersions(current, version);
+    let action = current === version ? 'confirmed' : 'set';
+    if (compared > 0) action = 'preserve';
+    return { tag, version: compared > 0 ? current : version, current,
+      action };
+  });
+  if (uploadTag && plan.some((entry) => entry.tag === uploadTag && entry.action === 'preserve'))
+    throw new Error(`runtime upload channel ${uploadTag} points to a newer release; publication cannot move it backwards`);
+  return plan;
+}
+
+/**
+ * Repair only stale declared tags of an integrity-confirmed runtime version, then read every tag
+ * back. The registry seam owns effects; a failed write/read throws and can be retried without upload.
+ */
+export function reconcileRuntimeTags({ row, tags, registry, out, sleep = null, waitMs = 0, stepMs = 5000 }) {
+  const state = registry.state(row.name, row.version);
+  if (state.state !== 'present' || state.integrity !== row.registry.integrity) throw new Error('runtime registry integrity changed before dist-tag reconciliation');
+  const plan = runtimeTagPlan({ version: row.version, tags, state });
+  for (const entry of plan.filter((item) => item.action === 'set')) {
+    const result = registry.tag(row.name, row.version, entry.tag);
+    if (!result.ok) throw new Error(`npm dist-tag ${entry.tag} failed (exit ${result.status ?? 'unknown'})`);
+  }
+  // Registry propagation of a tag write can lag; poll the read-back inside the window before calling it stale.
+  const deadline = Date.now() + waitMs;
+  let confirmed = registry.state(row.name, row.version);
+  while (sleep && Date.now() < deadline && plan.some((entry) => confirmed.distTags?.[entry.tag] !== entry.version)) {
+    sleep(stepMs);
+    confirmed = registry.state(row.name, row.version);
+  }
+  if (confirmed.state !== 'present' || confirmed.integrity !== state.integrity || plan.some((entry) => confirmed.distTags?.[entry.tag] !== entry.version))
+    throw new Error('runtime dist-tag read-back did not confirm the declared targets and immutable integrity');
+  for (const entry of plan) out(`  dist-tag ${row.name}@${entry.version} ${entry.tag}: ${entry.action === 'preserve' ? 'newer release preserved' : 'confirmed by registry read-back'}`);
+  return plan;
+}

package/runtime/scripts/lib/seat-env.mjs

@@ -0,0 +1,43 @@
+// seat-env.mjs — the seat identity one Orca terminal's environment claims, and the env a runtime child gets.
+//
+// Orca exports the terminal's identity into the shell it owns (ORCA_TERMINAL_HANDLE, ORCA_PANE_KEY, ORCA_TAB_ID,
+// ORCA_WORKTREE_ID, ORCA_AGENT_* — the agent hook endpoint and token included), and a session can carry the caller
+// markers STARCI_ROLE, STARCI_GUARD_FILE and STARCI_CALLER. Caller and guard logic binds a process to a seat by those
+// variables (scripts/guards/op-caller.mjs callerOf, scripts/guards/command-policy.mjs shimDecision, the seat bindings of
+// scripts/guards/hook-install.mjs), so a child the runtime spawns for its own work — the package proof of the land gate,
+// the scaffold e2e, a staging `npm ci` and its lifecycle scripts — that inherits them is admitted as
+// the seat: a supervisor seat's `node install.js` reads as a raw supervisor tool call (RIGHTS_RAW_TOOL) and a spec's
+// kernel call resolves the seat's custody (kernel-caller-unknown). The seat's own agent tool calls keep the identity;
+// every other child of it gets this env.
+//
+// The seat's PATH can likewise carry the per-user guard-shim directory first (<home>/.starci/bin,
+// packages/cli/src/shim.mjs writeRuntimeShim — put there by scripts/agent/starci-shim.mjs addStarciShimToPath): its
+// wrappers judge `node`, `git`, `npm` and friends through shimDecision before reaching the real tool. Without the
+// seat identity a wrapper binds no role and passes through, but a runtime child that never answers to the seat —
+// the codex app-server probe, whose `codex` launcher resolves `node` through PATH — also gets PATH without the shim
+// directory, so nothing it spawns is ever re-judged.
+import os from 'node:os';
+import path from 'node:path';
+
+/** The variables that bind a process to the calling seat or claim a caller identity. */
+const SEAT_ENV_VARS = Object.freeze(['ORCA_TERMINAL_HANDLE', 'ORCA_PANE_KEY', 'ORCA_TAB_ID', 'ORCA_WORKTREE_ID', 'STARCI_ROLE', 'STARCI_GUARD_FILE', 'STARCI_CALLER']);
+
+/** `parent` (the caller's env) without the seat identity: a child that is not the seat's own agent tool call runs unbound. Pure — the caller names the env; the base tier never reads process.env itself (RT_BASE_IMPURE). */
+export function withoutSeatEnv(parent) {
+  const env = { ...parent };
+  for (const key of Object.keys(env)) if (SEAT_ENV_VARS.includes(key) || key.startsWith('ORCA_AGENT_')) delete env[key];
+  return env;
+}
+
+/** `parent` without the guard-shim directory on PATH (any casing of the PATH key, the one <home>/.starci/bin entry wherever it sits). Pure — the caller names the env; `home`/`platform` are injectable seams. */
+export function withoutSeatShim(parent, { home = os.homedir(), platform = process.platform } = {}) {
+  const env = { ...parent };
+  const key = Object.keys(env).find((name) => name.toLowerCase() === 'path');
+  if (!key) return env;
+  const shim = path.resolve(path.join(home, '.starci', 'bin'));
+  const resolved = (entry) => path.resolve(String(entry).replace(/^"(.*)"$/, '$1'));
+  const same = (entry) => platform === 'win32' ? resolved(entry).toLowerCase() === shim.toLowerCase() : resolved(entry) === shim;
+  const delimiter = platform === 'win32' ? ';' : ':';
+  env[key] = String(env[key]).split(delimiter).filter((entry) => entry && !same(entry)).join(delimiter);
+  return env;
+}

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

@@ -56,6 +56,45 @@ const ASSIGNED_UNQUOTED = new RegExp(
   SECRET_NAME + String.raw`(?!['"\`]|env\()([A-Za-z0-9_+=-]{12,})(?![A-Za-z0-9_+=.(\[-])`,
 );
 
+const SQL_ROLE_HEAD = /^\s*(?:CREATE|ALTER)\s+(?:ROLE|USER)\b/i;
+const SQL_STATEMENT = /[^;\r\n]+/g;
+const SQL_PASSWORD_WORD = /\bPASSWORD\s+/gi;
+const PSQL_PASSWORD_REFERENCE = /:(?:'[A-Za-z_]\w*'|"[A-Za-z_]\w*")/y;
+const SQL_PASSWORD_QUOTED = /'([^'\r\n]{12,})'/y;
+const ASSIGNED_PLACEHOLDER = /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i;
+const SQL_PASSWORD_RULE = { name: 'assigned-secret' };
+
+/** Read only password tokens in role statements; sticky value readers never retry at later character positions. */
+function sqlPasswordParts(file, text) {
+  const references = [], literals = [];
+  if (!/\.(?:sql|sh)(?:\.tpl)?$/i.test(file ?? '')) return { references, literals };
+  for (const statement of text.matchAll(SQL_STATEMENT)) {
+    if (!SQL_ROLE_HEAD.test(statement[0])) continue;
+    for (const keyword of statement[0].matchAll(SQL_PASSWORD_WORD)) {
+      const start = statement.index + keyword.index + keyword[0].length;
+      PSQL_PASSWORD_REFERENCE.lastIndex = start;
+      SQL_PASSWORD_QUOTED.lastIndex = start;
+      const reference = PSQL_PASSWORD_REFERENCE.exec(text);
+      const literal = SQL_PASSWORD_QUOTED.exec(text);
+      if (reference) references.push([start, start + reference[0].length]);
+      if (literal) literals.push(literal[1]);
+    }
+  }
+  return { references, literals };
+}
+
+/** Psql variable references retain their positions while the assignment heuristic sees no literal value there. */
+function maskedReferences(text, references) {
+  const parts = [];
+  let cursor = 0;
+  for (const [start, end] of references) {
+    parts.push(text.slice(cursor, start), ' '.repeat(end - start));
+    cursor = end;
+  }
+  parts.push(text.slice(cursor));
+  return parts.join('');
+}
+
 const NAME_WORD = (word, tail) => new RegExp(`^${NAME_REST}${SEGMENT_BEFORE}(?:${word})${tail}`);
 const SECRET_NAME_TEST = NAME_WORD(SECRET_WORD, String.raw`(?:[_\-.]|[A-Z]|[^A-Za-z0-9_$]|$)`);
 const BENIGN_TAIL_TEST = NAME_WORD(BENIGN_WORD, '$');
@@ -84,27 +123,37 @@ export const SECRET_PATTERNS = [
   // A spec file's keyword-assigned values are test inputs (a spec's sign-in
   // form password and a mocked accessToken once refused a push): the heuristic skips spec files too.
   // A SCREAMING_SNAKE quoted value in source is a public code (an enum member whose value is an upper-case code), not a credential.
-  { name: 'assigned-secret', re: ASSIGNED_QUOTED, sourceCode: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+  { name: 'assigned-secret', re: ASSIGNED_QUOTED, sourceCode: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/, placeholder: ASSIGNED_PLACEHOLDER,
     skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$/ },
   // An unquoted value in TypeScript or JavaScript source is an identifier or a type (`token: InjectionToken`,
   // `MODULE_OPTIONS_TOKEN: DATABASE_OPTIONS_TOKEN`), never a literal; the unquoted form is the dotenv, compose and toml shape.
-  { name: 'assigned-secret', re: ASSIGNED_UNQUOTED, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+  { name: 'assigned-secret', re: ASSIGNED_UNQUOTED, placeholder: ASSIGNED_PLACEHOLDER,
     skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$|\.[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 = [];
+/** Matched pattern metadata stays private; callers receive pattern names, never credential values. */
+function matchingSecretPatterns(file, text) {
+  const matches = [];
+  const sql = sqlPasswordParts(file, text);
+  const assignments = maskedReferences(text, sql.references);
   for (const rule of SECRET_PATTERNS) {
     if (rule.skipFile?.test(file ?? '')) continue;
-    const hit = rule.re.exec(text);
-    if (hit && rule.sourceCode?.test(hit[1] ?? '') && /\.[cm]?[jt]sx?$/.test(file ?? '')) continue;
-    if (hit && !rule.placeholder?.test(hit[1] ?? '')) names.push(rule.name);
+    const hit = rule.re.exec(rule.name === 'assigned-secret' ? assignments : text);
+    if (hit && !rule.placeholder?.test(hit[1] ?? '')) matches.push({ rule, value: hit[1] ?? '' });
   }
-  return names;
+  for (const value of sql.literals) if (!ASSIGNED_PLACEHOLDER.test(value)) matches.push({ rule: SQL_PASSWORD_RULE, value });
+  return matches;
 }
 
+/** The strict secret-shape judgement used by Work custody, including uppercase keyword-assigned credentials. */
+export const secretPatternHits = (file, text) => matchingSecretPatterns(file, text).map(({ rule }) => rule.name);
+
+/** The source judgement also admits public SCREAMING_SNAKE codes; every provider shape remains refused. */
+export const secretHits = (file, text) => matchingSecretPatterns(file, text)
+  .filter(({ rule, value }) => !(rule.sourceCode?.test(value) && /\.[cm]?[jt]sx?$/.test(file ?? '')))
+  .map(({ rule }) => rule.name);
+
 const BADGE_BEGIN = '<!-- >>> starci app sync (managed block; do not edit) >>> -->';
 const BADGE_END = '<!-- <<< starci app sync <<< -->';
 

package/runtime/scripts/lib/shell-source.mjs

@@ -0,0 +1,4 @@
+// Shell scanners share the same projection: whole-line comments do not execute.
+
+/** Keep executable lines and line breaks while excluding whole-line shell comments. */
+export const shellCommandSource = (text) => String(text ?? '').split(/\r?\n/).filter((line) => !/^\s*#/.test(line)).join('\n');

package/runtime/scripts/lib/source-phrases.mjs

@@ -0,0 +1,34 @@
+// source-phrases.mjs - the Vietnamese phrase lists runtime source matches against owner or product text are DATA,
+// not source: they live in modules/goal/source-phrases.yaml (its leaf keys are declared Vietnamese fields,
+// scripts/lib/language.mjs DECLARED_VIETNAMESE_FIELDS - like the archetypes.yaml phrase lists) so the matchers'
+// source stays English. A list is plain words or regex alternatives, per its comment in the lexicon.
+//
+//   phrasesOf('owed.ownerWord')   -> the list as written (['<owner word>', ...])
+//   altOf('owed.ownerWord')       -> the regex alternation 'a|b|c'; '(?!)' - never matches - when absent
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+const SOURCE_PHRASES_FILE = 'modules/goal/source-phrases.yaml';
+
+const cache = new Map();
+
+/** The lexicon's `phrases` map ({<group>: {<list>: string[]}}), cached per root. */
+function sourcePhrases(root = skillRoot) {
+  if (!cache.has(root)) {
+    let doc = null;
+    try { doc = parseYaml(fs.readFileSync(path.join(root, ...SOURCE_PHRASES_FILE.split('/')), 'utf8')); } catch { doc = null; }
+    cache.set(root, doc?.phrases && typeof doc.phrases === 'object' ? doc.phrases : {});
+  }
+  return cache.get(root);
+}
+
+/** The phrase list `dotKey` (`<group>.<list>`) of `root`, [] when absent. */
+export function phrasesOf(dotKey, root = skillRoot) {
+  const value = dotKey.split('.').reduce((v, k) => (v && typeof v === 'object' ? v[k] : undefined), sourcePhrases(root));
+  return (Array.isArray(value) ? value : []).map(String);
+}
+
+/** The regex alternation of `dotKey` ('a|b|c'); '(?!)' - a never-match - when the list is empty. */
+export const altOf = (dotKey, root = skillRoot) => phrasesOf(dotKey, root).join('|') || '(?!)';

package/runtime/scripts/lib/sqlite.mjs

@@ -0,0 +1,21 @@
+// sqlite.mjs — the small better-sqlite3 probes the ledger and machine stores share. The handle is the
+// caller's; these helpers prepare statements on it and return its own result shapes.
+
+/** Whether the database holds a table `name` (`views: true` also counts views). */
+export const hasTable = (db, name, { views = false } = {}) =>
+  Boolean(db.prepare(`SELECT 1 FROM sqlite_master WHERE type${views ? " IN ('table','view')" : "='table'"} AND name=?`).get(name));
+
+/**
+ * INSERT the [column, value] `pairs` into `table` (`orIgnore` spells OR IGNORE); returns the statement's
+ * run() result. Column naming and value encoding are the caller's — this is only the statement shape.
+ */
+const insertPairs = (db, table, pairs, { orIgnore = false } = {}) =>
+  db.prepare(`INSERT ${orIgnore ? 'OR IGNORE ' : ''}INTO ${table}(${pairs.map((p) => p[0]).join(',')}) VALUES(${pairs.map(() => '?').join(',')})`)
+    .run(...pairs.map((p) => p[1]));
+
+/**
+ * The per-store `insertRow`: binds the caller's own [column, value] mapper (`cellsOf` — where the store's
+ * column validation and value encoding live) to an insertPairs statement.
+ */
+export const insertRowWith = (cellsOf) => (db, table, row, { orIgnore = false } = {}) =>
+  insertPairs(db, table, cellsOf(db, table, row), { orIgnore });

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

@@ -5,7 +5,8 @@ import { repositoryOf } from './stack-services.mjs';
 
 const PINNED_IMAGE = /@sha256:[a-f0-9]{64}$/i;
 const VERSIONED_SECRET = /-v[1-9]\d*$/;
-const BACKING_IMAGE_SQL_AND_CACHE = 'postgres(?:ql)?|postgresql-repmgr|redis(?:-stack(?:-server)?)?|mysql(?:-server)?|mongo(?:db)?|mongodb-community-server';
+// R276 (scripts/hfs/rules/stacks-lite-backing.mjs) judges declared Redis and refuses full-only backing services in lite.
+const BACKING_IMAGE_SQL_AND_CACHE = 'postgres(?:ql)?|postgresql-repmgr|mysql(?:-server)?|mongo(?:db)?|mongodb-community-server';
 const BACKING_IMAGE_BROKERS_AND_OTHERS = '(?:cp-)?kafka(?:-native)?|keycloak|minio|rabbitmq';
 const BACKING_IMAGE = new RegExp(`^(?:${BACKING_IMAGE_SQL_AND_CACHE}|${BACKING_IMAGE_BROKERS_AND_OTHERS})$`, 'i');
 const mapping = value => plain(value) ? value : {};

package/runtime/scripts/lib/tar-files.mjs

@@ -0,0 +1,39 @@
+// tar-files.mjs - the regular files of a gzipped tar (an npm tarball), read in memory: {path -> Buffer}. Pure: no disk, no
+// child process. Only what `npm pack` writes is understood (ustar headers, a `path` pax record and the ustar prefix
+// honoured, other pax records skipped); a link or a device entry is ignored.
+import zlib from 'node:zlib';
+
+const BLOCK = 512;
+const text = (buf, from, len) => {
+  const value = buf.toString('utf8', from, from + len);
+  const nul = value.indexOf('\0');
+  return nul < 0 ? value : value.slice(0, nul);
+};
+const octal = (buf, from, len) => Number.parseInt(text(buf, from, len).trim() || '0', 8);
+
+/** Map<string, Buffer> of the regular files in `tgz` (a Buffer). Throws on a truncated or corrupt archive. */
+export function tarFiles(tgz) {
+  const tar = zlib.gunzipSync(tgz);
+  const files = new Map();
+  let at = 0;
+  let paxPath = null;
+  while (at + BLOCK <= tar.length) {
+    const header = tar.subarray(at, at + BLOCK);
+    if (header.every((b) => b === 0)) break;
+    const size = octal(header, 124, 12);
+    const type = String.fromCodePoint(header[156] || 48);
+    const prefix = text(header, 345, 155);
+    const name = paxPath ?? (prefix ? `${prefix}/${text(header, 0, 100)}` : text(header, 0, 100));
+    const body = tar.subarray(at + BLOCK, at + BLOCK + size);
+    if (body.length < size) throw new Error(`tar entry ${name} is truncated`);
+    at += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+    if (type === 'x') {
+      const record = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(body.toString('utf8'));
+      paxPath = record ? record[1] : null;
+      continue;
+    }
+    paxPath = null;
+    if (type === '0') files.set(name, Buffer.from(body));
+  }
+  return files;
+}

package/runtime/scripts/lib/ts-analysis.mjs

@@ -25,3 +25,13 @@ export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiterals
 
 /** Catalog values unwrap parentheses, `as`, and `satisfies`, preserving assertions and non-null nodes. */
 export const unwrapCatalogExpression = (ts, node) => unwrapExpression(ts, node, { typeAssertions: false, nonNullExpressions: false });
+
+/** Bind this file in isolation: the compiler resolves lexical names, but imports and library files are never loaded. */
+export function lexicalChecker(ts, source) {
+  const options = { noLib: true, noResolve: true, allowJs: true };
+  const host = ts.createCompilerHost(options);
+  host.getSourceFile = (file) => file === source.fileName ? source : undefined;
+  host.fileExists = () => false;
+  host.readFile = () => undefined;
+  return ts.createProgram([source.fileName], options, host).getTypeChecker();
+}

package/runtime/scripts/lib/worktree-exclude.mjs

@@ -0,0 +1,35 @@
+// worktree-exclude.mjs — where a product repository keeps the runtime's own git worktrees (scratch trees made by
+// scripts/machine/worktree-git.mjs createScratchWorktree), and the one test every scanner uses to stay out of them.
+//
+// Layout inside a product repository:
+//   <repo>/.starciwork/worktrees/<name>    one runtime scratch tree
+// The directory is git-excluded (.git/info/exclude), so `git status`,
+// `git ls-files --others --exclude-standard` and sonar never see it; every scanner that walks the filesystem
+// (canon-scan's eslint, starci app lint, the architecture walkers, input digests, proof-integrity, Work readers)
+// skips it with isWorktreesPath / WORKTREES_IGNORE_GLOBS, or it would lint and hash every sibling worktree.
+import path from 'node:path';
+import { posixPath } from './path-key.mjs';
+
+/** The worktrees directory, relative to the product repository root (posix). */
+export const WORKTREES_REL = '.starciwork/worktrees';
+/** Glob patterns an ESLint/tsc-style ignore list takes. */
+export const WORKTREES_IGNORE_GLOBS = Object.freeze([`${WORKTREES_REL}/**`, `**/${WORKTREES_REL}/**`]);
+
+const posix = posixPath;
+
+/**
+ * True when `rel` (a path relative to a repository root, either slash) is the worktrees directory or inside it.
+ * With `root`, `rel` may be absolute: it is made relative to root first.
+ */
+export function isWorktreesPath(rel, { root = null } = {}) {
+  let p = posix(rel);
+  if (root && path.isAbsolute(String(rel))) p = posix(path.relative(root, String(rel)));
+  while (p.endsWith('/')) p = p.slice(0, -1);
+  return p === WORKTREES_REL || p.startsWith(`${WORKTREES_REL}/`) || p.includes(`/${WORKTREES_REL}/`) || p.endsWith(`/${WORKTREES_REL}`);
+}
+
+/**
+ * True when `abs` is a worktrees dir (or inside one) BELOW the scan root `root`. Always relative to the root a walker
+ * started from: a walker whose root is itself a runtime tree (<repo>/.starciwork/worktrees/<name>) must still walk it.
+ */
+export const underWorktrees = (root, abs) => isWorktreesPath(path.relative(path.resolve(String(root)), path.resolve(String(abs))));

package/runtime/scripts/lib/worktree-record.mjs

@@ -0,0 +1,14 @@
+// worktree-record.mjs — the workflow-worktree registry row a checkpoint or a gate needs.
+import fs from 'node:fs';
+
+/**
+ * `rec` must be `workflowId`'s live worktree row: present in the registry, its path on disk, a branch
+ * recorded. Throws {code: 'workflow-worktree-missing'} otherwise; returns `rec`.
+ */
+export function requireWorktreeRecord(rec, workflowId) {
+  const missing = (message) => { throw Object.assign(new Error(message), { code: 'workflow-worktree-missing' }); };
+  if (!rec) missing(`workflow ${workflowId} has no workflow worktree in the registry`);
+  if (!rec.path || !fs.existsSync(rec.path)) missing(`the worktree of workflow ${workflowId} (${rec.path ?? '-'}) is gone`);
+  if (!rec.branch) missing(`the registry records no branch for the worktree of workflow ${workflowId} (${rec.path})`);
+  return rec;
+}

package/runtime/scripts/machine/artifact-hold.mjs

@@ -0,0 +1,52 @@
+// artifact-hold.mjs — the retention exemption for the typed-log ledger. A registered ledger's runtime.sqlite
+// (it holds the typed logs, scripts/kernel/typed-logs.mjs) and a tree holding it are never removed by housekeeping, whatever the
+// workflow's phase (running, finished, archived). Every runtime delete of a tree passes artifactHoldReason as
+// scripts/api/fs/safe-remove.mjs safeRemove's `hold` (a call without one is refused), and every housekeeping unlink asks
+// artifactHoldOf first.
+// Proofs, artifacts and logs are deleted ONLY by the owner-approved workflow purge (scripts/work/purge-workflow.mjs:
+// archive to a verified ZIP, then delete the finished workflow as a unit), never here.
+//
+// The ledgers are the ones the machine registry enrols (machine.sqlite `ledgers`).
+import fs from 'node:fs';
+import path from 'node:path';
+import { localProjectsRoot, machineFileFor, readMachine } from '../../engine/db/machine.mjs';
+import { pathKey, sameOrUnder } from '../lib/path-key.mjs';
+
+const REGISTRY_TTL_MS = 30000;
+const norm = pathKey;
+let cache = { file: null, at: 0, repos: [] };
+
+/** The repositories whose ledgers the registry enrols: [{repo, ledger}], cached briefly per registry file; null when the registry cannot be read. */
+function registeredRepos({ env = process.env, now = Date.now() } = {}) {
+  const file = machineFileFor(env);
+  if (cache.file === file && now - cache.at < REGISTRY_TTL_MS) return cache.repos;
+  const repos = fs.existsSync(file) ? readMachine((m) => m.listLedgers().map((l) => ({ ledger: l.file, repo: l.repoRoot })), null, { file, env }) : [];
+  cache = { file, at: now, repos };
+  return repos;
+}
+
+/**
+ * Null when removing `target` touches no held file; else {ledger, repo, paths, count}.
+ * Held: a registered ledger file at or under `target`. An unreadable registry holds every path in or
+ * holding the projects root of the host-state directory (fail closed).
+ */
+export function artifactHoldOf(target, { env = process.env, repos = registeredRepos({ env }) } = {}) {
+  const t = norm(target);
+  if (repos === null) {
+    const projects = norm(localProjectsRoot(env));
+    return sameOrUnder(t, projects) || sameOrUnder(projects, t) ? { ledger: machineFileFor(env), repo: null, paths: [], count: null, error: 'the machine registry cannot be read' } : null;
+  }
+  for (const { ledger, repo } of repos) {
+    // The typed logs (scripts/kernel/typed-logs.mjs: the ledger's logs table) are append-only history: never swept.
+    if (ledger && sameOrUnder(norm(ledger), t) && fs.existsSync(ledger)) return { ledger, repo, paths: [path.basename(ledger)], count: 1 };
+  }
+  return null;
+}
+
+/** artifactHoldOf as one refusal line, or null. */
+export const artifactHoldReason = (target, options) => {
+  const hold = artifactHoldOf(target, options);
+  if (!hold) return null;
+  return hold.error ? `${hold.error} (${hold.ledger})`
+    : `${hold.count} ledger file(s) of ${hold.ledger} (${hold.paths.join(', ')})`;
+};

package/runtime/scripts/machine/ask-receipts.mjs

@@ -0,0 +1,113 @@
+// ask-receipts.mjs — where the answer to an ask is kept (docs/ledger-db.md §§5–6): serve-ask answers →
+// decisions + blobs; never a file under .starciwork/kernel-evidence.
+//
+// An answer (owner form, Telegram reply, config auto-accept, autopilot) is one starci/ask-answer@1 receipt. It is put
+// in the blob store (redacted), indexed as a kernel artifact of the attempt that asked - job_artifacts name
+// asks/<dispatchId>/answer-<ms>.json, origin kernel - and recorded as one `decisions` row (decider owner | the
+// answering actor, subject the attempt, result {receiptSha256, artifactId, ...}). The receipt's file is the blob
+// file (receiptPath, read-only), and a Work record cites it as `blob:<sha256>` (or by its decision id), never by a
+// repository path.
+import fs from 'node:fs';
+import path from 'node:path';
+import { recordDecision } from '../../engine/db/ledger.mjs';
+import { sha256 } from '../../engine/digest.mjs';
+import { artifactRoot, blobPath } from '../../engine/db/blob.mjs';
+import { stageBlob, putArtifact } from './evidence-store.mjs';
+import { slash } from '../lib/path-key.mjs';
+
+const RECEIPT_PREFIX = 'asks/';
+const receiptNameOf = (dispatchId, at) => `${RECEIPT_PREFIX}${dispatchId}/answer-${at}.json`;
+const BLOB_REF = /^blob:([a-f0-9]{64})$/;
+
+/** The receipt as a staged blob (outside any transaction). */
+export const stageReceipt = (receipt) => stageBlob(Buffer.from(JSON.stringify(receipt, null, 2)), { mediaType: 'application/json' });
+
+/**
+ * Inside the caller's transaction: index a staged receipt as the asking attempt's kernel artifact and record the
+ * answer as a decisions row. Returns {receiptPath, receiptSha, receiptRef, artifactId, decisionId}.
+ */
+function fileAskReceipt(db, { workflowId, dispatchId, receipt, blob, at = Date.now() }) {
+  const report = db.prepare('SELECT attempt_id,job_id FROM reports WHERE workflow_id=? AND dispatch_id=?').get(workflowId, dispatchId) ?? null;
+  const attempt = report ? db.prepare('SELECT attempt_id,job_id,op_id FROM op_attempts WHERE attempt_id=?').get(report.attempt_id) : null;
+  let name = receiptNameOf(dispatchId, at);
+  let n = at + 1;
+  while (db.prepare('SELECT 1 FROM job_artifacts WHERE workflow_id=? AND name=?').get(workflowId, name)) { name = receiptNameOf(dispatchId, n); n += 1; }
+  const { artifactId } = putArtifact(db, { workflowId, attemptId: attempt?.attempt_id ?? null, jobId: attempt?.job_id ?? report?.job_id ?? null, opId: attempt?.op_id ?? null,
+    role: 'other', kind: 'report', name, blob, origin: 'kernel', now: at });
+  const answeredBy = String(receipt.answeredBy ?? 'unknown');
+  const option = receipt.option ?? (receipt.optionIndex != null ? `option ${Number(receipt.optionIndex) + 1}` : 'answered');
+  const decisionId = recordDecision(db, { workflowId, decider: answeredBy === 'owner' ? 'owner' : answeredBy, subjectType: attempt ? 'attempt' : null,
+    subjectId: attempt ? String(attempt.attempt_id) : null, choice: String(option), rationale: typeof receipt.note === 'string' ? receipt.note.slice(0, 2000) : null,
+    result: { kind: 'ask-answer', dispatchId, answeredBy, optionIndex: receipt.optionIndex ?? null, receiptSha256: blob.sha, artifactId }, decidedAt: at });
+  return { receiptPath: blob.fileUri, receiptSha: blob.sha, receiptRef: `blob:${blob.sha}`, artifactId, decisionId };
+}
+
+
+/** Atomically accept one answer with its receipt, decision and terminal lifecycle event. */
+export function commitAskAnswer(ledger, { workflowId, dispatchId, receipt, at = Date.now(), payload = {}, events = [], blob: staged = null }) {
+  const blob = staged ?? stageReceipt(receipt);
+  const answerDigest = sha256(JSON.stringify({ ...receipt, at: null }));
+  return ledger.transaction(db => {
+    const latest = db.prepare(`SELECT kind,payload_json FROM events WHERE workflow_id=?
+      AND kind IN ('ask-answered','ask-superseded')
+      AND json_extract(payload_json,'$.dispatchId')=? ORDER BY seq DESC LIMIT 1`).get(workflowId, dispatchId);
+    if (latest?.kind === 'ask-answered' || latest?.kind === 'ask-superseded') {
+      const prior = JSON.parse(latest.payload_json);
+      return prior.answerDigest === answerDigest
+        ? { accepted: true, replayed: true, ...prior }
+        : { accepted: false, why: latest.kind === 'ask-answered' ? 'already-answered' : 'retired' };
+    }
+    const filed = fileAskReceipt(db, { workflowId, dispatchId, receipt, blob, at });
+    const answer = { dispatchId, receiptPath: filed.receiptPath, receiptSha: filed.receiptSha, decisionId: filed.decisionId,
+      answeredBy: receipt.answeredBy, optionIndex: receipt.optionIndex ?? null,
+      custodyWritten: receipt.custodyWritten ?? [], envWritten: receipt.envWritten ?? [], pointersWritten: receipt.pointersWritten ?? [], errors: receipt.errors ?? [],
+      ...payload, answerDigest };
+    ledger.appendEvent({ workflowId, entityType: 'report', entityId: dispatchId, kind: 'ask-answered', payload: answer });
+    for (const event of events) ledger.appendEvent({ workflowId, entityType: 'report', entityId: dispatchId, ...event,
+      payload: { ...event.payload, receiptPath: filed.receiptPath } });
+    return { accepted: true, replayed: false, ...filed };
+  });
+}
+
+/** True when `file` is a blob in the store (a receipt's file lives there). */
+const isBlobFile = (file) => {
+  const rel = path.relative(artifactRoot(), path.resolve(file));
+  return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+
+/** The file a receipt reference names: `blob:<sha256>`, a blob file, or a path (resolved against `base`). */
+export function receiptFileOf(ref, { base = process.cwd() } = {}) {
+  if (typeof ref !== 'string' || !ref.trim()) return null;
+  const m = BLOB_REF.exec(ref.trim());
+  if (m) return blobPath(m[1]);
+  const abs = path.resolve(base, ref);
+  return fs.existsSync(abs) ? abs : null;
+}
+
+/** How a Work record cites a receipt file: `blob:<sha256>` for a blob, else the path relative to `repoRoot`. */
+export const receiptRefOf = (file, repoRoot) => (isBlobFile(file) ? `blob:${path.basename(file)}` : path.relative(repoRoot, file).replaceAll('\\', '/'));
+
+/**
+ * The prelude of every `apply` that settles from a serve-ask answer (scripts/work/draw-review.mjs,
+ * scripts/work/brand-direction.mjs): resolve the receipt ref (a `blob:<sha256>` the store kept, or a path inside
+ * `repoRoot`), refuse a file outside the repository, and parse it as the `schema` receipt. Returns
+ * {receipt, receiptAbs, receiptRel} - receiptRel is how the record cites it.
+ */
+export function readAnswerReceipt(receiptFile, { repoRoot, base = process.cwd(), schema = 'starci/ask-answer@1' } = {}) {
+  // The receipt is the blob serve-ask stored (receiptPath, or `blob:<sha256>`); a Work record cites it as
+  // blob:<sha256>. A path inside the repository is still read (an example tree's own receipt).
+  const receiptAbs = receiptFileOf(String(receiptFile), { base }) ?? path.resolve(String(receiptFile));
+  const receiptRel = receiptRefOf(receiptAbs, repoRoot);
+  if (!isBlobFile(receiptAbs) && (receiptRel.startsWith('../') || path.isAbsolute(receiptRel))) throw new Error(`receipt ${slash(receiptFile)} is neither a stored answer (blob:<sha256>, the receiptPath serve-ask returned) nor a file inside the repository ${slash(repoRoot)}`);
+  let receipt;
+  try { receipt = JSON.parse(fs.readFileSync(receiptAbs, 'utf8')); } catch (error) { throw new Error(`receipt ${slash(receiptFile)} is unreadable: ${error.message}`); }
+  if (receipt?.schema !== schema) throw new Error(`${slash(receiptFile)} is ${receipt?.schema ?? 'not a receipt'}, not ${schema}`);
+  return { receipt, receiptAbs, receiptRel };
+}
+
+/** Every receipt answering `dispatchId` in a ledger, newest first: [{file, receipt, name}]. */
+export function receiptsAnswering(db, dispatchId) {
+  return db.prepare(`SELECT a.name,a.sha256 FROM job_artifacts a WHERE a.origin='kernel' AND a.name LIKE ? ORDER BY a.artifact_id DESC`).all(`${RECEIPT_PREFIX}${dispatchId}/answer-%`)
+    .map((r) => { const file = blobPath(r.sha256); let receipt = null; try { receipt = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { receipt = null; } return { file, receipt, name: r.name }; })
+    .filter((r) => r.file && r.receipt);
+}