@starci/hfs 4.0.10 → 4.2.0

package/runtime/modules/models/tiers.yaml

@@ -0,0 +1,66 @@
+schema: starci/model-tiers@1
+purpose: >-
+  The ONE owner of which model takes which work. A tier is an ordered chain of members (agent + model, optional
+  effort); the first member with tokens is taken. Tiers are named by capability. A model may sit in several tiers.
+  Adding a tier or a member is a line here (or in config.yaml models.tiers) and needs no code.
+tiers:
+  frontier:
+    - {agent: claude, model: claude-opus-5-5}
+    - {agent: codex, model: gpt-6.1-sol, effort: max}
+  high:
+    - {agent: claude, model: claude-sonnet-5-5}
+    - {agent: codex, model: gpt-6.1-sol, effort: high}
+  medium:
+    - {agent: devin, model: swe-2-max}
+    - {agent: codex, model: gpt-6.1-sol, effort: medium}
+  low:
+    - {agent: devin, model: swe-2-max}
+    - {agent: codex, model: gpt-6-luna, effort: low}
+  imagegen:
+    - {agent: codex, model: gpt-6.1-sol, effort: high}
+# Highest first: a provider with no frontier member takes its member of the first tier that has one.
+tierOrder: [frontier, high, medium, low]
+# Seat -> tier. A seat is a long-lived agent role; an op takes the tier of its difficulty.
+seats:
+  supervisor: frontier
+  planner: frontier
+  validator: frontier
+  kernelManager: frontier
+  kernel: high
+  worker: high
+  critic: frontier
+# The kernel's own model calls (selection.yaml kernelFunctionKinds) take the tier of their seat.
+kindSeats:
+  model.assessGoal: planner
+  model.planOp: planner
+  model.decide: kernelManager
+  model.manageWorkflow: kernelManager
+  model.validateOp: validator
+  model.critiqueGoal: validator
+  model.classifyScreen: kernelManager
+  model.presentOwnerQuestion: kernelManager
+  judge: validator
+difficulty:
+  insane: frontier
+  hard: high
+  medium: medium
+  easy: low
+# A kind named here takes that tier whatever its difficulty; the drawing ops take the tier of their difficulty like every core op.
+kindTiers: {}
+# A tier no seat and no op takes: only a headless call made by one op is made on it (`calls`). A tier not named here is a seat tier.
+tierUse:
+  imagegen: call
+# Headless calls: the call tier whose chain the call is picked from (the same picker: hard filter, bias, balance, token use),
+# the longest one call may run, and the most images and reference images it takes.
+calls:
+  imagegen: {tier: imagegen, timeoutMs: 600000, maxImages: 8, maxReferences: 6}
+# Balance over the recent picks of one tier, running seats included.
+balance:
+  maxStreak: 3
+  maxSharePercent: 70
+# Token use of the chosen member, in percent of its most used quota window. Automatic picks skip a member at
+# `reservePercent`; an owner bias naming the member keeps it usable up to `biasPercent`; `exhaustedPercent` is never used.
+usage:
+  reservePercent: 90
+  biasPercent: 95
+  exhaustedPercent: 100

package/runtime/scripts/api/fs/claim-file.mjs

@@ -0,0 +1,30 @@
+// claim-file.mjs — an exclusive writer claim on one file: a lock file beside it names the claiming process, so two processes never rewrite the same file at once
+// (the sealed secret writer, scripts/hfs/secret.mjs). The claim of a process that no longer exists is replaced.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pidAlive } from '../../lib/pid-alive.mjs';
+
+const UNREADABLE_HELD_MS = 10_000;
+const holderOf = (lock) => {
+  try { const pid = JSON.parse(fs.readFileSync(lock, 'utf8')).pid; return Number.isInteger(pid) ? pid : null; } catch { return null; }
+};
+/** A lock a claimant created but has not yet written is held for a moment: only an old unreadable lock is a crashed claim. */
+const freshlyCreated = (lock) => { try { return Date.now() - fs.statSync(lock).mtimeMs < UNREADABLE_HELD_MS; } catch { return false; } };
+
+/** {ok: true, release} once this process holds the claim of `file`; {ok: false, holder} while a live process (this one included) holds it. `pid` is the claiming process. */
+export function claimFile(file, { pid = process.pid } = {}) {
+  const lock = path.join(path.dirname(file), `.${path.basename(file)}.lock`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fs.writeFileSync(lock, JSON.stringify({ pid }), { flag: 'wx', mode: 0o600 });
+      return { ok: true, release: () => { if (holderOf(lock) === pid) fs.rmSync(lock, { force: true }); } };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const holder = holderOf(lock);
+      if (holder !== null ? pidAlive(holder) : freshlyCreated(lock)) return { ok: false, holder };
+      fs.rmSync(lock, { force: true });
+    }
+  }
+  return { ok: false, holder: null };
+}

package/runtime/scripts/api/fs/ensure-temp-root.mjs

@@ -0,0 +1,27 @@
+// ensure-temp-root.mjs — the temp root exists and takes writes before anything is placed in it or a child is started with TEMP/TMP/TMPDIR pointing at it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { tempRoot, TEMP_ROOT_ENV } from '../../../engine/temp-root.mjs';
+
+const TEMP_ROOT_UNUSABLE = 'TEMP_ROOT_UNUSABLE';
+const writable = new Set();
+
+const unusable = (root, reason) => Object.assign(new Error(`${TEMP_ROOT_UNUSABLE}: the temp root ${root} ${reason}; set roots.temp in config.yaml (or ${TEMP_ROOT_ENV}) to a directory the runtime can create and write - it is not replaced by the operating-system temp directory`), { code: TEMP_ROOT_UNUSABLE, root });
+
+/** Writes and removes one probe file in `root`: a directory that exists can still refuse writes. */
+function probeWritable(root) {
+  const probe = path.join(root, `.starci-write-probe-${process.pid}`);
+  fs.writeFileSync(probe, '');
+  fs.rmSync(probe, { force: true });
+}
+
+/** The temp root of `env`, created when it is missing. Throws an Error with code TEMP_ROOT_UNUSABLE when it cannot be created or written. */
+export function ensureTempRoot({ env = process.env } = {}) {
+  const root = tempRoot({ env });
+  try {
+    fs.mkdirSync(root, { recursive: true });
+    if (!writable.has(root)) probeWritable(root);
+  } catch (error) { throw unusable(root, `cannot be created or written (${error.code ?? error.message})`); }
+  writable.add(root);
+  return root;
+}

package/runtime/scripts/api/fs/forbidden-root.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { samePath } from '../../lib/path-key.mjs';
 import { realpathOr } from '../../lib/fs-kind.mjs';
+import { tempRoot } from '../../../engine/temp-root.mjs';
 
 const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
@@ -37,7 +38,7 @@ function strictlyInsideReal(p, root) {
 export function forbiddenRoot(p, { checkoutsUnder = null, hold } = {}) {
   const resolved = path.resolve(p);
   if (path.parse(resolved).root === resolved || samePath(path.dirname(resolved), resolved)) return 'a filesystem root';
-  for (const [name, dir] of [['the home directory', os.homedir()], ['the temp directory', os.tmpdir()], ['the runtime', SKILL_ROOT],
+  for (const [name, dir] of [['the home directory', os.homedir()], ['the temp directory', os.tmpdir()], ['the configured temp root', tempRoot()], ['the runtime', SKILL_ROOT],
     ['the repository hosting the runtime', path.dirname(SKILL_ROOT)], ['the repositories root', path.dirname(path.dirname(SKILL_ROOT))]]) {
     if (dir && samePath(path.resolve(dir), resolved)) return name;
   }

package/runtime/scripts/api/fs/make-temp-dir.mjs

@@ -0,0 +1,11 @@
+// make-temp-dir.mjs — a fresh temporary directory under the temp root (engine/temp-root.mjs tempRoot).
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureTempRoot } from './ensure-temp-root.mjs';
+
+/** A new directory `<prefix><random>` under `parent` (default the temp root, ensureTempRoot: TEMP_ROOT_UNUSABLE when it cannot be made), which is created when it is missing. */
+export function makeTempDir(prefix, { env = process.env, parent = undefined } = {}) {
+  const root = parent ?? ensureTempRoot({ env });
+  fs.mkdirSync(root, { recursive: true });
+  return fs.mkdtempSync(path.join(root, prefix));
+}

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

@@ -41,7 +41,7 @@ const retrying = (fn, retries) => {
 };
 const removeFile = (p, retries) => retrying(() => {
   try { fs.unlinkSync(p); } catch (error) {
-    if (WIN && (error?.code === 'EPERM' || error?.code === 'EACCES')) { fs.chmodSync(p, 0o666); fs.unlinkSync(p); } else throw error;
+    if (WIN && (error?.code === 'EPERM' || error?.code === 'EACCES')) { fs.chmodSync(p, 0o600); fs.unlinkSync(p); } else throw error;
   }
 }, retries);
 
@@ -65,40 +65,57 @@ export function safeRemove(root, { retries = 5, checkoutsUnder = null, hold } =
   // the root itself or strictly under the root's real path. A link is unlinked above (the link only); any other
   // entry that resolves outside the tree is refused, whatever made it look like a plain entry.
   const rootReal = realpathOr(target);
-  const insideRoot = (p) => { const real = realpathOr(p); if (!real || !rootReal) return false; if (same(real, rootReal)) return true;
-    const rel = path.relative(rootReal, real); return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel); };
-  const walk = (dir, st, parentReal) => {
-    if (isLinkLike(dir, { parentReal, stat: st })) {
-      if (unlinkOnly(dir)) { out.removed.links += 1; return true; }
-      fail(dir, { code: 'LINK_STUCK', message: 'a link could not be unlinked; nothing above it is removed' });
-      return false;
-    }
-    if (!insideRoot(dir)) {
-      fail(dir, { code: 'OUTSIDE_ROOT', message: `refusing to delete ${dir}: its real path ${realpathOr(dir) ?? '?'} is outside ${rootReal ?? target}` });
-      return false;
-    }
-    if (!st.isDirectory()) {
-      const error = removeFile(dir, retries);
-      if (error) { fail(dir, error); return false; }
-      out.removed.files += 1; return true;
-    }
-    const real = realpathOr(dir);
-    if (!real) { fail(dir, { code: 'REALPATH', message: 'cannot resolve the directory' }); return false; }
-    let entries;
-    try { entries = fs.readdirSync(dir); } catch (error) { fail(dir, error); return false; }
-    let clear = true;
-    for (const name of entries) {
-      const child = path.join(dir, name);
-      let childStat;
-      try { childStat = fs.lstatSync(child); } catch (error) { if (error?.code !== 'ENOENT') { fail(child, error); clear = false; } continue; }
-      if (!walk(child, childStat, real)) clear = false;
-    }
-    if (!clear) return false;
-    const error = retrying(() => fs.rmdirSync(dir), retries);
-    if (error) { fail(dir, error); return false; }
-    out.removed.dirs += 1; return true;
-  };
-  walk(target, st, null);
+  const ctx = { out, fail, retries, rootReal, target };
+  walk(ctx, target, st, null);
   out.ok = !fs.existsSync(target) && (() => { try { fs.lstatSync(target); return false; } catch { return true; } })();
   return out;
 }
+
+function insideRoot({ rootReal }, p) {
+  const real = realpathOr(p);
+  if (!real || !rootReal) return false;
+  if (same(real, rootReal)) return true;
+  const rel = path.relative(rootReal, real);
+  return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// Removes each child of `dir` (real path `real`); false when any child stays.
+function removeChildren(ctx, dir, entries, real) {
+  let clear = true;
+  for (const name of entries) {
+    const child = path.join(dir, name);
+    let childStat;
+    try { childStat = fs.lstatSync(child); } catch (error) { if (error?.code !== 'ENOENT') { ctx.fail(child, error); clear = false; } continue; }
+    if (!walk(ctx, child, childStat, real)) clear = false;
+  }
+  return clear;
+}
+
+function walkDirectory(ctx, dir) {
+  const { out, fail, retries } = ctx;
+  const real = realpathOr(dir);
+  if (!real) { fail(dir, { code: 'REALPATH', message: 'cannot resolve the directory' }); return false; }
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch (error) { fail(dir, error); return false; }
+  if (!removeChildren(ctx, dir, entries, real)) return false;
+  const error = retrying(() => fs.rmdirSync(dir), retries);
+  if (error) { fail(dir, error); return false; }
+  out.removed.dirs += 1; return true;
+}
+
+function walk(ctx, dir, st, parentReal) {
+  const { out, fail, retries, rootReal, target } = ctx;
+  if (isLinkLike(dir, { parentReal, stat: st })) {
+    if (unlinkOnly(dir)) { out.removed.links += 1; return true; }
+    fail(dir, { code: 'LINK_STUCK', message: 'a link could not be unlinked; nothing above it is removed' });
+    return false;
+  }
+  if (!insideRoot(ctx, dir)) {
+    fail(dir, { code: 'OUTSIDE_ROOT', message: `refusing to delete ${dir}: its real path ${realpathOr(dir) ?? '?'} is outside ${rootReal ?? target}` });
+    return false;
+  }
+  if (st.isDirectory()) return walkDirectory(ctx, dir);
+  const error = removeFile(dir, retries);
+  if (error) { fail(dir, error); return false; }
+  out.removed.files += 1; return true;
+}

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

@@ -7,8 +7,12 @@
 // (diff.mjs, ls-files.mjs, worktree-*.mjs, ...), and a caller folds the spawn result it gets back with the pure
 // helpers of scripts/lib/git.mjs (gitResultOf, gitOutputOf).
 import { assertMutationFence } from '../../lib/mutation-fence.mjs';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
+import { withTempEnv } from '../../../engine/temp-root.mjs';
 
 /**
  * Spawn `file` (the git binary) once with `args`: utf8 text, a hidden window, never a shell.
@@ -20,7 +24,8 @@ export const gitSpawn = (file, args, options = {}) => {
   assertMutationFence({ kind: 'git-effect', args });
   const spawn = { encoding: 'utf8', windowsHide: true, ...options };
   if (spawn.encoding === 'buffer') spawn.encoding = null;
-  return spawnSync(file, args, spawn);
+  // tempChildEnv copies the env (node adds NODE_V8_COVERAGE to the env object it is given: a frozen caller env must not throw under coverage) and points TEMP/TMP/TMPDIR at the temp root
+  return spawnSync(file, args, withTempEnv(spawn));
 };
 
 /**
@@ -42,3 +47,31 @@ export const gitRunner = (git = null) => (args, opts = {}) => {
   const r = git ? git(args, opts) : runGit(args, { timeout: 300_000, maxBuffer: 64 * 1024 * 1024, ...opts });
   return { ok: r?.ok ?? (!r?.error && r?.status === 0), stdout: String(r?.stdout ?? r?.out ?? '').trim(), stderr: String(r?.stderr ?? r?.err ?? r?.error?.message ?? r?.error ?? '').trim() };
 };
+
+let cachedGit;
+const gitPathOf = ({ env, platform, home, exists }) => {
+  const p = platform === 'win32' ? path.win32 : path.posix;
+  const pathKey = Object.keys(env).find((name) => name.toLowerCase() === 'path');
+  const shim = p.join(home, '.starci', 'bin');
+  const same = (a, b) => (platform === 'win32' ? p.resolve(a).toLowerCase() === p.resolve(b).toLowerCase() : p.resolve(a) === p.resolve(b));
+  const binary = platform === 'win32' ? 'git.exe' : 'git';
+  for (const raw of String(pathKey ? env[pathKey] : '').split(platform === 'win32' ? ';' : ':')) {
+    const dir = raw.replace(/^"(.*)"$/, '$1');
+    const file = dir && p.isAbsolute(dir) && !same(dir, shim) ? p.join(dir, binary) : null;
+    if (file && exists(file)) return file;
+  }
+  return null;
+};
+/**
+ * The absolute path of the real git binary, or null: the first PATH directory holding git (git.exe on Windows) that is not
+ * the StarCi shim directory <home>/.starci/bin (a seat's guard shim is never the git the runtime itself runs). A bare name is never
+ * spawned, so a writable directory cannot be reached by name lookup at spawn time. Resolved once per process; options (env,
+ * platform, home, exists) are for a spec and bypass the cache.
+ */
+export const gitExecutable = (options = null) => {
+  if (!options && cachedGit !== undefined) return cachedGit;
+  const { env = process.env, platform = process.platform, home = os.homedir(), exists = (file) => fs.statSync(file, { throwIfNoEntry: false })?.isFile() === true } = options ?? {};
+  const found = gitPathOf({ env, platform, home, exists });
+  if (!options) cachedGit = found;
+  return found;
+};

package/runtime/scripts/api/process/resolve-real-tool.mjs

@@ -22,6 +22,18 @@ const executableNames = (program, { env, platform }) => {
   return [...new Set(names)];
 };
 
+const firstExecutableHit = (entry, names, stat, realpath) => {
+  for (const executable of names) {
+    const candidate = path.join(entry, executable);
+    try {
+      if (stat(candidate).isFile()) {
+        try { return realpath(candidate); } catch { return path.resolve(candidate); }
+      }
+    } catch { /* try the next executable spelling or PATH entry */ }
+  }
+  return null;
+};
+
 /** Resolve `program` from PATH while excluding <home>/.starci/bin by canonical directory identity. */
 export function resolveRealTool(program, { env = process.env, home = os.homedir(), platform = process.platform,
   stat = fs.statSync, realpath = fs.realpathSync.native } = {}) {
@@ -33,14 +45,8 @@ export function resolveRealTool(program, { env = process.env, home = os.homedir(
   for (const rawEntry of pathValue(env).split(delimiter).filter(Boolean)) {
     const entry = rawEntry.replace(/^"(.*)"$/, '$1');
     if (canonical(entry, { platform, realpath }) === shimKey) continue;
-    for (const executable of names) {
-      const candidate = path.join(entry, executable);
-      try {
-        if (stat(candidate).isFile()) {
-          try { return realpath(candidate); } catch { return path.resolve(candidate); }
-        }
-      } catch { /* try the next executable spelling or PATH entry */ }
-    }
+    const hit = firstExecutableHit(entry, names, stat, realpath);
+    if (hit) return hit;
   }
   return null;
 }

package/runtime/scripts/api/process/run-program.mjs

@@ -2,6 +2,7 @@
 // assisted run (scripts/uat/assisted-runner.mjs), resolved to its file by scripts/uat/launch.mjs launchFor. Returns the
 // spawnSync result {status, stdout, stderr, error, signal} (utf8 text, a hidden window).
 import { spawnSync } from 'node:child_process';
+import { withTempEnv } from '../../../engine/temp-root.mjs';
 
 /** Runs `file args`; options (cwd, env, timeout, stdio, input) pass through. */
-export const runProgram = (file, args, options = {}) => spawnSync(file, args, { encoding: 'utf8', windowsHide: true, ...options });
+export const runProgram = (file, args, options = {}) => spawnSync(file, args, withTempEnv({ encoding: 'utf8', windowsHide: true, ...options }));