axstack 0.55.0 → 0.56.0

package/skills/voa/scripts/observations.js

@@ -0,0 +1,68 @@
+export const HOSTS = ['io', 'iobook', 'iobox', 'iosatellite', 'axat-vps'];
+export const activeRuns = new Set(['queued', 'preparing', 'starting', 'running', 'waiting']);
+export const pointer = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:/._#?=&%+@-]{0,1023}$/.test(value);
+export const instant = (value) => typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(value)
+  && Number.isFinite(Date.parse(value));
+const threadLink = (value) => typeof value === 'string' && (pointer(value) && value.startsWith('t3-thread://')
+  || value.startsWith('<t3-thread://') && value.endsWith('>') && pointer(value.slice(1, -1)));
+export const identity = (owner) => owner && HOSTS.includes(owner.host)
+  && ['environmentId', 'threadId'].every((key) => pointer(owner[key])) && threadLink(owner.threadLink);
+export const sameOwner = (a, b) => identity(a) && identity(b)
+  && ['host', 'environmentId', 'threadId', 'threadLink'].every((key) => a[key] === b[key]);
+export const sameKey = (a, b) => Array.isArray(a) && Array.isArray(b) && a.length === 3 && b.length === 3
+  && a.every((value, index) => value === b[index]);
+export const validKey = (key) => Array.isArray(key) && key.length === 3 && HOSTS.includes(key[0]) && key.every(pointer);
+export const term = (name, state, evidence) => ({ term: name, state, evidence });
+
+export function threadStatus(thread, at) {
+  let state = 'unknown';
+  if (Number.isInteger(thread.pendingRequests) && thread.pendingRequests > 0) state = 'needs-you';
+  else if (activeRuns.has(thread.run)) state = 'working';
+  else if (['failed', 'interrupted'].includes(thread.run)) state = 'failed';
+  else if (['completed', 'idle'].includes(thread.run) && thread.pendingRequests === 0) state = 'idle';
+  const last = Array.isArray(thread.messages) ? thread.messages.filter((m) => m.role === 'assistant').at(-1) : null;
+  return {
+    state, lastRun: thread.run ?? null, pendingRequests: thread.pendingRequests ?? null,
+    idleHours: instant(thread.updatedAt) ? Math.max(0, Math.round((at - Date.parse(thread.updatedAt)) / 360000) / 10) : null,
+    branch: thread.branch ?? null, prs: Array.isArray(thread.prs) ? thread.prs : [],
+    lastMessage: typeof last?.text === 'string' ? last.text.replace(/\s+/g, ' ').slice(0, 300) : '',
+  };
+}
+
+export function normalize(input) {
+  if (input?.schemaVersion !== 1 || !instant(input.at) || !instant(input.collectedAt)
+    || !Array.isArray(input.hosts)) throw Error('need schemaVersion 1, ISO at/collectedAt and hosts array');
+  const budget = input.budget;
+  if (!budget || !['maxOwners', 'maxMessages'].every((key) => Number.isInteger(budget[key])
+    && budget[key] > 0 && budget[key] <= 1000) || !instant(budget.deadlineAt)) throw Error('invalid finite budget');
+  const at = Date.parse(input.at);
+  const duration = Date.parse(budget.deadlineAt) - Date.parse(input.collectedAt);
+  const inTime = at >= Date.parse(input.collectedAt) && at < Date.parse(budget.deadlineAt)
+    && duration > 0 && duration < 1800000;
+  const coverage = [];
+  const threads = [];
+  let next = null;
+  for (const host of HOSTS) {
+    const matches = input.hosts.filter((row) => row.host === host);
+    const row = matches.length === 1 ? matches[0] : null;
+    const known = row?.reachable === true && row?.paginationComplete === true
+      && pointer(row.environmentId) && pointer(row.evidence) && Array.isArray(row.threads);
+    coverage.push(term(host, known ? 'pass' : 'unknown', row?.evidence ?? 'missing/unreachable/incomplete inventory'));
+    const rows = Array.isArray(row?.threads) ? row.threads : [];
+    const remaining = inTime ? budget.maxOwners - threads.length : 0;
+    const processed = rows.slice(0, remaining);
+    if (processed.length < rows.length && next === null) next = { host, rowIndex: processed.length };
+    const counts = new Map();
+    for (const thread of processed) counts.set(thread.threadId, (counts.get(thread.threadId) ?? 0) + 1);
+    // Observed rows on partial hosts remain visible, but cannot prove recovery readiness.
+    for (const thread of processed) {
+      const owner = { host, environmentId: row.environmentId, threadId: thread.threadId, threadLink: thread.threadLink };
+      threads.push({ owner, inventoryKnown: known && processed.length === rows.length && counts.get(thread.threadId) === 1,
+        raw: thread, ...threadStatus(thread, at) });
+    }
+  }
+  const observed = input.hosts.reduce((sum, row) => sum + (Array.isArray(row.threads) ? row.threads.length : 0), 0);
+  coverage.push(term('pass-budget', inTime && observed <= threads.length ? 'pass' : 'unknown',
+    `${threads.length}/${observed} observed rows; deadline ${budget.deadlineAt}`));
+  return { at, coverage, threads, cursor: { processedOwners: threads.length, next } };
+}

package/skills/voa/scripts/records.js

@@ -0,0 +1,48 @@
+import { identity, instant, pointer, sameOwner } from './observations.js';
+
+const text = (value) => typeof value === 'string' && value.trim().length > 0;
+const referenceList = (value) => Array.isArray(value) && value.length > 0 && value.every(pointer);
+const waitKinds = new Set(['active-worker', 'own-pr-ci-review', 'external-dependency', 'human-approval',
+  'explicit-pause', 'failed-interrupted', 'completed-cleanup', 'unknown']);
+
+export function currentRecord(thread, owner, maxMessages) {
+  if (thread.historyKnown !== true || !Array.isArray(thread.messages) || thread.messages.length > maxMessages) return null;
+  // Native roles and authorship are supplied by the caller, never reconstructed from text.
+  const last = thread.messages.at(-1);
+  if (last?.role !== 'assistant' || last.source !== 'native' || !sameOwner(last.author, owner) || !pointer(last.id)
+    || !pointer(thread.latestRunId) || last.runId !== thread.latestRunId
+    || typeof last.text !== 'string') return null;
+  let record = null;
+  for (const match of last.text.matchAll(/(?:^|\n)```json\s*\n([\s\S]*?)\n```(?=\n|$)/g)) {
+    try { record = JSON.parse(match[1]); } catch { record = null; }
+  }
+  if (record?.schemaVersion !== 1 || !sameOwner(record.owner, owner) || !pointer(record.conditionId)
+    || !text(record.diagnosis) || !text(record.authority?.scope) || !pointer(record.authority?.evidence)
+    || !text(record.nextAction?.action) || !text(record.nextAction?.mode) || !pointer(record.nextAction?.evidence)
+    || !text(record.wake?.mechanism) || !(record.wake.id === null || pointer(record.wake.id))
+    || !text(record.wake.scope) || !text(record.lifetime?.scope) || !instant(record.lifetime.expiresAt)
+    || !identity(record.cleanupOwner)) return null;
+  if (record.recordType === 'closing') {
+    return ['resolved', 'completed', 'cancelled', 'accepted-handoff'].includes(record.outcome)
+      && referenceList(record.evidence) && Array.isArray(record.cleanup) ? record : null;
+  }
+  if (record.recordType !== 'waiting-turn' || !waitKinds.has(record.waitKind)
+    || !text(record.dependency?.kind) || !pointer(record.dependency?.id) || !referenceList(record.dependency?.evidence)
+    || !instant(record.lastMeaningfulProgress?.at) || !pointer(record.lastMeaningfulProgress?.evidence)
+    || typeof record.pause !== 'boolean' || !(record.snoozeUntil === null || instant(record.snoozeUntil))
+    || !(record.nextEligibleCheck === null || instant(record.nextEligibleCheck))) return null;
+  return record;
+}
+
+export function condition(record, blocker, at) {
+  if (record?.recordType !== 'waiting-turn' || !blocker
+    || blocker.nonHuman !== true || blocker.kind !== record.dependency.kind || blocker.id !== record.dependency.id
+    || !['check', 'review', 'upstream-pr', 'dependency'].includes(blocker.kind)
+    || !pointer(blocker.evidence) || !instant(blocker.inspectedAt)
+    || Date.parse(blocker.inspectedAt) > at || Date.parse(blocker.inspectedAt) < at - 1800000) return null;
+  if (record.waitKind === 'external-dependency' && blocker.state === 'cleared') return 'dependency-cleared';
+  if (['own-pr-ci-review', 'external-dependency', 'human-approval'].includes(record.waitKind)
+    && record.diagnosis === 'none' && blocker.state === 'unexplained'
+    && record.nextAction.mode === 'read-only') return 'missing-diagnosis';
+  return null;
+}

package/skills/voa/scripts/voa.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+import { evaluate } from './evaluate.js';
+
+const HELP = `VOA saved-observation preview (Bun >=1.3.14)
+Usage: bun voa.js [--mode status|recovery|cleanup] --input <saved.json>
+  --mode   Defaults to read-only status. Recovery/cleanup require explicit scope evidence.
+  --input  One saved schemaVersion:1 JSON file, at most 8 MiB.
+  --help   Show flags and side effects.
+Reads only the given file; writes JSON to stdout and errors to stderr.
+No collection, network, sends, dispatch, scheduling, workflow selection, deletion or state.
+Terms are pass/fail/unknown/n/a with evidence, never an aggregate authority verdict.
+Exit: 0 complete report (including failed criteria), 1 invalid input, 2 incomplete/unknown.
+See ../references/observations.md and ../references/recovery.md.
+`;
+
+export async function main(args) {
+  if (args.length === 1 && args[0] === '--help') { process.stdout.write(HELP); return 0; }
+  let mode = 'status';
+  let path;
+  const seen = new Set();
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    const value = args[index + 1];
+    if (!['--mode', '--input'].includes(flag) || !value || value.startsWith('--') || seen.has(flag)) {
+      throw Error('use --help; unknown, repeated or missing flag value');
+    }
+    seen.add(flag);
+    if (flag === '--mode') mode = value;
+    else path = value;
+  }
+  if (!path) throw Error('--input is required');
+  const file = Bun.file(path);
+  if (file.size > 8 * 1024 * 1024) throw Error('input exceeds 8 MiB');
+  const result = evaluate(await file.json(), mode);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  const terms = [...result.coverage, ...result.owners.flatMap((owner) => owner.terms), ...(result.cleanup?.terms ?? [])];
+  return terms.some((entry) => entry.state === 'unknown') ? 2 : 0;
+}
+
+if (import.meta.main) {
+  try { process.exitCode = await main(Bun.argv.slice(2)); }
+  catch (error) { process.stderr.write(`voa: ${error.message}\n`); process.exitCode = 1; }
+}

package/src/installer.js

@@ -239,10 +239,11 @@ export async function validateBundle(bundleDir, selectedPreset = null) {
     throw new Error('bundle skills/ must be a real directory, not a symlink');
   }
   const entries = await readdir(skillsRoot, { withFileTypes: true });
+  const isShippedSkill = (name) => name.startsWith('axstack') || name === 'voa';
   // Symlinked (or non-directory) top-level skill entries must be rejected,
   // not silently skipped: Dirent.isDirectory() is false for symlinks.
   for (const entry of entries) {
-    if (!entry.name.startsWith('axstack')) continue;
+    if (!isShippedSkill(entry.name)) continue;
     const entryStat = await lstat(join(skillsRoot, entry.name));
     if (entryStat.isSymbolicLink() || !entryStat.isDirectory()) {
       throw new Error(
@@ -250,7 +251,7 @@ export async function validateBundle(bundleDir, selectedPreset = null) {
       );
     }
   }
-  const skillDirs = entries.filter((e) => e.isDirectory() && e.name.startsWith('axstack'));
+  const skillDirs = entries.filter((e) => e.isDirectory() && isShippedSkill(e.name));
   if (skillDirs.length === 0) {
     throw new Error('bundle contains no axstack-* skill directories under skills/');
   }

package/src/instructions.js

@@ -11,10 +11,18 @@ export function renderInstructionBlock() {
     '`axstack-implement` loops author -> review -> repair until every PR is merge-ready.',
     'Route every subagent, delegated worker, reviewer, and cross-harness dispatch through T3 Code orchestration using the `t3-code` MCP.',
     'Use `delegate_task` for every role, including authors with `isolation:"worktree"`.',
-    'Use `t3_thread_launch` for top-level drivers.',
-    'Use `t3_thread_launch` as a rare author fallback only when worktree isolation is unavailable and record each use in the run record.',
+    'Use `t3_thread_launch` for top-level drivers only on explicit user request for a new thread.',
+    'Use `t3_thread_launch` as a rare author fallback only when worktree isolation is unavailable following an explicit user request for a new thread and record each use in the run record.',
     'Follow `references/t3-runtime.md` in the installed `axstack` skill for the runtime contract.',
-    'The user authorizes Axstack drivers in T3 to run full-access and launch top-level driver threads, delegated writers and worktrees within approved scope.',
+    'Before every subsequent dispatch of delegated workers and reviewers and every explicitly authorized top-level launch, follow `references/fleet-dispatch.md` and `references/fleet-route-schema.md` in the installed `axstack` skill with current routing facts.',
+    'Refresh routing facts immediately before dispatch and run `bun <installed-axstack>/scripts/fleet-route.js recommend --input <facts.json> --now <epoch-ms> --config ~/.config/haoshoku/fleet-routing.json --config-digest <run-pinned-sha256> --json` with the account-local policy and run-pinned digest.',
+    'Bind the selected destination to explicit `environmentId`, `projectId`, provider, model, options and `runtimeMode` from current destination observations.',
+    'Never let native main/UI balancing override the explicit worker destination.',
+    'Hold routing failures, unknown execution authority and no-route results, using only a proven supported local isolated fallback within existing authority.',
+    'Absence of facts never authorizes a route.',
+    'Keep remote-author-coordinator off pending successful version-bound lifecycle gates.',
+    'The user authorizes Axstack drivers in T3 to run full-access and create delegated writers and worktrees within approved scope.',
+    'Existing exact scoped authorization needs no additional permission flow.',
     'Do not use a harness native subagent tool for delegated work.',
     END,
   ].join('\n');