@starci/hfs 4.0.9 → 4.0.10

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

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

package/runtime/scripts/connectors/lib.mjs

@@ -0,0 +1,488 @@
+// scripts/connectors/lib.mjs — what the ask gateway, the tunnel manager and the
+// Telegram notifier share: the host locks every singleton manager claims, the
+// connectors rows (machine.sqlite `connectors`: gateway, tunnel,
+// telegram-bridge, telegram-route, supervisor-channel:<id>), the repositories
+// whose asks go public, the read-only projection of open ask forms, and the
+// small process helpers. docs/connectors.md is the design note.
+//
+// Every ledger read here goes through inspectLedger (read-only): the
+// connectors observe asks, they never write a ledger. Every piece of host state
+// lives in machine.sqlite (engine/db/machine.mjs): a manager lock is a
+// host_locks row, a launch still starting is that row in state 'starting'.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnNode } from '../api/node/spawn-node.mjs';
+import { inspectLedger, ledgerFileFor, isRuntimeRoot, hasLedger } from '../../engine/db/ledger.mjs';
+import { machineLog, pidAlive, readMachine, withMachine } from '../../engine/db/machine.mjs';
+import { skillRoot, starciSourceRoot } from '../../engine/runtime-root.mjs';
+import { loadConfig } from '../../engine/config.mjs';
+import { parseJson, readJsonFile } from '../lib/json.mjs';
+import { jobDisplayNameOf, workflowNameOf } from '../lib/display-names.mjs';
+import { sleep } from '../lib/sleep.mjs';
+import { OWNED_PROCESS_SCHEMA } from '../lib/process-identity.mjs';
+import { stopOwnedProcess } from '../api/process/stop-owned-process.mjs';
+import { canonicalJSON } from '../../engine/canonical-json.mjs';
+
+
+/** When this host last booted (ms). */
+const hostBootAt = () => Date.now() - os.uptime() * 1000;
+/**
+ * Whether the process a state record names ({pid, startedAt}) is still that process: its pid is
+ * live AND it started in this boot. After a reboot the recorded pid may name an unrelated process,
+ * and a connector that trusted it would never start again. `startedAt` is an ISO time or epoch ms.
+ */
+export const recordAlive = (record) => {
+  if (!record?.pid || !pidAlive(record.pid)) return false;
+  const started = typeof record.startedAt === 'number' ? record.startedAt : Date.parse(record.startedAt ?? '');
+  return !Number.isFinite(started) || started >= hostBootAt() - 60_000;
+};
+
+/* ------------------------------------------------------------ host locks (machine.sqlite host_locks) */
+
+/**
+ * How long a held manager lock stays unexpired without a renewal. The holder renews it every LOCK_RENEW_MS from an
+ * unref'd timer, so an expired lock (v_leaks) is one whose holder stopped renewing. Who holds a lock is decided by its
+ * holder pid (recordAlive: live and of this boot), never by the expiry: a busy holder that missed a renewal keeps it.
+ */
+const LOCK_TTL_MS = 10 * 60_000;
+const LOCK_RENEW_MS = 3 * 60_000;
+const holderLabel = () => (process.argv[1] ? path.basename(process.argv[1]) : 'node');
+/** A host_locks row as the record callers read: {pid, startedAt (ISO), at, handedOverFrom, state, holder}. */
+const lockRecord = (row) => (row ? { pid: row.holder_pid, startedAt: new Date(row.started_at).toISOString(), at: row.started_at,
+  handedOverFrom: row.handed_over_from ?? null, state: row.state, holder: row.holder ?? null } : null);
+const liveRow = (row) => Boolean(row) && row.state !== 'released' && recordAlive({ pid: row.holder_pid, startedAt: row.started_at });
+
+// The renewal timers of the locks this process holds, by name.
+const renewals = new Map();
+const stopRenewal = (name) => { clearInterval(renewals.get(name)); renewals.delete(name); };
+function startRenewal(name, env) {
+  stopRenewal(name);
+  const timer = setInterval(() => {
+    let still = true;
+    try { still = withMachine((m) => m.renewHostLock({ name, ttlMs: LOCK_TTL_MS }), { env }); } catch { /* a busy store: the next tick tries again */ }
+    if (!still) stopRenewal(name);
+  }, LOCK_RENEW_MS);
+  timer.unref?.();
+  renewals.set(name, timer);
+}
+/** The handle a successful claim returns: release() frees the lock only while it still names this process. */
+function heldBy(name, env, extra = {}) {
+  startRenewal(name, env);
+  const release = () => {
+    stopRenewal(name);
+    try { withMachine((m) => m.releaseHostLock({ name }), { env }); } catch { /* the store is gone: nothing left to free */ }
+  };
+  return { ok: true, release, name, ...extra };
+}
+
+/**
+ * Take `name` for this process inside one transaction on `m`: refused while another live process of this boot holds
+ * it (state 'held'); a dead holder, one from an earlier boot, or a launch still 'starting' is replaced. Returns
+ * {ok:true} or {ok:false, holder}.
+ */
+function takeLock(m, name) {
+  return m.transaction(() => {
+    const custody = recordOf(m.connectorOf(name));
+    if (connectorManagerBlocked(custody)) return { ok: false, holder: custody, reason: 'connector-child-custody-unreconciled' };
+    const cur = m.hostLock(name);
+    if (cur && cur.state === 'held' && cur.holder_pid !== process.pid && liveRow(cur)) return { ok: false, holder: lockRecord(cur) };
+    if (cur && cur.state !== 'released' && cur.holder_pid !== process.pid) m.releaseHostLock({ name, force: true });
+    const got = m.acquireHostLock({ name, holder: holderLabel(), ttlMs: LOCK_TTL_MS, state: 'held' });
+    return got.ok ? { ok: true } : { ok: false, holder: lockRecord(got.holder) };
+  });
+}
+
+/**
+ * Claim the single-manager host lock `name` for this process. `current` is the manager's own record (its connectors
+ * row: gateway, tunnel): a live one that is not this process owns the state even without the lock. A lock whose
+ * holder is dead or from an earlier boot is stale and taken over. Returns {ok:true, release} or {ok:false, holder}.
+ */
+export function claimManager(name, { current = null, env = process.env } = {}) {
+  if (connectorManagerBlocked(current)) return { ok: false, holder: current, reason: 'connector-child-custody-unreconciled' };
+  if (current && current.pid !== process.pid && recordAlive(current)) return { ok: false, holder: current };
+  const got = withMachine((m) => takeLock(m, name), { env });
+  return got.ok ? heldBy(name, env) : { ok: false, holder: got.holder ?? null, ...(got.reason ? { reason: got.reason } : {}) };
+}
+
+/**
+ * Claim a manager lock that may be handed over (scripts/machine/self-reload.mjs): a loop that re-execs itself
+ * spawns its replacement with `from` = its own pid and waits, still holding the lock, until the lock names
+ * the replacement. The replacement takes the row over only while it still names `from`, in one transaction,
+ * so there is no moment the lock is free for a third claimant. Without `from`, or when the lock no longer
+ * names it, this is claimManager. Returns {ok:true, release, takenOver?} or {ok:false, holder}.
+ */
+export function claimOrTakeOver(name, { from = null, env = process.env } = {}) {
+  const fromPid = Number(from);
+  if (Number.isInteger(fromPid) && fromPid > 0) {
+    const took = withMachine((m) => m.transaction(() => {
+      if (connectorManagerBlocked(recordOf(m.connectorOf(name)))) return false;
+      const cur = m.hostLock(name);
+      if (!cur || cur.state === 'released' || cur.holder_pid !== fromPid) return false;
+      const at = m.now();
+      return m.update('host_locks', { holder_pid: process.pid, holder: holderLabel(), started_at: at, heartbeat_at: at, expires_at: at + LOCK_TTL_MS,
+        handed_over_from: fromPid, state: 'held' }, { name, holder_pid: fromPid }).changes > 0;
+    }), { env });
+    if (took) return heldBy(name, env, { takenOver: true });
+  }
+  return claimManager(name, { env });
+}
+
+/** Make the lock name this process again (a handover that failed after the replacement took it). */
+export const reassertManager = (name, { env = process.env } = {}) => {
+  const ok = withMachine((m) => m.transaction(() => {
+    const cur = m.hostLock(name);
+    if (cur && cur.state !== 'released' && cur.holder_pid !== process.pid) m.releaseHostLock({ name, force: true });
+    return m.acquireHostLock({ name, holder: holderLabel(), ttlMs: LOCK_TTL_MS, state: 'held' }).ok;
+  }), { env });
+  if (ok) startRenewal(name, env);
+  return ok;
+};
+
+/** The live holder of a manager lock ({pid, startedAt, handedOverFrom, ...}), or null. A launch still starting is not one. */
+export const lockHolder = (name, env = process.env) => {
+  const row = readMachine((m) => m.hostLock(name), null, { env });
+  return row?.state === 'held' && liveRow(row) ? lockRecord(row) : null;
+};
+
+/**
+ * A manager a starter just launched but that has not claimed its lock yet (node takes a while to
+ * start on a loaded host). `start` marks the lock row 'starting' with the launched pid right after the
+ * spawn, and every liveness test counts it for STARTING_MS while that pid lives, so two starters in
+ * that window do not both launch a manager. The launched manager's claim turns the row 'held'.
+ */
+const STARTING_MS = 30_000;
+export const markStarting = (name, pid, env = process.env) => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  return withMachine((m) => m.transaction(() => {
+    const cur = m.hostLock(name);
+    // A live holder (the launched manager already claimed, or another one) is never overwritten.
+    if (cur && cur.state === 'held' && liveRow(cur)) return false;
+    if (cur && cur.state !== 'released' && cur.holder_pid !== pid) m.releaseHostLock({ name, force: true });
+    return m.acquireHostLock({ name, holder: 'starting', pid, ttlMs: STARTING_MS, state: 'starting' }).ok;
+  }), { env });
+};
+export const startingHolder = (name, env = process.env, { windowMs = STARTING_MS, now = Date.now() } = {}) => {
+  const row = readMachine((m) => m.hostLock(name), null, { env });
+  return row?.state === 'starting' && now - row.started_at < windowMs && pidAlive(row.holder_pid)
+    ? { pid: row.holder_pid, at: row.started_at, startedAt: new Date(row.started_at).toISOString() } : null;
+};
+
+/**
+ * Run async `fn` while holding the host lock `name` (a short cross-process mutex: the Telegram notice store, the
+ * media dedupe). Waits up to `waitMs`, then resolves {ok:false, skipped} without running `fn`. Calls from one
+ * process are chained, since a host lock is per pid.
+ */
+const chains = new Map();
+export function withHostMutex(name, fn, { env = process.env, waitMs = 10_000, stepMs = 100 } = {}) {
+  const prior = chains.get(name) ?? Promise.resolve();
+  const run = prior.catch(() => {}).then(async () => {
+    const end = Date.now() + waitMs;
+    for (;;) {
+      let got;
+      try { got = withMachine((m) => takeLock(m, name), { env }); } catch { got = { ok: false }; }
+      if (got.ok) break;
+      if (Date.now() > end) return { ok: false, skipped: `${name} is locked` };
+      await sleep(stepMs);
+    }
+    try { return await fn(); } finally { try { withMachine((m) => m.releaseHostLock({ name }), { env }); } catch { /* gone */ } }
+  });
+  chains.set(name, run);
+  run.catch(() => {}).finally(() => { if (chains.get(name) === run) chains.delete(name); });
+  return run;
+}
+
+export const CONNECTOR_LAUNCH_ENV = 'STARCI_CONNECTOR_LAUNCH';
+
+/* ------------------------------------------------------------ connectors rows (machine.sqlite connectors) */
+
+const recordOf = (row) => (row ? { ...(row.config ?? {}), pid: row.pid ?? row.config?.pid ?? null, port: row.port ?? row.config?.port ?? null,
+  publicUrl: row.public_url ?? null, state: row.state ?? null, cursor: row.cursor ?? null, updatedAt: row.updated_at } : null);
+/**
+ * One connector's record, or null: its config_json spread, with the row's pid, port, publicUrl, state, cursor and
+ * updatedAt. `name`: gateway | tunnel | telegram-bridge | telegram-route | supervisor-channel:<id>.
+ */
+export const connectorState = (name, env = process.env) => readMachine((m) => recordOf(m.connectorOf(name)), null, { env });
+/** Every connector row whose name starts with `prefix`, as connectorState records with their `name`. */
+export const connectorStates = (prefix, env = process.env) => readMachine((m) => m.db.prepare('SELECT name FROM connectors WHERE substr(name,1,length(?))=? ORDER BY name')
+  .all(prefix, prefix).map((r) => ({ name: r.name, ...recordOf(m.connectorOf(r.name)) })), [], { env });
+/**
+ * Write one connector row: only the fields given change (`config` and `cursor` replace their column whole). Returns
+ * true. No secret ever goes here (the token lives in .starcistacks / the secrets file).
+ */
+export const writeConnectorState = (name, { kind, state, pid, port, publicUrl, config, cursor } = {}, env = process.env) => withMachine((m) => m.transaction(() => {
+  const current = recordOf(m.connectorOf(name));
+  if (connectorChildUnresolved(current) && config !== undefined
+      && (config.childLaunchNonce !== current.childLaunchNonce || canonicalJSON(config.childIdentity ?? null) !== canonicalJSON(current.childIdentity ?? null)
+        || canonicalJSON(config.childCapture ?? null) !== canonicalJSON(current.childCapture ?? null)
+        || closedProcess(current.stopReceipt?.manager, current.processIdentity)
+          && canonicalJSON(config.stopReceipt?.manager ?? null) !== canonicalJSON(current.stopReceipt.manager)))
+    throw Error('connector-child-custody-unreconciled');
+  const row = { name, updated_at: m.now(), kind, state, pid, port, public_url: publicUrl, config_json: config, cursor_json: cursor };
+  m.upsert('connectors', Object.fromEntries(Object.entries(row).filter(([, v]) => v !== undefined)), ['name']);
+  return true;
+}), { env });
+
+
+const sameIdentity = (a, b) => Boolean(a && b) && canonicalJSON(a) === canonicalJSON(b);
+const sameConnectorOwner = (a, b) => Boolean(a && b) && a.pid === b.pid && a.source === b.source && sameIdentity(a.processIdentity, b.processIdentity);
+const closedProcess = (receipt, identity) => receipt?.schema === OWNED_PROCESS_SCHEMA && receipt.ok === true
+  && ['gone', 'stopped'].includes(receipt.outcome) && receipt.proof === 'process-handle-signaled'
+  && receipt.pid === identity?.pid && sameIdentity(receipt.identity, identity);
+const closedChild = (receipt, record) => Boolean(receipt && record.childLaunchNonce && receipt.launchNonce === record.childLaunchNonce)
+  && (closedProcess(receipt, record.childIdentity) || receipt.ok === true && receipt.proof === 'owned-child-process-exit'
+    && receipt.pid === record.childIdentity?.pid || receipt.ok === true && receipt.proof === 'owned-child-spawn-failed' && receipt.pid == null);
+
+/** Original child custody remains owed even when its manager or lock no longer lives. */
+export const connectorChildUnresolved = (record) => Boolean(record && (record.childLaunchNonce || record.childPid || record.childIdentity))
+  && !closedChild(record.childClosure, record) && !closedChild(record.stopReceipt?.child, record);
+export const connectorManagerBlocked = (record) => connectorChildUnresolved(record)
+  && (closedProcess(record.stopReceipt?.manager, record.processIdentity) || !recordAlive(record));
+
+const retainConnectorClosure = (name, expected, receipt, env) => withMachine((m) => m.transaction(() => {
+  const row = m.connectorOf(name), current = recordOf(row);
+  if (!sameConnectorOwner(current, expected) || canonicalJSON(current) !== canonicalJSON(expected)) return false;
+  m.upsert('connectors', { name, updated_at: m.now(), config_json: { ...(row.config ?? {}), stopReceipt: receipt } }, ['name']);
+  return true;
+}), { env });
+
+/** Close only recorded process objects; unknown effects retain the original row and a concurrent new owner is never overwritten. */
+export function stopConnector(name, { source, child = false, env = process.env, read = connectorState, stop = stopOwnedProcess,
+  retain = (expected, receipt) => retainConnectorClosure(name, expected, receipt, env),
+  commit = (expected, receipt) => withMachine((m) => m.transaction(() => {
+    const row = m.connectorOf(name), current = recordOf(row);
+    if (!sameConnectorOwner(current, expected) || canonicalJSON(current) !== canonicalJSON(expected)) return false;
+    const stoppedAt = new Date(m.now()).toISOString();
+    m.upsert('connectors', { name, state: 'stopped', pid: null, public_url: null, updated_at: m.now(),
+      config_json: { ...(row.config ?? {}), pid: null, childPid: null, connected: false, stoppedAt, stopReceipt: receipt } }, ['name']);
+    return true;
+  }), { env }) } = {}) {
+  let original;
+  try { original = read(name, env); } catch (error) { return { ok: false, effectState: 'unknown', reason: 'connector-state-unreadable', error: String(error?.message ?? error) }; }
+  if (!original) return { ok: false, effectState: 'unknown', reason: 'connector-custody-missing' };
+  if (original.source !== source) return { ok: false, effectState: 'none', reason: 'connector-source-conflict', custody: original };
+  const prior = original.stopReceipt;
+  if (original.state === 'stopped' && closedProcess(prior?.manager, original.processIdentity)
+      && (!child || closedChild(prior?.child, original)))
+    return { ok: true, already: true, effectState: 'completed', stopped: original.processIdentity.pid, receipt: prior };
+  const identity = original.processIdentity;
+  if (!identity || identity.pid !== original.pid) return { ok: false, effectState: 'none', reason: 'connector-process-custody-required', custody: original };
+  let manager;
+  if (closedProcess(prior?.manager, identity)) manager = prior.manager;
+  else { try { manager = stop(identity); } catch (error) { manager = { ok: false, error: String(error?.message ?? error) }; } }
+  if (!closedProcess(manager, identity)) return { ok: false, effectState: manager?.outcome === 'refused' ? 'none' : 'unknown',
+    reason: 'connector-manager-closure-unverified', custody: original, receipt: { manager } };
+  let current;
+  try { current = read(name, env); } catch (error) { return { ok: false, effectState: 'unknown', reason: 'connector-state-unreadable', custody: original, receipt: { manager }, error: String(error?.message ?? error) }; }
+  if (!sameConnectorOwner(current, original)) return { ok: false, effectState: 'unknown', reason: 'connector-owner-changed', custody: original, receipt: { manager } };
+  if (child) {
+    try {
+      if (retain(current, { manager, child: current.stopReceipt?.child ?? null }) !== true)
+        return { ok: false, effectState: 'unknown', reason: 'connector-stop-record-refused', custody: current, receipt: { manager } };
+      current = read(name, env);
+      if (!sameConnectorOwner(current, original)) return { ok: false, effectState: 'unknown', reason: 'connector-owner-changed', custody: original, receipt: { manager } };
+    } catch (error) { return { ok: false, effectState: 'unknown', reason: 'connector-stop-record-refused', custody: current, receipt: { manager }, error: String(error?.message ?? error) }; }
+  }
+  let childReceipt = null;
+  if (child) {
+    if (closedChild(current.stopReceipt?.child, current)) childReceipt = current.stopReceipt.child;
+    else if (!current.childPid) {
+      if (!closedChild(current.childClosure, current)) return { ok: false, effectState: 'unknown', reason: 'connector-child-custody-unverified', custody: current, receipt: { manager } };
+      childReceipt = current.childClosure;
+    } else {
+      if (!current.childIdentity || current.childIdentity.pid !== current.childPid)
+        return { ok: false, effectState: 'unknown', reason: 'connector-child-custody-unverified', custody: current, receipt: { manager } };
+      try { childReceipt = { ...stop(current.childIdentity), launchNonce: current.childLaunchNonce }; } catch (error) { childReceipt = { ok: false, error: String(error?.message ?? error) }; }
+      if (!closedProcess(childReceipt, current.childIdentity)) return { ok: false, effectState: 'unknown',
+        reason: 'connector-child-closure-unverified', custody: current, receipt: { manager, child: childReceipt } };
+    }
+  }
+  const receipt = { manager, child: childReceipt };
+  try {
+    if (child) {
+      if (retain(current, receipt) !== true) return { ok: false, effectState: 'unknown', reason: 'connector-stop-record-refused', custody: current, receipt };
+      current = read(name, env);
+      if (!sameConnectorOwner(current, original) || !closedChild(current?.stopReceipt?.child, current))
+        return { ok: false, effectState: 'unknown', reason: 'connector-owner-changed', custody: original, receipt };
+    }
+    if (commit(current, receipt) !== true) return { ok: false, effectState: 'unknown', reason: 'connector-stop-record-refused', custody: current, receipt };
+  } catch (error) { return { ok: false, effectState: 'unknown', reason: 'connector-stop-record-refused', custody: current, receipt, error: String(error?.message ?? error) }; }
+  return { ok: true, effectState: 'completed', stopped: original.pid, receipt };
+}
+
+/** One connector log line in machine_logs (actor connector, kind `<source>.<kind>`). Never throws. */
+export const connectorLog = (source, msg, { env = process.env, level = 'info', kind = 'log', data = null } = {}) =>
+  machineLog({ actor: 'connector', kind: `${source}.${kind}`, msg: String(msg), level, data }, { env });
+
+/** Launch `node <script> ...args` detached from this process, output discarded. */
+export const spawnDetached = (script, args = [], { env = process.env } = {}) => {
+  const child = spawnNode([script, ...args], { detached: true, stdio: 'ignore', cwd: skillRoot, env });
+  child.unref();
+  return child.pid ?? null;
+};
+
+
+
+
+/**
+ * The repositories whose ledgers the connectors read. `connectors.repos` when the owner listed any
+ * (relative entries resolve against the source root); otherwise the source root itself plus the Work
+ * owner of every .workspaces/projects/<p>/work.json binding — each kept only when it holds a ledger.
+ */
+export function askRepos(connectors, { env = process.env, extra = [] } = {}) {
+  const source = starciSourceRoot(env);
+  const listed = (connectors?.repos ?? []).map((repo) => path.resolve(source, repo));
+  let candidates = listed;
+  if (!listed.length) {
+    candidates = [source];
+    const projects = path.join(source, '.workspaces', 'projects');
+    let entries = [];
+    try { entries = fs.readdirSync(projects, { withFileTypes: true }); } catch { /* no bindings */ }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const doc = readJsonFile(path.join(projects, entry.name, 'work.json'));
+      const rel = doc?.schema === 'starci/workspace-binding@2' ? doc?.repository?.pathFromSource : null;
+      if (typeof rel === 'string' && rel.trim()) candidates.push(path.resolve(source, rel));
+    }
+  }
+  const seen = new Set(), out = [];
+  for (const repo of [...candidates, ...extra.map((r) => path.resolve(r))]) {
+    const key = process.platform === 'win32' ? repo.toLowerCase() : repo;
+    if (seen.has(key) || !hasLedger(repo)) continue;
+    seen.add(key); out.push(repo);
+  }
+  return out;
+}
+
+/** The nonce path segment serve-ask binds (`/a-<hex>`). */
+export const NONCE = /^a-[0-9a-f]{8,64}$/;
+const nonceOf = (url) => {
+  try { const first = new URL(url).pathname.split('/')[1] ?? ''; return NONCE.test(first) ? first : null; } catch { return null; }
+};
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+const isLoopbackUrl = (url) => {
+  try { const u = new URL(url); return u.protocol === 'http:' && LOOPBACK.has(u.hostname); } catch { return false; }
+};
+/** A credential ask names custody files or env variables to fill (serve-ask payload.fields). */
+const isCredentialAsk = (fields) => Boolean((fields?.files?.length ?? 0) + (fields?.vars?.length ?? 0));
+
+const parse = parseJson;
+
+/**
+ * Every ask whose serve-ask form is still open in one ledger, newest serving per dispatch:
+ * not answered, not expired or superseded after it was served, and inside its ttl.
+ */
+export function servingAsks(db, { now = Date.now() } = {}) {
+  const rows = db.prepare(`SELECT seq, workflow_id, payload_json, created_at FROM events WHERE kind='ask-serving' ORDER BY seq DESC`).all();
+  const seen = new Set(), out = [];
+  const closedAfter = db.prepare(`SELECT 1 FROM events WHERE workflow_id=? AND json_extract(payload_json,'$.dispatchId')=?
+    AND (kind='ask-answered' OR (kind IN ('ask-serving-expired','ask-superseded') AND seq>?)) LIMIT 1`);
+  for (const row of rows) {
+    const payload = parse(row.payload_json, {}) ?? {};
+    const dispatchId = payload.dispatchId;
+    if (!dispatchId || seen.has(`${row.workflow_id}\u0000${dispatchId}`)) continue;
+    seen.add(`${row.workflow_id}\u0000${dispatchId}`);
+    if (closedAfter.get(row.workflow_id, dispatchId, row.seq)) continue;
+    const ask = servingRecord(row, payload, now);
+    if (ask) out.push(ask);
+  }
+  return out;
+}
+
+// One ask-serving row as an open form, or null: past its ttl, not a loopback nonce URL, or its
+// recorded serve-ask process is gone (the form stops being served the moment its process exits).
+function servingRecord(row, payload, now) {
+  if (Number.isFinite(payload.ttlMs) && row.created_at + payload.ttlMs <= now) return null;
+  const nonce = nonceOf(payload.url);
+  if (!nonce || !isLoopbackUrl(payload.url)) return null;
+  if (Number.isInteger(payload.pid) && !pidAlive(payload.pid)) return null;
+  return {
+    seq: row.seq, workflowId: row.workflow_id, dispatchId: payload.dispatchId, url: payload.url, nonce, pid: payload.pid ?? null,
+    fields: payload.fields ?? { files: [], vars: [] }, credential: isCredentialAsk(payload.fields), onDemand: payload.onDemand === true,
+    createdAt: row.created_at, expiresAt: Number.isFinite(payload.ttlMs) ? row.created_at + payload.ttlMs : null,
+  };
+}
+
+/**
+ * One filed ask as the owner-facing connectors see it (read-only on `db`): {workflowId, dispatchId,
+ * opId, title, question, closed, serving}, or null when no ask report was filed for it. `closed` is
+ * 'answered', 'superseded' (retired, and not re-parked since: a later ask-notified or ask-serving
+ * reopens it), else null. `serving` is the live form (servingAsks' rules) or null: an open ask
+ * with no live form is healthy, its link is generated on demand from Telegram.
+ */
+export function askState(db, workflowId, dispatchId, { now = Date.now() } = {}) {
+  const report = db.prepare("SELECT a.op_id,r.job_id,r.report_json FROM reports r JOIN op_attempts a ON a.attempt_id=r.attempt_id WHERE r.workflow_id=? AND r.dispatch_id=? AND r.outcome='ask' ORDER BY r.report_id DESC LIMIT 1").get(workflowId, dispatchId);
+  if (!report) return null;
+  const last = (kinds) => db.prepare(`SELECT seq, payload_json, created_at FROM events WHERE workflow_id=? AND kind IN (${kinds.map(() => '?').join(',')})
+    AND json_extract(payload_json,'$.dispatchId')=? ORDER BY seq DESC LIMIT 1`).get(workflowId, ...kinds, dispatchId) ?? null;
+  const answered = last(['ask-answered']), superseded = last(['ask-superseded']), reopened = last(['ask-serving', 'ask-notified']);
+  const closed = answered ? 'answered' : superseded && !(reopened && reopened.seq > superseded.seq) ? 'superseded' : null;
+  let serving = null;
+  const row = last(['ask-serving']);
+  if (!closed && row) {
+    const ended = last(['ask-serving-expired', 'ask-superseded']);
+    if (!(ended && ended.seq > row.seq)) serving = servingRecord({ ...row, workflow_id: workflowId }, parse(row.payload_json, {}) ?? {}, now);
+  }
+  const rj = parse(report.report_json, {}) ?? {};
+  return {
+    // title: the workflow's display name (starci kernel rename / define-goal), else its goal slug; jobName: the asking
+    // op job's `<op label> · <what> · <workflow name>` (scripts/lib/display-names.mjs).
+    workflowId, dispatchId, opId: report.op_id ?? null, title: workflowNameOf(db, workflowId), jobName: askJobName(db, workflowId, report),
+    question: rj.question ?? { text: rj.summary ?? '', options: [] }, closed, serving,
+  };
+}
+
+/** The display name of the op job that filed an ask report, or null. */
+const askJobName = (db, workflowId, report) => {
+  try {
+    const job = db.prepare("SELECT * FROM jobs WHERE workflow_id=? AND job_id=? AND kind<>'kernel' LIMIT 1")
+      .get(workflowId, report.job_id);
+    return job ? jobDisplayNameOf(db, job) : null;
+  } catch { return null; }
+};
+
+/** Every open ask of one ledger (askState with closed null), newest report first, in live workflows only. */
+export function openAskList(db, { now = Date.now() } = {}) {
+  const rows = db.prepare(`SELECT r.workflow_id, r.dispatch_id FROM reports r JOIN workflows w ON w.workflow_id=r.workflow_id
+    WHERE r.outcome='ask' AND w.archived_at IS NULL AND (w.phase IS NULL OR w.phase<>'finished') ORDER BY r.report_id DESC`).all();
+  const seen = new Set(), out = [];
+  for (const row of rows) {
+    const id = `${row.workflow_id}\u0000${row.dispatch_id}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const state = askState(db, row.workflow_id, row.dispatch_id, { now });
+    if (state && !state.closed) out.push(state);
+  }
+  return out;
+}
+
+/** The repos the Telegram ask notices name (notifications kind 'ask'), so the gateway can route their forms. */
+export const notifiedRepos = (env = process.env) => readMachine((m) => [...new Set(m.db.prepare("SELECT json_extract(ref,'$.repo') repo FROM notifications WHERE kind='ask' AND json_valid(ref)").all()
+  .map((r) => r.repo).filter((r) => typeof r === 'string' && r))], [], { env });
+
+/** Open one repo's ledger read-only for `fn`, always closing it; a missing or unreadable ledger yields `fallback`. */
+export function withLedgerRead(repo, fn, fallback = null) {
+  let handle = null;
+  try { handle = inspectLedger({ file: ledgerFileFor(repo) }); } catch { return fallback; }
+  try { return fn(handle.db); } finally { try { handle.close(); } catch { /* closed */ } }
+}
+
+/** Open asks across repos, each tagged with its repo. */
+export const servingAsksAcross = (repos, opts = {}) =>
+  repos.flatMap((repo) => withLedgerRead(repo, (db) => servingAsks(db, opts).map((ask) => ({ ...ask, repo })), []));
+
+/** The owner config, or null when it cannot be read (a connector never dies on a broken file it only observes). */
+export const ownerConfig = () => { try { return loadConfig(); } catch { return null; } };
+
+export const argsOf = (argv) => {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (!k.startsWith('--')) { out._.push(k); continue; }
+    const key = k.slice(2), next = argv[i + 1];
+    let value = true;
+    if (next !== undefined && !next.startsWith('--')) { value = next; i++; }
+    out[key] = key in out ? [].concat(out[key], value) : value;
+  }
+  return out;
+};

package/runtime/scripts/hfs/architecture/fe-slot-allows.mjs

@@ -10,7 +10,7 @@ import { isFeTestPath } from '../rules/fe-no-tests.mjs';
  * root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
  * Files no slot owns are HFS_PATH_NO_SLOT's (`starci app check`), so together every front-end file is placed by exactly one slot and
  * named by it. A test path (a `.spec.tsx` or `.test.tsx` beside a component, a test directory or test tooling) is FE_NO_TESTS's
- * (R97, contract-change fe-no-tests): that rule is the one finding of such a file, so this check leaves it alone, as
+ * (R97 FE_NO_TESTS): that rule is the one finding of such a file, so this check leaves it alone, as
  * HFS_PATH_NO_SLOT does (scripts/hfs/path-findings.mjs).
  */
 export const FE_SLOT_ALLOWS_RULE_IDS = ['FE_SLOT_FILE_ROLE'];

package/runtime/scripts/hfs/secret.mjs

@@ -12,11 +12,19 @@
 // Exit 0 done, 2 a refusal or bad usage (a secret value is never part of a message).
 import fs from 'node:fs';
 import path from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { runProgram } from '../api/process/run-program.mjs';
+import { resolveRealTool } from '../api/process/resolve-real-tool.mjs';
+const sopsInvocation = Object.freeze({runProgram,resolveRealTool});
+import { randomBytes, randomUUID } from 'node:crypto';
+import { claimManager } from '../connectors/lib.mjs';
+import { sha256 } from '../../engine/digest.mjs';
+import { isSopsEnvelope } from '../lib/sops-envelope.mjs';
 import { decrypt as sopsDecrypt } from '../api/sops/decrypt.mjs';
 import { seal as sopsSeal } from '../api/sops/seal.mjs';
 
 class SecretError extends Error {}
+// claimManager is process-owned; refuse a recursive same-process write as well.
+const writingSecrets = new Set();
 
 const SLUG = /^[a-z0-9][a-z0-9-]*$/u;
 const KEY = /^[A-Za-z_][A-Za-z0-9_]*$/u;
@@ -75,18 +83,19 @@ const fileOf = (directory, slug) => {
 /** The default sops seam: the runtime's sops api, which finds the binary on this machine. */
 function defaultSops(env = process.env) {
   const refuse = (what, result) => {
+    if (result.error?.identityRefusal) return Object.assign(new SecretError(result.error.message), { identityRefusal: result.error.identityRefusal });
     if (result.error?.code === 'SOPS_MISSING') return new SecretError(result.error.message);
     return new SecretError(`sops could not ${what} (exit ${String(result.status)})`);
   };
   return {
     decrypt(file, format) {
-      const result = sopsDecrypt(null, ['decrypt', '--input-type', format, '--output-type', 'json', file], { env });
+      const result = sopsDecrypt(null, ['decrypt', '--input-type', format, '--output-type', 'json', file], { env, invocation: sopsInvocation });
       if (result.status !== 0) throw refuse(`decrypt ${path.basename(file)}; is the age identity installed?`, result);
-      return JSON.parse(result.stdout);
+      try { return JSON.parse(result.stdout); } catch { throw new SecretError('sops returned an invalid plaintext document'); }
     },
     seal(request) {
-      const result = sopsSeal(null, request, { env });
-      if (result.status !== 0) throw refuse(`seal the secret: ${String(result.stderr).trim().split(String.fromCharCode(10)).at(-1)}`, result);
+      const result = sopsSeal(null, request, { env, invocation: sopsInvocation });
+      if (result.status !== 0) throw refuse('seal the secret', result);
       return result.stdout;
     },
   };
@@ -109,8 +118,15 @@ function parse(argv) {
 const readStdin = () => fs.readFileSync(0, 'utf8');
 
 /** Seal `key = value` into the secret `slug`: an existing document keeps its other keys and its recipients. */
-function writeSecret({ file, key, value, age, sops }) {
-  if (!KEY.test(key)) throw new SecretError(`${key} is not a key name`);
+function writeSecret({ file, values, age, sops, processEnv = process.env }) {
+  for (const key of Object.keys(values)) if (!KEY.test(key)) throw new SecretError(`${key} is not a key name`);
+  const absolute = path.resolve(file), target = process.platform === 'win32' ? absolute.toLowerCase() : absolute;
+  const name = `sealed-secret-${sha256(target)}`;
+  if (writingSecrets.has(name)) throw new SecretError('the sealed secret is being updated; retry after that write settles');
+  const held = claimManager(name, { env: processEnv });
+  if (!held.ok) throw new SecretError('the sealed secret is being updated; retry after that write settles');
+  writingSecrets.add(name);
+  try {
   let format = 'json';
   let map = {};
   let recipients = age;
@@ -121,10 +137,28 @@ function writeSecret({ file, key, value, age, sops }) {
     map = sops.decrypt(file, format);
     if (!age.length) recipients = envelope.recipients;
   }
-  map[key] = value;
+  Object.assign(map, values);
   const sealed = sops.seal({ inputType: format, plaintext: plaintextOf(format, map), recipients, filenameOverride: file });
+  let parsed;
+  try { parsed = envelopeOf(sealed); } catch { throw new SecretError('sops returned an invalid sealed document'); }
+  if (!isSopsEnvelope(sealed) || parsed.keys.length !== Object.keys(map).length || !parsed.keys.every(key => Object.hasOwn(map, key))) throw new SecretError('sops returned an invalid sealed document');
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, sealed);
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}-${randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, sealed, { flag: 'wx', mode: 0o600, flush: true });
+    fs.renameSync(temporary, file);
+  } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
+  } finally { writingSecrets.delete(name); held.release(); }
+}
+
+/** Update named keys through the same canonical sealed-secret owner used by the CLI. */
+export function setSecretValues(repoRoot, { slug, values, env = null }, { sops = null, age = [], processEnv = process.env } = {}) {
+  const directory = secretsDirectory(repoRoot, env);
+  const file = fileOf(directory, slug);
+  if (!values || typeof values !== 'object' || Array.isArray(values) || !Object.keys(values).length) throw new SecretError('secret update requires named values');
+  for (const value of Object.values(values)) if (typeof value !== 'string' || value === '') throw new SecretError('secret values must be nonempty strings');
+  writeSecret({ file, values, age, sops: sops ?? defaultSops(processEnv), processEnv });
+  return { file, via: 'sealed-secret' };
 }
 
 /** `starci app secret <verb> ...`; `stdin` returns the value `set` seals, `sops` and `random` are test seams. */
@@ -159,13 +193,13 @@ export function secretMain(argv, { stdout = (s) => process.stdout.write(s), stde
     if (verb === 'set') {
       const value = String(stdin()).replace(/\r?\n$/u, '');
       if (value === '') throw new SecretError('the value on stdin is empty');
-      writeSecret({ file, key, value, age: opts.age, sops: seam });
+      writeSecret({ file, values: { [key]: value }, age: opts.age, sops: seam, processEnv: env });
       stdout(`sealed ${opts.positional[0]} (${key})\n`);
       return 0;
     }
     const bytes = opts.bytes === undefined ? 32 : Number(opts.bytes);
     if (!Number.isInteger(bytes) || bytes < 16 || bytes > 1024) throw new SecretError('--bytes is a whole number from 16 to 1024');
-    writeSecret({ file, key, value: random(bytes).toString('base64url'), age: opts.age, sops: seam });
+    writeSecret({ file, values: { [key]: random(bytes).toString('base64url') }, age: opts.age, sops: seam, processEnv: env });
     stdout(`generated and sealed ${opts.positional[0]} (${key}, ${bytes} bytes); read it with starci app secret show\n`);
     return 0;
   } catch (error) {