@starci/hfs 4.7.32 → 4.7.34

package/runtime/scripts/machine/lock-recovery.mjs

@@ -0,0 +1,55 @@
+// lock-recovery.mjs — the compositions around the ONE stale `.git/index.lock` recovery (scripts/api/git/index-lock.mjs
+// indexLock): the git-process probe over the host's process table (scripts/api/process/process-list.mjs), the Supervisor
+// audit event a removal records, and the command guard's pre-flight (scripts/guards/command-guard.mjs). The housekeeping
+// area `gitlocks` (scripts/housekeeping/hk-git-locks.mjs) uses the probe and the recorder too.
+import path from 'node:path';
+import { checkoutOf, gitDirOf, isGitImage, lockStat } from '../lib/git-dir.mjs';
+import { indexLock } from '../api/git/index-lock.mjs';
+import { processList } from '../api/process/process-list.mjs';
+import { isSpecRun } from '../lib/env.mjs';
+
+const LOCK_EVENT = 'git-index-lock-removed';
+
+/** Git-family processes on this host: [{pid, name, commandLine}], or null when the probe failed. A spec run (NODE_TEST_CONTEXT) never reads the host process table. */
+export function listGitProcesses({ platform = process.platform, run, env = process.env } = {}) {
+  if (isSpecRun(env)) return null;
+  const rows = processList({ where: "Name LIKE 'git%'", run, platform, timeoutMs: 30000 });
+  return rows ? rows.map((p) => ({ pid: p.pid, name: String(p.name ?? ''), commandLine: p.cmd })).filter((p) => isGitImage(p.name)) : null;
+}
+
+/** `record` for api/git/index-lock.mjs indexLock: one Supervisor audit event (machine.sqlite sup_events) per removal, naming who removed it. */
+export async function supervisorLockRecorder({ env = process.env, by, jobId = null, workflowId = null } = {}) {
+  const { withSupervisor, supervisorEvent } = await import('./home.mjs');
+  return (result) => withSupervisor((m) => supervisorEvent(m, { entityType: 'repo', entityId: result.repo, kind: LOCK_EVENT,
+    payload: { lock: result.lock, ageMs: Math.round(result.ageMs), bytes: result.bytes, mtime: result.mtime, by, jobId, workflowId } }), { env });
+}
+
+/**
+ * The command guard's git pre-flight (scripts/guards/command-guard.mjs): when the checkout `cwd` is in holds an index
+ * lock older than the declared window, try the recovery once and say what happened on stderr. Costs one stat when no
+ * lock stands. Never throws: the command runs either way.
+ */
+export async function preflightIndexLock({ cwd = process.cwd(), guard = null, env = process.env, say = () => {}, now = Date.now(), list = listGitProcesses } = {}) {
+  try {
+    const repo = checkoutOf(cwd);
+    const gitDir = repo ? gitDirOf(repo) : null;
+    const st = gitDir ? lockStat(path.join(gitDir, 'index.lock')) : null;
+    if (!st) return null;
+    const { allocationMs } = await import('../../engine/config.mjs');
+    const staleMs = allocationMs('housekeeping.gitIndexLockStaleMs');
+    if (now - st.mtimeMs < staleMs) return null;
+    const record = await supervisorLockRecorder({ env, by: 'command-guard', jobId: guard?.jobId ?? null, workflowId: guard?.workflowId ?? null });
+    const result = indexLock({ repo, staleMs, now, list, record });
+    const age = `${Math.round((result.ageMs ?? 0) / 60000)} min`;
+    if (result.state === 'removed') say(`starci guard: removed a stale ${result.lock} (${age} old, no git process on this repository); recorded as ${LOCK_EVENT}.`);
+    else if (result.state === 'held') say(`starci guard: ${result.lock} is ${age} old but a git process may still hold it (${result.holders.map((h) => h.pid).join(', ')}); left in place - retry shortly, never delete it by hand.`);
+    else if (result.state !== 'fresh' && result.state !== 'absent') {
+      const error = result.error ? `: ${result.error}` : '';
+      say(`starci guard: ${result.lock} is ${age} old and was left in place (${result.state}${error}).`);
+    }
+    return result;
+  } catch (error) {
+    say(`starci guard: index-lock check error (${error?.message ?? error}); running git anyway`);
+    return null;
+  }
+}

package/runtime/scripts/machine/roles-contract.mjs

@@ -0,0 +1,90 @@
+// roles-contract.mjs — reads the one roles contract (modules/kernel/roles.yaml) and renders a role's block: the Markdown a surface
+// carries between its markers, and the compact lines the op prompt prints at launch. The roles-contract self-check compares
+// every surface with this rendering.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const ROLES_FILE = 'modules/kernel/roles.yaml';
+
+/** The roles contract document of the tree at `root`. */
+export const rolesContract = (root = ROOT) => parseYaml(fs.readFileSync(path.join(root, ROLES_FILE), 'utf8'));
+
+export const markerOf = (id) => ({ begin: `<!-- roles:begin ${id} -->`, end: `<!-- roles:end ${id} -->` });
+
+const bullets = (label, items) => (items?.length ? [`- ${label}:`, ...items.map((item) => `  - ${item}`)] : []);
+const nameOf = (doc, id) => (id === 'runtime' ? 'the runtime' : doc.roles.find((role) => role.id === id)?.label ?? id);
+
+/** The lines that state who a role reports to, who oversees it and what it owns. */
+function chainLines(doc, role) {
+  const up = role.reportsTo ? `${nameOf(doc, role.reportsTo)} (${role.reportsUpWhen})` : 'no one';
+  return [`- Owns: ${role.owns}. Decides alone: ${role.decidesAlone}.`,
+    `- Reports to: ${up}. Overseen by: ${role.overseenBy.map((id) => nameOf(doc, id)).join(', ') || 'no one'}.`,
+    `- Measure: ${role.measure}.`];
+}
+
+/** The token budget line of a role that declares one. */
+function budgetLines(role) {
+  const b = role.tokenBudget;
+  const wake = role.wakeBudget;
+  if (b) return [`- Token budget (${b.status}): ${b.perAttempt.default} per ${b.unit ?? 'attempt'}; over it, ${b.onExceed}.`];
+  if (wake) {
+    const boot = wake.perBoot ? `, ${wake.perBoot.turns} turns and ${wake.perBoot.tokens} tokens for its boot (the contract files and the rev-ack manifest)` : '';
+    return [`- Wake budget (${wake.status}): ${wake.perWake.turns} turns and ${wake.perWake.tokens} tokens per wake${boot}; over it, ${wake.onExceed}.`];
+  }
+  return role.noBudget ? [`- No budget: ${role.noBudget}.`] : [];
+}
+
+/** The line that states how a role learns that the runtime tree changed (its revisionAck declaration). */
+function revisionLines(role) {
+  const decl = role.revisionAck;
+  if (!decl) return [];
+  if (decl.noAck) return [`- Runtime changes: ${decl.noAck}.`];
+  if (decl.admission) return [`- Runtime changes: ${decl.reason}.`];
+  return [`- Runtime changes (modules/kernel/revision-scope.yaml): woken once with exactly the changed files that concern it, it reads them and attests with ${decl.verb}; a change that concerns it nothing costs it nothing; it is replaced by a fresh seat, at its next yield, only when a rule of its contract was removed or reversed or its boot prompt changed.`];
+}
+
+/** The guard binding, the happy errors and the bug surface of a role that declares them (the owner's two classes of error). */
+function standardLines(role) {
+  const unbound = role.noSeat ? [`- Guard: none by design; ${role.noSeatReason}.`] : [];
+  const guard = role.guard ? [`- Guard: its terminals are bound as the "${role.guard.role}" role of modules/kernel/command-policy.yaml.`] : unbound;
+  const happy = role.happyErrors?.map((error) => `${error.id} (policy row ${error.row}): ${error.what}`);
+  const bugs = role.bugSurface?.map((entry) => `${entry.bug}: ${entry.signal}`);
+  return [...guard, ...bullets('Happy errors it handles (the system working as designed, handled inside the chain through the policy)', happy),
+    ...bullets('A bug in this role (the chain neither fixes nor works around it; Debug removes it with a change to .claude) is detected by', bugs)];
+}
+
+/** The Debug lines that state whom it audits and when it retires. */
+function debugLines(doc, role) {
+  if (!role.oversees) return [];
+  const criteria = role.endCondition.criteria.map((c) => `${c.id}: ${c.rule}`);
+  return [`- Audits: ${role.oversees.map((id) => nameOf(doc, id)).join(', ')}.`, ...bullets('Retires when', criteria)];
+}
+
+/** The Markdown block of one role (without its markers). */
+export function renderRoleBlock(doc, id) {
+  const role = doc.roles.find((entry) => entry.id === id);
+  const lines = [`**${role.label}** (${ROLES_FILE}#${id}): ${role.scope}`, ...bullets('Does', role.does), ...bullets('Must clean up', role.cleanup),
+    ...bullets('Never', role.never), ...chainLines(doc, role), ...budgetLines(role), ...revisionLines(role), ...standardLines(role), ...debugLines(doc, role), `- Principles: ${role.binds.join(' ')} (${ROLES_FILE}, principles).`];
+  return lines.join('\n');
+}
+
+/** The compact lines of a role for a launch prompt. */
+export function renderRoleLines(id, root = ROOT) {
+  const doc = rolesContract(root);
+  const role = doc.roles.find((entry) => entry.id === id);
+  return [`role: ${role.label} (${ROLES_FILE}#${id}) - ${role.scope}`, ...role.never.map((item) => `  never: ${item}`),
+    ...role.cleanup.map((item) => `  clean up: ${item}`), `  reports to: ${nameOf(doc, role.reportsTo)} only`];
+}
+
+/** The text with the role's block replaced between its markers, or appended with markers when it has none. */
+export function withRoleBlock(text, doc, id) {
+  const { begin, end } = markerOf(id);
+  const block = `${begin}\n${renderRoleBlock(doc, id)}\n${end}`;
+  const from = text.indexOf(begin);
+  const to = text.indexOf(end);
+  if (from < 0 || to < from) return `${text.trimEnd()}\n\n${block}\n`;
+  return text.slice(0, from) + block + text.slice(to + end.length);
+}

package/runtime/scripts/machine/runtime-change.mjs

@@ -0,0 +1,20 @@
+// runtime-change.mjs — the typed refusal of a runtime change by the Supervisor. Changing .claude belongs to Debug and the owner's
+// release flow (modules/kernel/roles.yaml chain.runtimeChange); the verbs and the code are read from there, so the command guard,
+// the file-write guard and the CLI dispatcher refuse with one voice.
+import { rolesContract } from './roles-contract.mjs';
+
+export const RUNTIME_CHANGE_CODE = 'RUNTIME_CHANGE_OWNED_BY_DEBUG';
+
+/** The refusal fields {code, reason, remedy} for `words` (the group, verb and subcommand a caller runs), or null when they change nothing. */
+export function runtimeChangeRefusal(words) {
+  const { runtimeChange } = rolesContract().chain;
+  const hit = runtimeChange.verbs.find((verb) => verb.every((word, index) => words[index] === word));
+  if (!hit) return null;
+  return { code: RUNTIME_CHANGE_CODE, reason: `the Supervisor changes no runtime code: starci ${hit.join(' ')} belongs to Debug`, remedy: runtimeChange.use };
+}
+
+/** The refusal fields for a Supervisor write inside the runtime checkout. */
+export function runtimeWriteRefusal() {
+  const { runtimeChange } = rolesContract().chain;
+  return { code: RUNTIME_CHANGE_CODE, reason: 'the Supervisor changes no file of the runtime checkout: .claude belongs to Debug and the owner\'s release flow', remedy: runtimeChange.use };
+}

package/runtime/scripts/machine/workflow-tree.mjs

@@ -0,0 +1,122 @@
+// workflow-tree.mjs - the host registry's view of a workflow's worktree (machine.sqlite worktrees, kind workflow) and the
+// base an op's gate measures against there. Read by the Kernel (scripts/kernel/workflow-worktree.mjs,
+// workflow-checkpoint.mjs) and by scripts/gates/gate.mjs, which finds its workflow from the directory it runs in.
+import fs from 'node:fs';
+import path from 'node:path';
+import { mergeBase } from '../api/git/merge-base.mjs';
+import { diffNames } from '../api/git/diff-names.mjs';
+import { log as gitLog } from '../api/git/log.mjs';
+import { revParse as gitRevParse } from '../api/git/rev-parse.mjs';
+import { withMachine } from '../../engine/db/machine.mjs';
+import { isInside } from '../lib/walk.mjs';
+import { requireWorktreeRecord } from '../lib/worktree-record.mjs';
+
+const SHA = /^[0-9a-f]{40,64}$/;
+const insidePath = (child, parent) => isInside(path.resolve(parent), path.resolve(child));
+const fail = ({ code }, message) => Object.assign(new Error(message), { code });
+const revParse = (cwd, ref) => { const sha = gitRevParse(cwd, ref); return sha && SHA.test(sha) ? sha : null; };
+const mainOf = (ctx) => ctx?.main ?? 'main';
+const envOf = (ctx) => ctx?.env ?? process.env;
+
+/** A registry row of a workflow worktree as a record: {workflowId, orcaWorktreeId, path, branch, checkpoint, repoRoot, ...}, or null. */
+export const workflowRecordOf = (row) => (row ? { workflowId: row.workflow_id, orcaWorktreeId: row.orca_id, path: path.resolve(row.path), branch: row.branch ?? null,
+  checkpoint: row.checkpoint_sha ?? null, repoRoot: row.repo_root, ledgerId: row.ledger_id ?? null, createdAt: row.created_at,
+  releasePending: row.release_pending_at != null } : null);
+
+/** The live workflow worktree of `workflowId`: {workflowId, orcaWorktreeId, path, branch, checkpoint, repoRoot}, or null. */
+export function workflowWorktreeOf(ctx, workflowId) {
+  const env = envOf(ctx);
+  try {
+    return workflowRecordOf(withMachine((m) => m.db.prepare("SELECT * FROM worktrees WHERE kind='workflow' AND workflow_id=? AND orca_id IS NOT NULL AND removed_at IS NULL ORDER BY created_at DESC LIMIT 1").get(workflowId), { env }));
+  } catch (cause) { throw Object.assign(new Error(`the workflow worktree registry is unavailable: ${cause.message}`, { cause }), { code: 'worktree-registry-unavailable' }); }
+}
+
+/**
+ * The live workflow worktree whose directory is `dir` (or holds it), or null: how a tool run inside a worktree
+ * (scripts/gates/gate.mjs) finds its workflow through the registry, never by parsing a branch or folder name.
+ */
+export function workflowWorktreeAt(ctx, dir) {
+  const env = envOf(ctx);
+  const at = path.resolve(dir);
+  const key = (p) => { let r = path.resolve(p); try { r = fs.realpathSync.native(r); } catch { /* missing */ } return process.platform === 'win32' ? r.toLowerCase() : r; };
+  try {
+    const rows = withMachine((m) => m.db.prepare("SELECT * FROM worktrees WHERE kind='workflow' AND orca_id IS NOT NULL AND removed_at IS NULL ORDER BY created_at DESC").all(), { env });
+    const row = rows.find((r) => key(r.path) === key(at)) ?? rows.find((r) => insidePath(key(at), key(r.path)));
+    return workflowRecordOf(row ?? null);
+  } catch (cause) { throw Object.assign(new Error(`the workflow worktree registry is unavailable: ${cause.message}`, { cause }), { code: 'worktree-registry-unavailable' }); }
+}
+
+/** The registry functions a caller may replace (ctx.worktree in a spec, the functions above in the runtime). */
+const registryOf = (ctx) => ({ workflowWorktreeOf, workflowWorktreeAt, ...ctx?.worktree });
+
+/** The registry record of the workflow's worktree, its directory present: {workflowId, orcaWorktreeId, path, branch, checkpoint}. */
+function presentRecordOf(ctx, workflowId) {
+  return requireWorktreeRecord(registryOf(ctx).workflowWorktreeOf(ctx, workflowId), workflowId);
+}
+
+/**
+ * The gate base of the workflow worktree that holds `dir` (part A's workflowWorktreeAt over the registry), or null when
+ * `dir` is no workflow worktree: scripts/gates/gate.mjs measures an op there against its previous checkpoint.
+ */
+export function gateBaseAt(ctx, dir) {
+  const rec = registryOf(ctx).workflowWorktreeAt(ctx, dir);
+  return rec ? gateBaseOf(ctx, rec.workflowId) : null;
+}
+
+/** The base an op's gate measures against: the previous checkpoint, else the merge-base of the workflow branch with main. */
+/**
+ * The newest checkpoint commit of the workflow's own chain on the branch (subject `checkpoint <workflowId>: ...`, first-parent line from HEAD), or null. A registry
+ * record that lost its checkpoint pointer (a tree put back by the custody repair) must not fall back to the merge-base with main: that would put the base of
+ * every settled op's gate, and the target of a reset, behind the work those ops committed.
+ */
+function chainCheckpointOf(rec) {
+  const r = gitLog(['--first-parent', '--format=%H%x09%s', '-n', '256', 'HEAD'], { cwd: rec.path, timeout: 30_000 });
+  if (r.status !== 0) return null;
+  const prefix = `checkpoint ${rec.workflowId}:`;
+  for (const line of String(r.stdout ?? '').split(/\r?\n/)) {
+    const [sha, subject] = line.split('\t');
+    if (SHA.test(sha ?? '') && subject?.startsWith(prefix)) return sha;
+  }
+  return null;
+}
+
+export function gateBaseOf(ctx, workflowId) {
+  const rec = presentRecordOf(ctx, workflowId);
+  const chained = rec.checkpoint ? null : chainCheckpointOf(rec);
+  if (chained) return chained;
+  if (rec.checkpoint) {
+    const sha = revParse(rec.path, rec.checkpoint);
+    if (!sha) throw fail({ code: 'workflow-gate-base-unknown' }, `the checkpoint ${rec.checkpoint} of workflow ${workflowId} is not a commit of ${rec.path}`);
+    return sha;
+  }
+  const base = mergeBase(rec.path, `refs/heads/${mainOf(ctx)}`, 'HEAD') ?? '';
+  if (!SHA.test(base)) throw fail({ code: 'workflow-gate-base-unknown' }, `workflow ${workflowId} has no checkpoint and ${rec.branch} has no merge-base with ${mainOf(ctx)}`);
+  return base;
+}
+
+const CHAIN_WALK_MAX = 64;
+/**
+ * The bases an op's gate may have measured against, newest first (per side, WFWT2 2.2): the current checkpoint, then each
+ * older checkpoint of the chain while the checkpoint stepped over changed none of `owned` (the op's owned paths, the
+ * leases checkpointOp commits), stopping at the chain's start (the merge-base with main). A be checkpoint committed while
+ * an fe op ran therefore never forces the fe op to re-run its gate: what differs between the bases is the other side's
+ * committed, gated work, and the finish gates the whole branch again. An op that owns no path or owns '.' gets the current
+ * checkpoint only.
+ */
+export function gateBasesOf(ctx, workflowId, { owned = [] } = {}) {
+  const current = gateBaseOf(ctx, workflowId);
+  const paths = owned.map(String).filter(Boolean);
+  if (!paths.length || paths.some((p) => p === '.' || p === './')) return [current];
+  const rec = presentRecordOf(ctx, workflowId);
+  const root = mergeBase(rec.path, `refs/heads/${mainOf(ctx)}`, current);
+  const bases = [current];
+  for (let at = current; at !== root && bases.length < CHAIN_WALK_MAX;) {
+    const parent = revParse(rec.path, `${at}^`);
+    if (!parent) break;
+    const touched = diffNames(rec.path, parent, at, { paths: paths.map((p) => `:(literal)${p}`) });
+    if (touched === null || touched.length) break;
+    bases.push(parent);
+    at = parent;
+  }
+  return bases;
+}

package/runtime/scripts/reconciler/checklist-items.mjs

@@ -0,0 +1,7 @@
+// The checklist row builders of `start` (scripts/reconciler/start.mjs) and of the row modules split out of it.
+
+/** One checklist row. status green|red|warn; required rows decide the exit code, warn never does; a green row with `idle: true` is an agent seat that is not running because nothing needs it yet. */
+const item = (group, id, name, status, detail = '', { fix = null, required = true, idle = false } = {}) => ({ group, id, name, status, required: required && status !== 'warn', detail, ...(fix && status !== 'green' ? { fix } : {}), ...(idle && status === 'green' ? { idle: true } : {}) });
+export const green = (group, id, name, detail, opts) => item(group, id, name, 'green', detail, opts);
+export const red = (group, id, name, detail, fix, opts) => item(group, id, name, 'red', detail, { fix, ...opts });
+export const warn = (group, id, name, detail, fix) => item(group, id, name, 'warn', detail, { fix, required: false });

package/runtime/scripts/reconciler/guard-row.mjs

@@ -0,0 +1,25 @@
+// guard-row.mjs — the host checklist row of the command guard hook: the exact hook command launch trust registers is run
+// the way a seat's shell runs it (scripts/api/process/probe-guard-command.mjs), because a hook that does not resolve is a
+// non-blocking error and leaves every guarded command unguarded. Required: red names each failing shell.
+import { probeGuardCommand } from '../api/process/probe-guard-command.mjs';
+import { toolGuardCommand } from '../lib/guard-command.mjs';
+import { green, red } from './checklist-items.mjs';
+
+const NAME = 'command guard resolvable';
+const FIX = 'starci runtime link, then launch again to refresh the registered Node and linked runtime CLI paths';
+
+/** The row of one probe of `toolGuardCommand()`; never throws. Seam: `probe`. */
+export function guardCommandRow({ home, probe = probeGuardCommand } = {}) {
+  let command;
+  let result;
+  try {
+    command = toolGuardCommand({ home });
+    result = probe({ command, home });
+  }
+  catch (error) { return red('preflight', 'guard-command', NAME, `${command ?? 'linked runtime guard'}: ${String(error?.message ?? error).slice(0, 200)}`, FIX); }
+  if (!result.ok) return red('preflight', 'guard-command', NAME, `${command} does not run: ${result.reason}`.slice(0, 400), FIX);
+  const ran = result.shells.filter((entry) => !entry.skipped).map((entry) => entry.shell).join(', ');
+  const skipped = result.shells.filter((entry) => entry.skipped).map((entry) => entry.skipped);
+  const note = skipped.length ? ` (skipped: ${skipped.join('; ')})` : '';
+  return green('preflight', 'guard-command', NAME, `${command} runs through ${ran}${note}`);
+}

package/runtime/scripts/work/asset-slot.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+// asset-slot.mjs — artwork a drawing owes to interface.asset (owner ruling 2026-09-27: "mascot/illustration comes from
+// interface.asset, never reused ad hoc").
+//
+// A drawing that needs artwork (a mascot, an illustration, a hero image) never reuses a file it found: it marks the
+// place data-asset-slot="<id>" on the MediaFrame / Image / img (a placeholder src, or none, is fine) and requests it in
+// asset-request.md beside its render source (or in the ui record directory) - one heading per slot naming its id, the
+// section its purpose, placement, pixel size and format, and the brand master it references. The DNA gate refuses
+// artwork without a slot and a slot without a request (DRAW_ASSET_SLOT_UNDECLARED, scripts/work/draw/draw-dna.mjs), and
+// the draw records each slot in ui.artworkSlots[] (status owed).
+//
+// interface.asset owes every open slot: it generates the artwork under the brand record's imagery.promptRules (and
+// masters), then replaces the placeholder in the render source - src the produced file, data-asset-sha256 its bytes'
+// sha256, data-asset-prompt the prompt.txt it was generated from - and records ui.artworkSlots[].file/sha256/status.
+// The brand masters (brand/assets/**, the unicorn masters) are the LANDING's art and the style reference only (owner
+// ruling 2026-09-27): every product slot is owed a NEW generation - a new pose/composition per surface in the same
+// brand style - so a master may stand in only as the placeholder. A slot is FILLED only when data-asset-sha256 names
+// the sha256 of the file its src resolves to, those bytes are not byte-identical to any brand master, and its prompt
+// (data-asset-prompt, else <file>.prompt.txt beside it) exists; anything else is OWED. A done ui record with an owed
+// slot is refused (ASSET_SLOT_UNFILLED, scripts/work/validate/check-example-work.mjs).
+//
+// The ledger: settling an interface.draw or interface.asset job records one `asset-slot-owed` event per owed slot of
+// the files it binds and one `asset-slot-filled` per filled one; `starci kernel status` lists the open ones as assetSlotsOwed[]
+// and its nextActions propose an interface.asset leg for them (scripts/kernel/cli.mjs).
+//
+//   starci work asset-slot list <file|dir>... [--json]    every slot, owed or filled, with its request
+//   starci work asset-slot check <file|dir>... [--json]   exit 1 when a slot has no request
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMain } from '../lib/is-main.mjs';
+import { sha256File } from '../../engine/digest.mjs';
+import { openEventItems } from '../lib/event-items.mjs';
+import { ASSET_SLOT_ATTR, COMPONENT_ATTR, parseHtml, walkElements } from './draw/draw-dna.mjs';
+import { isDir, isFile, slash } from './work-io.mjs';
+
+export { ASSET_SLOT_ATTR };
+const ASSET_SHA_ATTR = 'data-asset-sha256';
+const ASSET_REQUEST_FILE = 'asset-request.md';
+const ASSET_SLOT_OWED = 'asset-slot-owed';
+const ASSET_SLOT_FILLED = 'asset-slot-filled';
+const ASSET_PROMPT_ATTR = 'data-asset-prompt';
+export const ASSET_OP = 'interface.asset';
+export const ASSET_SLOT_UNFILLED = 'ASSET_SLOT_UNFILLED';
+const SKIP_DIRS = new Set(['node_modules', '.git', 'draw-loop']);
+
+/** The ui record directory above `file` (the nearest dir holding index.yaml, at most 6 levels up), or null. */
+export function uiDirOf(file) {
+  let dir = isDir(file) ? file : path.dirname(file);
+  for (let i = 0; i < 7; i++) {
+    if (isFile(path.join(dir, 'index.yaml'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+/** The asset-request.md files that belong to a render source: beside it, up to its ui record dir, and in `dirs`. */
+function requestFilesFor(htmlFile, dirs = []) {
+  const out = [];
+  const add = (dir) => { const f = path.join(dir, ASSET_REQUEST_FILE); if (isFile(f) && !out.includes(f)) out.push(f); };
+  const stop = uiDirOf(htmlFile);
+  let dir = path.dirname(htmlFile);
+  for (let i = 0; i < 7; i++) {
+    add(dir);
+    if (!stop || dir === stop) break;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  for (const d of dirs) add(d);
+  return out;
+}
+
+const SLUG = /^[a-z0-9][a-z0-9._-]*$/i;
+const HEADING_PATTERN = new RegExp(['^#{1,6}', String.raw`\s+`, '(.*)$'].join(''));
+const SLOT_LINE_PATTERN = new RegExp([String.raw`^\s*`, '[-*]?', String.raw`\s*(?:slot|id)\s*:\s*`, '`?', String.raw`([\w.-]+)`, '`?', String.raw`\s*$`].join(''), 'i');
+/** The slot requests of asset-request.md files: [{id, file, brief}] - a heading per slot, or `slot: <id>` lines. */
+function readAssetRequests(files) {
+  const out = [];
+  for (const file of files ?? []) readFileRequests(file, out);
+  return out;
+}
+
+function readFileRequests(file, out) {
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return; }
+  const lines = text.split(/\r?\n/);
+  let current = null;
+  for (const line of lines) {
+    current = requestLine(line, current, file, out);
+  }
+}
+
+function requestLine(line, current, file, out) {
+  const heading = HEADING_PATTERN.exec(line);
+  const slotLine = SLOT_LINE_PATTERN.exec(line);
+  if (heading) {
+    const id = requestedHeadingId(heading[1].trim());
+    return id ? pushRequest(id.trim(), file, out) : null;
+  }
+  if (slotLine) return current?.id !== slotLine[1] ? pushRequest(slotLine[1], file, out) : current;
+  if (current && line.trim()) current.brief = `${current.brief} ${line.trim()}`.trim().slice(0, 400);
+  return current;
+}
+
+function requestedHeadingId(heading) {
+  return new RegExp(String.raw`${ASSET_SLOT_ATTR}\s*=\s*["']([^"']+)["']`).exec(heading)?.[1] ?? /`([^`]+)`/.exec(heading)?.[1] ?? (SLUG.test(heading) ? heading : null);
+}
+
+function pushRequest(id, file, out) {
+  const current = { id, file, brief: '' };
+  out.push(current);
+  return current;
+}
+
+/** The Set of slot ids the render source's asset-request.md files request. */
+export const assetRequestIdsFor = (htmlFile, dirs = []) => new Set(readAssetRequests(requestFilesFor(htmlFile, dirs)).map((r) => r.id));
+
+/** The .starciwork directory above `file`, or null. */
+function workRootAbove(file) {
+  let dir = path.dirname(path.resolve(file));
+  for (let i = 0; i < 12; i++) {
+    if (path.basename(dir) === '.starciwork') return dir;
+    if (isDir(path.join(dir, '.starciwork')) && isFile(path.join(dir, '.starciwork', 'brand', 'index.yaml'))) return path.join(dir, '.starciwork');
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+/** Calls `onFile(fullPath, name)` for every file under `dir`, `depth` directory levels down; `enter(name)` admits a directory. */
+function eachFileUnder(dir, depth, onFile, enter = () => true) {
+  let entries = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (!e.isDirectory()) onFile(full, e.name);
+    else if (depth > 0 && enter(e.name)) eachFileUnder(full, depth - 1, onFile, enter);
+  }
+}
+
+/** The sha256 of every brand master file (<work>/brand/assets/**): the landing's art, never a product slot's bytes. */
+function brandMasterShas(workRoot) {
+  if (!workRoot) return new Set();
+  const out = new Set();
+  eachFileUnder(path.join(workRoot, 'brand', 'assets'), 6, (full) => { try { out.add(sha256File(full)); } catch { /* unreadable */ } });
+  return out;
+}
+
+/**
+ * The slots of one render source: [{id, tag, component, src, sha256, file, master, prompt, filled}]; `htmlFile`
+ * resolves the src and the prompt, `masters` is the Set of brand master sha256s a filled slot must not equal.
+ */
+function slotsOfHtml(html, { htmlFile = null, masters = new Set() } = {}) {
+  const out = [];
+  for (const el of walkElements(parseHtml(html))) {
+    const slot = slotOfElement(el, htmlFile, masters);
+    if (slot) out.push(slot);
+  }
+  return out;
+}
+
+/** The prompt file a slot names (relative to its render source), else the `.prompt.txt` beside its filled asset. */
+function promptFileOf(promptAttr, htmlFile, actual, file) {
+  if (promptAttr && htmlFile) return path.resolve(path.dirname(htmlFile), promptAttr);
+  return actual ? file.replace(/\.[^.\\/]+$/, '.prompt.txt') : null;
+}
+
+function slotOfElement(el, htmlFile, masters) {
+  const id = (el.attrs[ASSET_SLOT_ATTR] ?? '').trim();
+  if (!id) return null;
+  const img = el.tag === 'img' ? el : walkElements(el).find((d) => d.tag === 'img') ?? el;
+  const src = (img.attrs.src ?? el.attrs.src ?? '').trim() || null;
+  const sha = (el.attrs[ASSET_SHA_ATTR] ?? img.attrs[ASSET_SHA_ATTR] ?? '').trim().toLowerCase() || null;
+  const { file, actual } = actualAssetFile(src, htmlFile);
+  const master = Boolean(actual && masters.has(actual));
+  const promptFile = promptFileOf((el.attrs[ASSET_PROMPT_ATTR] ?? img.attrs[ASSET_PROMPT_ATTR] ?? '').trim(), htmlFile, actual, file);
+  const prompt = promptFile && isFile(promptFile) ? promptFile : null;
+  return { id, tag: el.tag, component: el.attrs[COMPONENT_ATTR] ?? null, src, sha256: sha, file: actual ? file : null, master, prompt,
+    filled: slotIsFilled(sha, actual, master, prompt) };
+}
+
+// Filled: the declared sha256 is the asset's actual bytes, which are not a brand master, and a prompt file exists.
+const slotIsFilled = (sha, actual, master, prompt) => Boolean(sha && actual && sha === actual && !master && prompt);
+
+function actualAssetFile(src, htmlFile) {
+  let file = null, actual = null;
+  if (src && htmlFile && !/^(data:|https?:|\/\/)/i.test(src)) {
+    file = path.resolve(path.dirname(htmlFile), decodeURI(src.split(/[?#]/)[0]));
+    try { actual = isFile(file) ? sha256File(file) : null; } catch { actual = null; }
+  }
+  return { file, actual };
+}
+
+/** The render sources among `targets` (files, or directories walked without draw-loop rounds). */
+function renderSourcesIn(targets, depth = 6) {
+  const out = new Map();
+  const add = (file) => { if (/\.html?$/i.test(file)) out.set(path.resolve(file).toLowerCase(), path.resolve(file)); };
+  for (const t of targets ?? []) {
+    if (isDir(t)) eachFileUnder(t, depth, add, (name) => !SKIP_DIRS.has(name));
+    else if (isFile(t)) add(t);
+  }
+  return [...out.values()];
+}
+
+/**
+ * Every slot of the render sources among `targets`: [{key, id, ui, html, requested, request, filled, src, sha256}].
+ * `key` is `<ui record dir, repo-relative>#<slot id>` - one slot per ui record, however many parts show it.
+ */
+export function assetSlotsOf(targets, { repo = process.cwd() } = {}) {
+  const bySlot = new Map();
+  const mastersByRoot = new Map();
+  for (const html of renderSourcesIn(targets)) addHtmlSlots(bySlot, mastersByRoot, html, repo);
+  return [...bySlot.values()];
+}
+
+function addHtmlSlots(bySlot, mastersByRoot, html, repo) {
+  let text = '';
+  try { text = fs.readFileSync(html, 'utf8'); } catch { return; }
+  if (!text.includes(ASSET_SLOT_ATTR)) return;
+  const requests = readAssetRequests(requestFilesFor(html));
+  const ui = slash(path.relative(repo, uiDirOf(html) ?? path.dirname(html)));
+  const workRoot = workRootAbove(html);
+  if (!mastersByRoot.has(workRoot)) mastersByRoot.set(workRoot, brandMasterShas(workRoot));
+  const masters = mastersByRoot.get(workRoot);
+  for (const s of slotsOfHtml(text, { htmlFile: html, masters })) {
+    const key = `${ui}#${s.id}`;
+    const request = requests.find((r) => r.id === s.id) ?? null;
+    const slot = { key, id: s.id, ui, html: slash(path.relative(repo, html)), requested: Boolean(request), request: request ? { file: slash(path.relative(repo, request.file)), brief: request.brief } : null,
+      filled: s.filled, src: s.src, sha256: s.sha256, master: s.master, prompt: s.prompt ? slash(path.relative(repo, s.prompt)) : null };
+    const prior = bySlot.get(key);
+    // A slot is filled only when every part that shows it carries the filled bytes.
+    bySlot.set(key, prior ? { ...prior, filled: prior.filled && slot.filled } : slot);
+  }
+}
+
+/**
+ * Record one `asset-slot-owed` event per owed slot of the job's files and one `asset-slot-filled` per filled one
+ * (once per slot key and sha). Returns {owed, filled} newly recorded. `ledger` is an open ledger (appendEvent).
+ */
+export function recordAssetSlots(ledger, { job, repo, files, now = Date.now() }) {
+  const db = ledger.db;
+  const recorded = { owed: [], filled: [] };
+  for (const s of assetSlotsOf(files, { repo })) {
+    const kind = s.filled ? ASSET_SLOT_FILLED : ASSET_SLOT_OWED;
+    const seen = db.prepare("SELECT 1 FROM events WHERE workflow_id=? AND kind=? AND json_extract(payload_json,'$.key')=? AND json_extract(payload_json,'$.sha256') IS ? AND json_extract(payload_json,'$.jobId')=? LIMIT 1")
+      .get(job.workflow_id, kind, s.key, s.sha256, job.job_id);
+    if (seen) continue;
+    const payload = { key: s.key, id: s.id, ui: s.ui, html: s.html, src: s.src, sha256: s.sha256, requested: s.requested, request: s.request?.file ?? null, jobId: job.job_id, opId: job.op_id, attempt: job.attempt };
+    ledger.appendEvent({ workflowId: job.workflow_id, entityType: 'job', entityId: job.job_id, kind, createdAt: now, payload });
+    recorded[s.filled ? 'filled' : 'owed'].push(payload);
+  }
+  return recorded;
+}
+
+/** The workflow's open asset slots (owed, not filled since): [{key, id, ui, html, request, jobId, opId, owedAt}]. */
+export function openAssetSlots(db, workflowId) {
+  return openEventItems(db, workflowId, {
+    owedKind: ASSET_SLOT_OWED, resolvedKind: ASSET_SLOT_FILLED, keyOf: (p) => p.key,
+    item: (p, row) => ({ key: p.key, id: p.id ?? null, ui: p.ui ?? null, html: p.html ?? null, request: p.request ?? null, requested: p.requested !== false, jobId: p.jobId ?? null, opId: p.opId ?? null, owedAt: row.created_at }),
+  });
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  const json = rest.includes('--json');
+  const targets = rest.filter((a) => !a.startsWith('--')).map((t) => path.resolve(t));
+  if (!['list', 'check'].includes(cmd) || !targets.length) {
+    process.stderr.write('use: starci work asset-slot list|check <file|dir>... [--json]\n');
+    return 2;
+  }
+  const slots = assetSlotsOf(targets);
+  const unrequested = slots.filter((s) => !s.requested);
+  if (json) process.stdout.write(`${JSON.stringify({ ok: cmd === 'list' || !unrequested.length, slots }, null, 2)}\n`);
+  else {
+    const lines = slots.map((s) => `${s.filled ? 'filled' : 'OWED  '} ${s.key}${s.requested ? '' : ' (NO REQUEST in asset-request.md)'} ${s.html}`).join('\n');
+    process.stdout.write(`${lines || 'no asset slots'}\n`);
+  }
+  return cmd === 'check' && unrequested.length ? 1 : 0;
+}
+
+if (isMain(import.meta.url)) process.exitCode = main(process.argv.slice(2));