@sabaiway/agent-workflow-kit 10.5.0 → 11.0.0

package/tools/robustness-literals.mjs

@@ -0,0 +1,101 @@
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+
+export const KINDS = Object.freeze(['env', 'flag', 'ref', 'syscall', 'errno', 'state', 'argv']);
+const KIND_SET = new Set(KINDS);
+const TOP_KEYS = Object.freeze(['schema', 'version', 'classes']);
+const CLASS_KEYS = Object.freeze(['id', 'prove', 'members']);
+const MEMBER_KEYS = Object.freeze(['literal', 'kind', 'note', 'source']);
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const ADR = /^AD-\d+$/u;
+const CONTROL = /[\p{Cc}\u2028\u2029\uFFFD]/u;
+const SHIPPED_LIST = fileURLToPath(new URL('../references/robustness-literals.json', import.meta.url));
+
+const refuse = (code, detail) => {
+  throw Object.assign(new Error(`robustness-literals: ${code}${detail ? ` — ${detail}` : ''}`), { code });
+};
+const requireObject = (value, label) => {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) refuse('type', `${label} must be an object`);
+};
+const requireKeys = (value, keys, label) => {
+  requireObject(value, label);
+  const unknown = Object.keys(value).find((key) => !keys.includes(key));
+  if (unknown !== undefined) refuse('unknown-key', `${label}.${unknown}`);
+  const missing = keys.find((key) => !Object.hasOwn(value, key));
+  if (missing !== undefined) refuse('missing-key', `${label}.${missing}`);
+};
+const requireString = (value, label) => {
+  if (typeof value !== 'string') refuse('type', `${label} must be a string`);
+  if (value.length === 0) refuse('empty-string', label);
+  if (CONTROL.test(value)) refuse('control', label);
+};
+const isRepoSource = (source) => !source.startsWith('/') && !source.includes('\\') &&
+  !source.split('/').includes('..') && (source.includes('/') || source.includes('.'));
+const freezeList = (list) => Object.freeze({
+  ...list,
+  classes: Object.freeze(list.classes.map((entry) => Object.freeze({
+    ...entry,
+    members: Object.freeze(entry.members.map((member) => Object.freeze(member))),
+  }))),
+});
+
+const validateList = (value) => {
+  requireKeys(value, TOP_KEYS, 'list');
+  if (value.schema !== 1) refuse('schema', 'schema must be 1');
+  if (!Number.isSafeInteger(value.version) || value.version < 1) refuse('version', 'version must be an integer >= 1');
+  if (!Array.isArray(value.classes)) refuse('type', 'classes must be an array');
+  if (value.classes.length === 0) refuse('empty-class', 'classes must not be empty');
+  const ids = new Set();
+  for (const [classIndex, entry] of value.classes.entries()) {
+    const label = `classes[${classIndex}]`;
+    requireKeys(entry, CLASS_KEYS, label);
+    requireString(entry.id, `${label}.id`);
+    if (!SLUG.test(entry.id)) refuse('class-id', entry.id);
+    if (ids.has(entry.id)) refuse('duplicate-class', entry.id);
+    ids.add(entry.id);
+    requireString(entry.prove, `${label}.prove`);
+    if (!Array.isArray(entry.members)) refuse('type', `${label}.members must be an array`);
+    if (entry.members.length === 0) refuse('empty-class', entry.id);
+    const literals = new Set();
+    for (const [memberIndex, member] of entry.members.entries()) {
+      const memberLabel = `${label}.members[${memberIndex}]`;
+      requireKeys(member, MEMBER_KEYS, memberLabel);
+      for (const key of MEMBER_KEYS) requireString(member[key], `${memberLabel}.${key}`);
+      if (literals.has(member.literal)) refuse('duplicate-literal', `${entry.id}:${member.literal}`);
+      literals.add(member.literal);
+      if (!KIND_SET.has(member.kind)) refuse('kind', member.kind);
+      if (!ADR.test(member.source) && !SLUG.test(member.source) && !isRepoSource(member.source)) refuse('source', member.source);
+    }
+  }
+  return freezeList(value);
+};
+
+export const readRobustnessLiterals = (path, io = {}) => {
+  const read = readRegularFileNoFollow(path, io);
+  if (read.outcome !== 'ok') refuse('type', `${path} must be a readable regular file (${read.className ?? read.code ?? read.outcome})`);
+  try {
+    return validateList(JSON.parse(read.content));
+  } catch (error) {
+    if (error?.code) throw error;
+    refuse('type', `${path} is not valid JSON (${error.message})`);
+  }
+};
+
+export const readShippedRobustnessLiterals = (deps = {}) =>
+  readRobustnessLiterals((deps.resolvePath ?? (() => SHIPPED_LIST))(), deps.io);
+
+export const parseRobustTag = (text) => {
+  const matches = [...String(text ?? '').matchAll(/robust:(\S*)/gu)];
+  if (matches.length === 0) return { classes: [] };
+  if (matches.length > 1) return { refusal: 'multiple-tags' };
+  if (matches[0][1] === '') return { refusal: 'no-class' };
+  const classes = matches[0][1].split(',');
+  if (classes.some((entry) => entry === '')) return { refusal: 'empty-class' };
+  if (new Set(classes).size !== classes.length) return { refusal: 'duplicate-class' };
+  if (classes.some((entry) => !SLUG.test(entry))) return { refusal: 'invalid-class' };
+  return { classes };
+};
+
+export const classIds = (list) => Object.freeze(list.classes.map((entry) => entry.id));
+export const digestOf = (list) => createHash('sha256').update(JSON.stringify(list.classes)).digest('hex');

package/tools/sandbox-masks.mjs

@@ -42,6 +42,7 @@ import { isDirectRun } from './direct-run.mjs';
 import { fail } from './orchestration-config.mjs';
 import { isNeverCommittableStat, shellQuoteArg } from './review-state.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 export const MASKS_FENCE_START = '# >>> agent-workflow sandbox-masks — managed block, fully REPLACED by the kit sandbox-masks lane; do not hand-edit inside >>>';
 export const MASKS_FENCE_END = '# <<< agent-workflow sandbox-masks <<<';
@@ -59,7 +60,7 @@ const gitLine = (args, cwd) => {
 // The UNFILTERED untracked walk: --others WITHOUT --exclude-standard, so a mask already hidden by
 // an earlier apply stays visible to a rerun (the full-block replace re-derives it, codex).
 const listUntrackedUnfilteredZ = (root) => {
-  const r = spawnSync('git', ['ls-files', '--others', '-z'], { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, windowsHide: true });
+  const r = spawnSync('git', ['ls-files', '--others', '-z'], { cwd: root, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;
   return r.stdout.split('\0').filter(Boolean);
 };

package/tools/set-flow.mjs

@@ -50,6 +50,7 @@ import { loadDeclaration } from './run-gates.mjs';
 import { compareSemver } from './semver-lite.mjs';
 import { lexicalRepoRelative } from './core-evidence.mjs';
 import { readAuthoritativeVersion } from './manifest/validate.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const GATES_REL = 'docs/ai/gates.json';
@@ -197,7 +198,7 @@ const meetsVersionFloor = (version, floor) => {
   return cmp !== null && cmp >= 0;
 };
 
-const defaultRunGit = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+const defaultRunGit = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
 
 const gitToplevel = (cwd, runGit) => {
   const r = runGit(['rev-parse', '--show-toplevel'], cwd);

package/tools/source-size-scope.mjs

@@ -18,37 +18,18 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { configFail, configPathFor, scopeFail } from './source-size-refusal.mjs';
+import { GIT_MAX_BUFFER, parseIndexEntries, resolveGitLocation, withGitPath } from './git-env.mjs';
 
 const LF = 0x0a;
 const CR = 0x0d;
-const TAB = 0x09;
 const SLASH = 0x2f;
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 const SYMLINK_MODE = '120000';
 const GITLINK_MODE = '160000';
 
-// Raw bytes in, raw bytes out: `ls-files -s -z` emits mode, object and stage, then a TAB, then the
-// path, then a NUL — and the path half is never decoded before it has been matched, so a name
-// carrying a tab or a newline survives intact (splitting on lines would mangle it).
-// The object id is carried through rather than dropped: the record already holds it, and a consumer
-// that must read what the index HOLDS (not what the worktree happens to show) needs exactly that.
-const parseIndexEntries = (buf) => {
-  const entries = [];
-  let start = 0;
-  while (start < buf.length) {
-    let end = buf.indexOf(0, start);
-    if (end === -1) end = buf.length;
-    const record = buf.subarray(start, end);
-    const tab = record.indexOf(TAB);
-    if (tab !== -1) {
-      const head = record.subarray(0, tab).toString('utf8').split(' ');
-      entries.push({ mode: head[0], sha: head[1], stage: Number(head[2]), path: record.subarray(tab + 1) });
-    }
-    start = end + 1;
-  }
-  return entries;
-};
+// The `ls-files -s -z` record parser lives in the git leaf (raw bytes in, raw path bytes out, the
+// object id carried through so a consumer reading what the index HOLDS has it) — one home shared
+// with the control-byte gate.
 
 // A path whose bytes are not valid UTF-8 round-trips to something DIFFERENT (the replacement char is
 // lossy) — that is the whole test, and it is exact.
@@ -65,11 +46,24 @@ const bufSegmentPrefix = (path, prefix) =>
 const bufEndsWith = (path, suffix) =>
   path.length >= suffix.length && path.subarray(path.length - suffix.length).equals(suffix);
 
+// The enumeration-error class (exit 2) also refuses every git LOCATION but a work tree, by its own
+// state name — a redirecting GIT_DIR would otherwise enumerate ANOTHER repository's index in
+// silence — and a runner that throws, which is an answer here, never a raw stack.
 export const enumerateIndex = (cwd, deps = {}) => {
   const spawn = deps.spawn ?? spawnSync;
-  const result = spawn('git', ['ls-files', '-s', '-z'], { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  const env = deps.env ?? process.env;
+  const location = resolveGitLocation(cwd, { spawn, env });
+  if (location.state !== 'work-tree') {
+    throw configFail(`the git index could not be enumerated in ${cwd} (the git location is ${location.state}: ${location.cause}) — the declared scope is unknown, so nothing is judged`);
+  }
+  let result;
+  try {
+    result = spawn('git', ['ls-files', '-s', '-z'], { cwd, env: withGitPath(env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  } catch (err) {
+    result = { error: err };
+  }
   if (result.error || result.status !== 0) {
-    const why = result.error ? result.error.message : `git exited ${result.status}`;
+    const why = result.error ? result.error.message : result.signal ? `git was killed by ${result.signal}` : `git exited ${result.status}`;
     throw configFail(`the git index could not be enumerated in ${cwd} (${why}) — the declared scope is unknown, so nothing is judged`);
   }
   return parseIndexEntries(result.stdout);

package/tools/tracked-tree-census.mjs

@@ -1,6 +1,6 @@
 // tracked-tree-census.mjs — how much of a project's TRACKED tree the changed-line coverage domain
 // can actually assess, in the closed vocabulary that domain already speaks. A LEAF: it imports the
-// classification and nothing else, and it spawns exactly one read-only `git ls-files`.
+// changed-surface classification and the shared git-spawn buffer from the git-location leaf, and it spawns exactly one read-only `git ls-files`.
 //
 // Why this exists: the coverage checker's domain is `.mjs/.cjs/.js` by design, and on a TS project
 // that domain is a rounding error of the tree. Certifying it and calling the flow optimal is the
@@ -10,9 +10,9 @@
 // Read-only: never writes, never commits. Dependency-free, Node >= 22. No side effects on import.
 
 import { spawnSync } from 'node:child_process';
-import { classifyChangedPath } from './changed-surface.mjs';
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a large tracked tree; never truncate
+import { classifyChangedPath } from './changed-surface.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 export const CENSUS_VERDICT = Object.freeze({ NARROW: 'domain-narrow', WITHIN_DOMAIN: 'within-domain' });
 

package/tools/velocity-profile.mjs

@@ -133,7 +133,7 @@ export const SHELL_READONLY = Object.freeze([
 // seed time from the RUNNING tool's own location — resolved-absolute, so a moved or reinstalled
 // skill leaves a stale rule that FAIL-SAFE prompts again (never a silent widening).
 //
-// Membership (13, frozen): the read-only kit tools plus run-gates.mjs — which is NOT read-only but
+// Membership (14, frozen): the read-only kit tools plus run-gates.mjs — which is NOT read-only but
 // project-exec (it runs the project's OWN declared gates.json commands), so it seeds as ONE exact
 // byte-string pinned to this project root (`--cwd <resolved root>`): a wildcard would be BROADER
 // than the AD-037 hook boundary (`--cwd <dir>` executes an arbitrary OTHER project's gates.json)
@@ -163,6 +163,9 @@ export const KIT_READONLY_TOOLS = Object.freeze([
   // The round table the procedures advisor names every review round; its path argument is resolved
   // and compared, never opened as a pattern, so it rides the settings-level posture like the rest.
   'tools/review-rounds-cli.mjs',
+  // The control-byte gate: a pure reader over the work tree, run by hand before the matrix runs it.
+  'tools/control-bytes.mjs',
+  'tools/robustness-brief.mjs',
 ]);
 // Writer previews: ONLY writers whose ARG-FREE invocation is a documented dry-run ("Default is
 // --dry-run" in their usage) seed an EXACT preview byte-string — every --apply/--write/--yes keeps
@@ -780,7 +783,7 @@ export const screenAllowlistEntry = (pattern) => {
 };
 
 /**
- * Derive the opt-in kit-tools tier for a project: 12 wildcard entries (resolved-absolute script
+ * Derive the opt-in kit-tools tier for a project: 13 wildcard entries (resolved-absolute script
  * path + args wildcard), ONE exact run-gates entry pinned to the resolved project root, and the
  * writer-preview exact dry-run byte-strings. Pure derivation — a stale path simply prompts again.
  */

package/tools/worktree-handoff-return.mjs

@@ -34,12 +34,14 @@
 import { spawnSync } from 'node:child_process';
 import { lstatSync, readdirSync, realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
+
 import { findSatelliteEntry, readSatelliteIdentity, WORKTREES_STOP } from './satellite-locator.mjs';
 import { locateProvisionRecordSection, parseProvisionRecord, displayValue } from './worktrees-record.mjs';
 import { readFileBytesNoFollow } from './fs-read-nofollow.mjs';
 import { computeNumerator } from './dispatch-record.mjs';
 import { resolveRepoRoot, formatRatio, buildObservationRecord } from './observation-builder.mjs';
 import { appendDelegationRecord, DELEGATION_STORE_STOP } from './dispatch-store.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 // The worktrees slug grammar, repeated here so the CLI can refuse a malformed slug as USAGE before
 // any probe echoes it — the locator's own refusal interpolates the slug into a terminal message.
@@ -57,8 +59,6 @@ const PROVENANCE = 'self-reported';
 const REGULAR_MODES = new Set(['100644', '100755']);
 const RECORD_HEADING = '## Provision record';
 
-const GIT_MAX_BUFFER = 64 * 1024 * 1024;
-
 const defaultGit = (args, cwd) => {
   const r = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true, maxBuffer: GIT_MAX_BUFFER });
   return {

package/tools/worktrees.mjs

@@ -16,6 +16,7 @@ import { join, dirname, basename, resolve, relative, isAbsolute, sep } from 'nod
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
+
 import { MCP_JSON_REL, SERVER_NAME, SETTINGS_REL, withoutRegistration } from './mcp-registration.mjs';
 import {
   KIT_OWN_PATHS, KNOWN_FOOTPRINT, expandGlob, normalizeSlashes, isDirPattern, isGlobPattern,
@@ -25,6 +26,7 @@ import { isDirectRun } from './direct-run.mjs';
 import { isScratchPlanName, plansInFlight, PLANS_REL, shellQuoteArg } from './review-state.mjs';
 import { writeContainedFileAtomic } from './atomic-write.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 import { isFinalCapableDeclaration } from './run-gates.mjs';
 import {
   WORKTREES_STOP, stop, EXIT, handoffBasename, recordValue, hasControlByte, displayValue,
@@ -76,8 +78,6 @@ const TRACKED_PIN_DECLARATION =
 const TRANSFER_EXCLUSIONS = Object.freeze([':!docs/ai', ':!docs/plans']);
 const PREPARE_LOCK_BASENAME = 'aw-prepare-lock';
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
-
 const USAGE = [
   'usage: worktrees.mjs <subcommand> [args]',
   '',