axstack 0.53.1 → 0.55.0

package/skills/axstack/scripts/fleet-config.js

@@ -0,0 +1,78 @@
+// Configuration is reviewed data. This module does not read account-local files.
+export function fail(code) { throw new Error(code); }
+export const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+export const text = (value) => typeof value === 'string' && value.trim().length > 0;
+export const time = (value) => Number.isSafeInteger(value) && value >= 0;
+const bp = (value) => Number.isInteger(value) && value >= 0 && value <= 10000;
+
+// Canonical comparison for JSON settings, independent of property insertion order.
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (record(value)) return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+export function evidence(value, environmentId, now) {
+  return record(value) && value.environmentId === environmentId && text(value.pointer)
+    && time(value.observedAt) && value.observedAt <= now;
+}
+
+export function parseFleetConfig(configText, expectedDigest) {
+  if (!text(configText)) fail('missing-config');
+  if (typeof expectedDigest !== 'string' || !/^[a-f0-9]{64}$/.test(expectedDigest)) fail('config-digest');
+  const digest = new Bun.CryptoHasher('sha256').update(configText).digest('hex');
+  if (digest !== expectedDigest) fail('config-digest-mismatch');
+  let config;
+  try { config = JSON.parse(configText); } catch { fail('config-json'); }
+  if (!record(config) || config.schemaVersion !== 1) fail('schema-version: config');
+  if (!Array.isArray(config.hosts) || config.hosts.length === 0) fail('config-host');
+  const ids = new Set();
+  const environments = new Set();
+  for (const host of config.hosts) {
+    if (!record(host) || !text(host.id) || !text(host.environmentId) || ids.has(host.id)
+      || environments.has(host.environmentId) || !record(host.capabilities)) fail('config-host');
+    ids.add(host.id); environments.add(host.environmentId);
+    if (!bp(host.fallbackLimitBp)) fail('config-threshold');
+  }
+  if (!bp(config.balanceLimitBp)) fail('config-threshold');
+  const order = (value, complete) => Array.isArray(value) && value.every((id) => ids.has(id))
+    && new Set(value).size === value.length && (!complete || value.length === ids.size);
+  if (!order(config.defaultOrder, true) || !order(config.pool, false) || !record(config.taskOrders)
+    || Object.values(config.taskOrders).some((o) => !order(o, true))) fail('config-order');
+  if (!Array.isArray(config.routes)) fail('config-route');
+  const routeIds = new Set();
+  for (const route of config.routes) {
+    if (!record(route) || !text(route.id) || routeIds.has(route.id) || !text(route.originEnvironmentId)
+      || !environments.has(route.environmentId) || typeof route.enabled !== 'boolean'
+      || !['local', 'remote', 'remote-author-coordinator'].includes(route.kind)
+      || (route.kind === 'local') !== (route.originEnvironmentId === route.environmentId)) fail('config-route');
+    routeIds.add(route.id);
+  }
+  return config;
+}
+
+export function validateInput(input, now) {
+  if (!time(now)) fail('evaluation-time');
+  if (!record(input) || input.schemaVersion !== 1) fail('schema-version: input');
+  if (!record(input.origin) || !text(input.origin.environmentId) || !record(input.origin.versions)) fail('origin-schema');
+  const r = input.request;
+  if (!record(r) || !text(r.task) || !['reader', 'author'].includes(r.role)
+    || !Array.isArray(r.requiredCapabilities) || !r.requiredCapabilities.every(text)
+    || !text(r.repositoryId) || !text(r.providerInstanceId) || !text(r.model)
+    || !record(r.options) || !text(r.runtimeMode)) fail('request-schema');
+  for (const key of ['destinations', 'routeFacts', 'telemetry', 'assignments', 'pendingAssignments']) {
+    if (!Array.isArray(input[key])) fail(`${key}-schema`);
+  }
+  if (!['known', 'unknown'].includes(input.inventoryStatus)
+    || (input.inventoryStatus === 'known' && (!time(input.inventoryObservedAt) || input.inventoryObservedAt > now))) fail('inventory-schema');
+  if (!record(input.exclusions) || !record(input.exclusions.hosts) || !record(input.exclusions.routes)
+    || !Object.values(input.exclusions.hosts).every(text) || !Object.values(input.exclusions.routes).every(text)) fail('exclusions-schema');
+  // Reject ambiguous joins, rather than choosing whichever duplicate arrived first.
+  for (const [key, id] of [['destinations', 'environmentId'], ['routeFacts', 'routeId'], ['telemetry', 'environmentId']]) {
+    const seen = new Set();
+    for (const value of input[key]) {
+      if (!record(value) || !text(value[id]) || seen.has(value[id])) fail(`${key}-schema`);
+      seen.add(value[id]);
+    }
+  }
+}

package/skills/axstack/scripts/fleet-dispatch.js

@@ -0,0 +1,41 @@
+// Bind supplied placement facts to a plan. No reads, dispatch or authority grant.
+import { canonical, record, text } from './fleet-config.js';
+import { recommend } from './fleet-route.js';
+
+export function bindFleet(input, saved, configDigest, now, capabilitiesText, resolved, author) {
+  const hold = (code) => { throw Object.assign(new Error(code), { exitCode: 2 }); };
+  if (saved?.schemaVersion !== 1) hold('schema-version: recommendation');
+  if (configDigest !== input?.configDigest) hold('config-digest-mismatch');
+  let current;
+  try { current = recommend(input, now); } catch (error) { hold(error.message); }
+  if (canonical(saved) !== canonical(current)) hold('recommendation-mismatch');
+  const selected = current.selected;
+  if (!selected) hold('no-executable-route');
+  // Coordinator enablement/lifecycle is a later capability, never inferred here.
+  if (selected.routeKind === 'remote-author-coordinator') hold('remote-author-not-enabled');
+  const digest = selected.destinationCapabilitiesDigest;
+  if (typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest)) hold('capabilities-digest-missing');
+  if (new Bun.CryptoHasher('sha256').update(capabilitiesText).digest('hex') !== digest) hold('capabilities-digest-mismatch');
+  const request = current.request;
+  const { model, providerInstanceId, effortOption } = resolved;
+  if (request.providerInstanceId !== providerInstanceId || request.model !== model
+    || request.runtimeMode !== 'full-access' || (request.role === 'author') !== author
+    || !record(request.options) || request.options[effortOption.id] !== effortOption.value) hold('settings-mismatch');
+  const catalog = JSON.parse(capabilitiesText);
+  const instance = catalog.providers.find((p) => p.providerInstanceId === providerInstanceId);
+  const models = instance.models.filter((m) => m.id === model);
+  if (models.length !== 1) hold('capabilities-model-ambiguous');
+  const options = Object.entries(request.options).sort(([a], [b]) => a.localeCompare(b)).map(([id, value]) => {
+    const definitions = models[0].options.filter((o) => o.id === id);
+    if (!text(id) || !['string', 'boolean'].includes(typeof value) || definitions.length !== 1) hold('unsupported-option');
+    const definition = definitions[0];
+    const values = definition.values ?? definition.options?.map((v) => v.id);
+    if (!values?.includes(value)) hold(`unsupported-option: ${id}`);
+    return { id, value };
+  });
+  return {
+    options, destination: { environmentId: selected.environmentId, projectId: selected.projectId },
+    fleetBinding: { configDigest, destinationSnapshotId: selected.destinationSnapshotId,
+      destinationCapabilitiesDigest: digest },
+  };
+}

package/skills/axstack/scripts/fleet-facts.js

@@ -0,0 +1,150 @@
+import { canonical, evidence, fail, record, text, time } from './fleet-config.js';
+
+const terminal = new Set(['completed', 'failed', 'cancelled', 'canceled', 'rejected']);
+const states = new Set([...terminal, 'pending', 'queued', 'running', 'waiting', 'blocked']);
+const qualified = (value) => text(value) && /^.+:.+$/.test(value);
+
+export function assignmentCounts(input, hosts) {
+  const byEnvironment = Object.fromEntries(hosts.map((h) => [h.environmentId, 0]));
+  const inventory = new Map();
+  const clients = new Map();
+  const pendingTasks = new Map();
+  for (const a of input.assignments) {
+    if (!record(a) || !qualified(a.assignmentId) || !text(a.environmentId) || !states.has(a.state)) fail('assignment-schema');
+    const previous = inventory.get(a.assignmentId);
+    if (previous && (previous.environmentId !== a.environmentId || previous.state !== a.state)) fail('assignment-conflict');
+    inventory.set(a.assignmentId, a);
+  }
+  const count = (environmentId) => {
+    if (Object.hasOwn(byEnvironment, environmentId)) byEnvironment[environmentId]++;
+  };
+  if (input.inventoryStatus === 'known') {
+    for (const a of inventory.values()) if (!terminal.has(a.state)) count(a.environmentId);
+  }
+  for (const p of input.pendingAssignments) {
+    if (!record(p) || !text(p.clientRequestId) || !text(p.environmentId)
+      || (p.taskId !== undefined && !qualified(p.taskId))) fail('pending-assignment-schema');
+    const previous = clients.get(p.clientRequestId);
+    if (previous && (previous.environmentId !== p.environmentId || previous.taskId !== p.taskId)) fail('assignment-conflict');
+    if (previous) continue;
+    clients.set(p.clientRequestId, p);
+    if (p.taskId !== undefined) {
+      const known = input.inventoryStatus === 'known' ? inventory.get(p.taskId) : null;
+      const pendingEnvironment = pendingTasks.get(p.taskId);
+      if ((known && known.environmentId !== p.environmentId)
+        || (pendingEnvironment && pendingEnvironment !== p.environmentId)) fail('assignment-conflict');
+      if (known || pendingEnvironment) continue;
+      pendingTasks.set(p.taskId, p.environmentId);
+    }
+    count(p.environmentId);
+  }
+  return { byEnvironment, inventoryStatus: input.inventoryStatus,
+    inventoryObservedAt: input.inventoryObservedAt ?? null, pendingRecords: clients.size,
+    provenance: input.inventoryStatus === 'known' ? 'inventory-plus-pending' : 'pending-only' };
+}
+
+// Scale the shortest decimal representation, avoiding binary multiplication overshoot.
+function fractionBp(fraction) {
+  const [mantissa, exponent = '0'] = String(fraction).split('e');
+  const [whole, decimals = ''] = mantissa.split('.');
+  const numerator = BigInt(whole + decimals);
+  const scale = decimals.length - Number(exponent) - 4;
+  if (scale <= 0) return Number(numerator * (10n ** BigInt(-scale)));
+  const denominator = 10n ** BigInt(scale);
+  return Number((numerator + denominator - 1n) / denominator);
+}
+
+export function telemetry(sample, now) {
+  const provenance = Object.fromEntries(['source', 'scope', 'durationMs', 'intervalMs', 'windowStartedAt',
+    'windowEndedAt', 'windowKind', 'receivedAt', 'timeoutMs'].filter((key) => sample?.[key] !== undefined)
+    .map((key) => [key, sample[key]]));
+  const ageMs = time(sample?.receivedAt) ? now - sample.receivedAt : null;
+  const unknown = (reason) => ({ ...provenance, status: 'unknown', reason, ageMs });
+  if (!sample) return unknown('missing');
+  if (sample.timedOut === true) return unknown('timeout');
+  if (sample.status !== 'ok') return unknown(text(sample.status) ? sample.status : 'failed');
+  if (!time(sample.receivedAt)) return unknown('invalid-received-time');
+  if (ageMs < 0) return unknown('future');
+  if (ageMs > 15000) return unknown('stale');
+  if (!Number.isSafeInteger(sample.durationMs) || sample.durationMs < 5000
+    || sample.scope !== 'whole-host' || !text(sample.source)) return unknown('unusable-provenance');
+  if (sample.windowStartedAt !== undefined && (!time(sample.windowStartedAt)
+    || sample.receivedAt - sample.windowStartedAt < sample.durationMs)) return unknown('inconsistent-window');
+  if ((sample.intervalMs !== undefined && (!Number.isSafeInteger(sample.intervalMs)
+    || sample.intervalMs < 5000 || sample.intervalMs > 60000 || sample.intervalMs > sample.durationMs))
+    || (sample.windowEndedAt !== undefined && (!time(sample.windowEndedAt)
+      || !time(sample.windowStartedAt) || sample.windowEndedAt > sample.receivedAt
+      || sample.windowEndedAt - sample.windowStartedAt < sample.durationMs))) return unknown('inconsistent-window');
+  const toBp = (name) => {
+    const points = sample[`${name}Bp`];
+    const fraction = sample[`${name}Fraction`];
+    // Exactly one representation: conflicting fields must not silently win.
+    if (points !== undefined && fraction !== undefined) return null;
+    if (fraction !== undefined) return typeof fraction === 'number' && Number.isFinite(fraction)
+      && fraction >= 0 && fraction <= 1 ? fractionBp(fraction) : null;
+    return Number.isInteger(points) && points >= 0 && points <= 10000 ? points : null;
+  };
+  const cpuBp = toBp('cpu'); const ramBp = toBp('ram');
+  if (cpuBp === null || ramBp === null) return unknown('malformed');
+  // If the collector supplies latest RAM as well as an average, retain spikes.
+  const latest = sample.ramLatestBp;
+  if (latest !== undefined && (!Number.isInteger(latest) || latest < 0 || latest > 10000)) return unknown('malformed');
+  return { status: 'measured', ageMs, cpuBp, ramBp, ramLatestBp: latest ?? null,
+    loadBp: Math.max(cpuBp, ramBp, latest ?? 0), receivedAt: sample.receivedAt,
+    source: sample.source, scope: sample.scope, durationMs: sample.durationMs,
+    windowStartedAt: sample.windowStartedAt ?? null, windowEndedAt: sample.windowEndedAt ?? null,
+    intervalMs: sample.intervalMs ?? null, windowKind: sample.windowKind ?? null,
+    timeoutMs: sample.timeoutMs ?? null };
+}
+
+const versionsMatch = (a, b) => record(a) && record(b) && text(a.t3) && text(a.axstack)
+  && a.t3 === b.t3 && a.axstack === b.axstack;
+
+export function routeReasons(route, host, destination, facts, input, now) {
+  const reasons = [];
+  const add = (code) => { if (!reasons.includes(code)) reasons.push(code); };
+  const remote = route.environmentId !== input.origin.environmentId;
+  const r = input.request;
+  if (Object.hasOwn(input.exclusions.hosts, host.id)) add('excluded-host');
+  if (Object.hasOwn(input.exclusions.routes, route.id)) add('excluded-route');
+  if (!route.enabled) add('route-disabled');
+  if (route.kind === 'remote-author-coordinator' && r.role !== 'author') add('route-role-mismatch');
+  if (!evidence(route.evidence, host.environmentId, now)) add('evidence-unproven');
+  if (!facts) add('route-unproven');
+  else {
+    if (facts.reachable !== true) add(facts.reachable === false ? 'offline' : 'route-unproven');
+    if (facts.authorized !== true) add(facts.authorized === false ? 'unauthorized' : 'route-unproven');
+    if (remote && (!time(facts.expiresAt) || facts.expiresAt <= now)) add('link-expired');
+    if (!evidence(facts.evidence, host.environmentId, now)) add('evidence-unproven');
+  }
+  if (destination?.status !== 'known') add('destination-unproven');
+  else {
+    if (!time(destination.observedAt) || destination.observedAt > now
+      || !evidence(destination.evidence, host.environmentId, now)) add('evidence-unproven');
+    if (!text(destination.snapshotId) || facts?.destinationSnapshotId !== destination.snapshotId) add('target-snapshot-mismatch');
+    if (!record(destination.project) || !text(destination.project.id)) add('project-missing');
+    else if (destination.project.repositoryId !== r.repositoryId) add('project-mismatch');
+    const e = destination.execution;
+    if (!record(e) || e.available !== true) add('execution-unproven');
+    else if (e.providerInstanceId !== r.providerInstanceId || e.model !== r.model
+      || e.runtimeMode !== r.runtimeMode || canonical(e.options) !== canonical(r.options)) add('execution-mismatch');
+  }
+  const required = [...r.requiredCapabilities, ...(r.role === 'author' ? ['worktree-isolation'] : [])];
+  for (const name of required) {
+    for (const capabilities of [host.capabilities, destination?.capabilities]) {
+      const fact = capabilities?.[name];
+      if (fact?.value !== true || !evidence(fact.evidence, host.environmentId, now)) add('capability-unproven');
+    }
+  }
+  if (r.role === 'author' && remote) {
+    if (route.kind !== 'remote-author-coordinator') add('remote-author-unsupported');
+    else {
+      const proof = route.authorProof;
+      if (proof?.gatesPassed !== true || proof.originEnvironmentId !== input.origin.environmentId
+        || proof.environmentId !== host.environmentId || !evidence(proof.evidence, host.environmentId, now)
+        || !versionsMatch(proof.originVersions, input.origin.versions)
+        || !versionsMatch(proof.destinationVersions, destination?.versions)) add('remote-author-unproven');
+    }
+  }
+  return reasons;
+}

package/skills/axstack/scripts/fleet-proc.js

@@ -0,0 +1,31 @@
+// Linux aggregate CPU counters; guest/guest_nice are already in user/nice.
+const malformed = () => { throw Error('malformed'); };
+const bp = (n, d) => Number((n * 10000n + d - 1n) / d);
+export function parseProc(value) {
+  if (typeof value !== 'string' || value.length > 65536) malformed();
+  const parts = value.split('\n---AXSTACK-MEM---\n');
+  if (parts.length !== 2) malformed();
+  const lines = parts[0].split('\n').filter((s) => /^cpu\s/.test(s));
+  if (lines.length !== 1) malformed();
+  const counters = lines[0].trim().split(/\s+/).slice(1);
+  if (counters.length < 8 || counters.length > 10
+    || counters.some((v) => !/^\d+$/.test(v) || !Number.isSafeInteger(Number(v)))) malformed();
+  const memory = (key) => {
+    const rows = parts[1].split('\n').filter((s) => s.startsWith(`${key}:`));
+    const match = rows.length === 1 && rows[0].match(new RegExp(`^${key}:\\s+(\\d+) kB\\s*$`));
+    if (!match || !Number.isSafeInteger(Number(match[1]))) malformed();
+    return BigInt(match[1]);
+  };
+  const total = memory('MemTotal'); const available = memory('MemAvailable');
+  if (total <= 0n || available > total) malformed();
+  return { counters: counters.slice(0, 8).map(BigInt), total, used: total - available };
+}
+
+export function pressure(first, last) {
+  const deltas = last.counters.map((v, i) => v - first.counters[i]);
+  const total = deltas.reduce((a, b) => a + b, 0n);
+  if (deltas.some((v) => v < 0n) || total <= 0n || first.total !== last.total) throw Error('inconsistent-counters');
+  const busy = total - deltas[3] - deltas[4]; // idle and iowait only; steal is busy.
+  return { cpuBp: bp(busy, total), ramBp: bp(first.used + last.used, 2n * last.total),
+    ramLatestBp: bp(last.used, last.total) };
+}

package/skills/axstack/scripts/fleet-route-cli.js

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { sampleMain, sampleHelp } from './fleet-sample-cli.js';
+import { recommend, parseFleetConfig } from './fleet-route.js';
+
+const help = `Usage: bun fleet-route.js recommend --input <snapshot.json> --now <epoch-ms> [--json]
+  [--task <name>] [--config <fleet-routing.json>] [--config-digest <sha256>]
+
+--input          Saved schema-1 facts; no collection or dispatch
+--now            Required nonnegative integer evaluation time; no ambient clock
+--task           Override the saved request's task preference
+--config         Reviewed account-local config (default: ~/.config/haoshoku/fleet-routing.json)
+--config-digest  Run-pinned SHA-256; otherwise required in saved input.configDigest
+--json           Emit complete recommendation JSON; errors are JSON on stderr
+--help           Show this interface
+
+Reads only the supplied input and config. Writes stdout/stderr only.
+No network, authentication, dispatch, config changes or retained state.
+Required session capabilities must be proven on the actual destination session;
+an origin catalog or transferred credentials cannot establish them.
+Exclusions with reasons are supplied in input.exclusions.hosts/routes.
+Use sample or sample-recommend for bounded collection.
+Exit codes: 0 recommendation/help, 1 input/config error, 2 no executable route.
+`;
+
+const fail = (code) => { throw new Error(code); };
+function readInput(path) {
+  let value;
+  try { value = readFileSync(path, 'utf8'); } catch { fail('missing-input'); }
+  try { return JSON.parse(value); } catch { fail('input-json'); }
+}
+
+function defaultConfigPath() {
+  return process.env.HOME ? `${process.env.HOME}/.config/haoshoku/fleet-routing.json` : null;
+}
+
+export async function main(argv) {
+  try {
+    if (argv.length === 1 && argv[0] === '--help') {
+      process.stdout.write(help + sampleHelp);
+      return 0;
+    }
+    if (['sample', 'sample-recommend'].includes(argv[0])) return await sampleMain(argv, defaultConfigPath());
+    if (argv[0] !== 'recommend') fail('unexpected-command');
+    const args = {};
+    for (let i = 1; i < argv.length; i++) {
+      const flag = argv[i];
+      if (!['--input', '--now', '--task', '--config', '--config-digest', '--json'].includes(flag)) fail('unexpected-argument');
+      if (Object.hasOwn(args, flag)) fail('duplicate-argument');
+      if (flag === '--json') { args[flag] = true; continue; }
+      const value = argv[++i];
+      if (!value?.trim() || value.startsWith('--')) fail('missing-argument');
+      args[flag] = value;
+    }
+    if (!args['--input'] || !args['--now']) fail('missing-argument');
+    if (!/^\d+$/.test(args['--now'])) fail('evaluation-time');
+    const now = Number(args['--now']);
+    const input = readInput(args['--input']);
+    if (!input || typeof input !== 'object' || Array.isArray(input) || input.schemaVersion !== 1) fail('schema-version: input');
+    let configText;
+    const configPath = args['--config'] ?? defaultConfigPath();
+    try {
+      if (!configPath) fail('missing-config');
+      configText = readFileSync(configPath, 'utf8');
+    } catch { fail('missing-config'); }
+    const configDigest = args['--config-digest'] ?? input.configDigest;
+    parseFleetConfig(configText, configDigest);
+    if (input.configDigest !== undefined && input.configDigest !== configDigest) fail('config-digest-mismatch');
+    if (input.configText !== undefined && input.configText !== configText) fail('config-snapshot-mismatch');
+    const result = recommend({ ...input, configText, configDigest,
+      request: args['--task'] ? { ...input.request, task: args['--task'] } : input.request }, now);
+    process.stdout.write(args['--json'] ? `${JSON.stringify(result)}\n`
+      : `${result.stage}: ${result.selected?.hostId ?? 'no host'} (${result.reason})\n`);
+    return result.selected ? 0 : 2;
+  } catch (error) {
+    process.stderr.write(`${JSON.stringify({ error: { code: error.message.split(':')[0], message: error.message } })}\n`);
+    return 1;
+  }
+}

package/skills/axstack/scripts/fleet-route.js

@@ -0,0 +1,85 @@
+// Pure supplied-facts API. No clock, filesystem, networking or dispatch.
+import { parseFleetConfig, validateInput } from './fleet-config.js';
+import { assignmentCounts, routeReasons, telemetry } from './fleet-facts.js';
+export { parseFleetConfig } from './fleet-config.js';
+
+export function recommend(input, now) {
+  validateInput(input, now);
+  const config = parseFleetConfig(input.configText, input.configDigest);
+  const counts = assignmentCounts(input, config.hosts);
+  const preference = Object.hasOwn(config.taskOrders, input.request.task)
+    ? config.taskOrders[input.request.task] : config.defaultOrder;
+  const eligible = [];
+  const excluded = [];
+  for (const hostId of preference) {
+    const host = config.hosts.find((h) => h.id === hostId);
+    const destination = input.destinations.find((d) => d.environmentId === host.environmentId);
+    const routes = config.routes.filter((r) => r.environmentId === host.environmentId
+      && r.originEnvironmentId === input.origin.environmentId);
+    let accepted = null;
+    for (const route of routes) {
+      const facts = input.routeFacts.find((f) => f.routeId === route.id);
+      const reasons = routeReasons(route, host, destination, facts, input, now);
+      if (reasons.length) {
+        excluded.push({ hostId, environmentId: host.environmentId, routeId: route.id, reasons,
+          exclusion: (Object.hasOwn(input.exclusions.hosts, hostId) ? input.exclusions.hosts[hostId] : null)
+            ?? (Object.hasOwn(input.exclusions.routes, route.id) ? input.exclusions.routes[route.id] : null),
+          evidence: { configuredRoute: route.evidence ?? null, observedRoute: facts?.evidence ?? null,
+            destination: destination?.evidence ?? null, destinationSnapshotId: destination?.snapshotId ?? null,
+            configuredCapabilities: host.capabilities, observedCapabilities: destination?.capabilities ?? null } });
+      } else if (!accepted) {
+        accepted = { hostId, environmentId: host.environmentId, projectId: destination.project.id,
+          repositoryId: destination.project.repositoryId, routeId: route.id, routeKind: route.kind,
+          destinationSnapshotId: destination.snapshotId, destinationObservedAt: destination.observedAt,
+          ...(destination.capabilitiesDigest !== undefined
+            ? { destinationCapabilitiesDigest: destination.capabilitiesDigest } : {}),
+          destinationEvidence: destination.evidence, routeEvidence: facts.evidence, versions: destination.versions,
+          execution: destination.execution, capabilities: destination.capabilities,
+          fallbackLimitBp: host.fallbackLimitBp, assignmentCount: counts.byEnvironment[host.environmentId],
+          telemetry: telemetry(input.telemetry.find((s) => s.environmentId === host.environmentId), now) };
+      }
+    }
+    if (accepted) eligible.push(accepted);
+    if (!routes.length) excluded.push({ hostId, environmentId: host.environmentId, routeId: null, reasons: ['route-missing'], exclusion: null });
+  }
+  const pool = eligible.filter((h) => config.pool.includes(h.hostId));
+  const measured = (h) => h.telemetry.status === 'measured';
+  const rank = (h) => preference.indexOf(h.hostId);
+  const byLoad = (a, b) => a.telemetry.loadBp - b.telemetry.loadBp || rank(a) - rank(b);
+  const under = pool.filter((h) => measured(h) && h.telemetry.loadBp <= config.balanceLimitBp);
+  let stage; let reason; let selected = null;
+  if (!eligible.length) { stage = 'no-route'; reason = 'no-executable-route'; }
+  else if (under.length) {
+    stage = 'balance'; reason = 'pool-under-limit';
+    selected = under.sort((a, b) => a.assignmentCount - b.assignmentCount || byLoad(a, b))[0];
+  } else if (pool.length && pool.every((h) => !measured(h))) {
+    stage = 'pool-unknown'; reason = 'pool-all-unknown'; selected = pool[0];
+  } else {
+    stage = 'fallback';
+    selected = eligible.find((h) => measured(h) && h.telemetry.loadBp <= h.fallbackLimitBp);
+    if (selected) reason = 'first-within-limit';
+    else {
+      const observed = eligible.filter(measured).sort(byLoad);
+      selected = observed[0] ?? eligible[0];
+      reason = observed.length ? 'least-loaded-over-limit' : 'all-telemetry-unknown';
+    }
+  }
+  const flags = {
+    countsUnknown: input.inventoryStatus === 'unknown', poolEmpty: pool.length === 0,
+    poolPartlyUnknown: pool.some(measured) && pool.some((h) => !measured(h)),
+    telemetryUnknown: eligible.some((h) => !measured(h)),
+    overloaded: selected ? measured(selected) && selected.telemetry.loadBp > selected.fallbackLimitBp : false,
+    localAuthorOnly: input.request.role === 'author' && eligible.length > 0
+      && eligible.every((h) => h.environmentId === input.origin.environmentId),
+  };
+  // Copy supplied nested facts so callers cannot mutate input through the result.
+  return structuredClone({ schemaVersion: 1, configDigest: input.configDigest, evaluatedAt: now,
+    originEnvironmentId: input.origin.environmentId, request: input.request,
+    stage, reason: flags.localAuthorOnly ? 'author-local-only' : reason, decisionReason: reason,
+    selected, flags, counts, eligible, excluded });
+}
+
+if (import.meta.main) {
+  const { main } = await import('./fleet-route-cli.js');
+  process.exitCode = await main(process.argv.slice(2));
+}

package/skills/axstack/scripts/fleet-sample-cli.js

@@ -0,0 +1,81 @@
+import { readFileSync } from 'node:fs';
+import { parseFleetConfig, recommend } from './fleet-route.js';
+import { sampleFleet } from './fleet-sample.js';
+import { sampleOptions, validateManifest } from './fleet-sample-manifest.js';
+export const sampleHelp = `
+Usage: bun fleet-route.js sample --fleet <manifest.json> --config-digest <sha256> [--config <path>] [--json]
+       bun fleet-route.js sample-recommend --fleet <manifest.json> --input <snapshot.json>
+         --config-digest <sha256> [--config <path>] [--json]
+--fleet        Schema-1 manifest; exact host/environment joins; local or SSH transport
+--interval-ms  Integer 5000..60000; default 5000; minimum gap between two reads
+--timeout-ms   Per-host whole-collection deadline; default 10000; interval+1000..120000
+--config       Same reviewed config/default path as recommend; explicit digest required
+--input        sample-recommend only: C1 access/project/capability/assignment facts
+--json         Full sample report or {input,evaluatedAt,recommendation} replay envelope
+
+Sample commands read Linux /proc/stat and /proc/meminfo locally or through bounded,
+noninteractive SSH argv to validated MagicDNS short names with existing identities.
+They use collector receipt time, collect hosts concurrently, and write stdout/stderr only.
+Window duration brackets transport plus reads and interval; it is not native history.
+Unknown telemetry never grants a route. No dispatch, config mutation or retained state.
+Exit codes: 0 sample/recommendation, 1 input/config error, 2 no executable route.
+`;
+const fail = (code) => { throw Error(code); };
+function read(path, name, json = true) {
+  let text;
+  try { text = readFileSync(path, 'utf8'); } catch { fail(`missing-${name}`); }
+  if (!json) return text;
+  try { return JSON.parse(text); } catch { fail(`${name}-json`); }
+}
+export async function sampleMain(argv, defaultConfigPath) {
+  const command = argv[0]; const args = {};
+  const flags = ['--fleet', '--config', '--config-digest', '--interval-ms', '--timeout-ms', '--json',
+    ...(command === 'sample-recommend' ? ['--input', '--task'] : [])];
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!flags.includes(flag)) fail('unexpected-argument');
+    if (Object.hasOwn(args, flag)) fail('duplicate-argument');
+    if (flag === '--json') { args[flag] = true; continue; }
+    const value = argv[++i];
+    if (!value?.trim() || value.startsWith('--')) fail('missing-argument');
+    args[flag] = value;
+  }
+  if (!args['--fleet'] || (command === 'sample-recommend' && !args['--input'])) fail('missing-argument');
+  const numeric = (name, fallback, reason) => {
+    if (args[name] === undefined) return fallback;
+    if (!/^\d+$/.test(args[name])) fail(reason);
+    return Number(args[name]);
+  };
+  const options = sampleOptions({ intervalMs: numeric('--interval-ms', 5000, 'sample-interval'),
+    timeoutMs: numeric('--timeout-ms', 10000, 'sample-timeout') });
+  const configPath = args['--config'] ?? defaultConfigPath;
+  const configText = read(configPath, 'config', false);
+  const configDigest = args['--config-digest'];
+  const config = parseFleetConfig(configText, configDigest);
+  const manifest = validateManifest(read(args['--fleet'], 'manifest'), config.hosts);
+  let input;
+  if (command === 'sample-recommend') {
+    input = read(args['--input'], 'input');
+    if (input?.configDigest !== undefined && input.configDigest !== configDigest) fail('config-digest-mismatch');
+    if (input?.configText !== undefined && input.configText !== configText) fail('config-snapshot-mismatch');
+    input = { ...input, configText, configDigest, request: args['--task']
+      ? { ...input.request, task: args['--task'] } : input?.request };
+    recommend(input, Date.now()); // Validate supplied security facts before any network read.
+  }
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  process.once('SIGINT', cancel); process.once('SIGTERM', cancel);
+  let samples;
+  try { samples = await sampleFleet(manifest, config.hosts, options, { signal: controller.signal }); }
+  finally { process.removeListener('SIGINT', cancel); process.removeListener('SIGTERM', cancel); }
+  const evaluatedAt = Date.now();
+  if (command === 'sample') {
+    process.stdout.write(`${JSON.stringify({ ...samples, telemetry: samples.telemetry.map((s) => ({ ...s, ageMs: evaluatedAt - s.receivedAt })),
+      configDigest, collectedAt: evaluatedAt })}\n`);
+    return 0;
+  }
+  input = { ...input, telemetry: samples.telemetry };
+  const recommendation = recommend(input, evaluatedAt);
+  process.stdout.write(`${JSON.stringify({ schemaVersion: 1, input, evaluatedAt, recommendation })}\n`);
+  return recommendation.selected ? 0 : 2;
+}

package/skills/axstack/scripts/fleet-sample-io.js

@@ -0,0 +1,59 @@
+import { readFile } from 'node:fs/promises';
+export const PROC_COMMAND = "cat /proc/stat && printf '\\n---AXSTACK-MEM---\\n' && cat /proc/meminfo";
+export function sshArgv(host) {
+  return ['ssh', '-T', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'IdentitiesOnly=yes',
+    '-o', 'ConnectTimeout=3', '-o', 'ConnectionAttempts=1', '-o', 'ServerAliveInterval=2',
+    '-o', 'ServerAliveCountMax=1', '-o', 'ControlMaster=no', '-o', 'ControlPath=none',
+    '-o', 'ClearAllForwardings=yes', '-o', 'PermitLocalCommand=no',
+    ...(host.user ? ['-l', host.user] : []), '--', host.destination, PROC_COMMAND];
+}
+export function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const cancel = () => { clearTimeout(timer); signal.removeEventListener('abort', cancel); reject(signal.reason); };
+    const timer = setTimeout(() => { signal.removeEventListener('abort', cancel); resolve(); }, ms);
+    signal.addEventListener('abort', cancel, { once: true });
+    if (signal.aborted) cancel();
+  });
+}
+async function limited(stream, signal) {
+  const reader = stream.getReader(); const chunks = []; let size = 0;
+  const cancel = () => { void reader.cancel(); };
+  signal.addEventListener('abort', cancel, { once: true });
+  try {
+    while (true) {
+      if (signal.aborted) throw signal.reason;
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 65536) throw Error('malformed');
+      chunks.push(value);
+    }
+    return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+  } finally {
+    signal.removeEventListener('abort', cancel);
+    await reader.cancel();
+    reader.releaseLock();
+  }
+}
+export async function readProc(host, signal, spawn = Bun.spawn) {
+  if (host.transport === 'local') {
+    const stat = await readFile('/proc/stat', { encoding: 'utf8', signal });
+    const mem = await readFile('/proc/meminfo', { encoding: 'utf8', signal });
+    return `${stat}\n---AXSTACK-MEM---\n${mem}`;
+  }
+  const child = spawn(sshArgv(host), { stdin: 'ignore', stdout: 'pipe', stderr: 'ignore' });
+  const cancel = () => child.kill('SIGKILL');
+  signal.addEventListener('abort', cancel, { once: true });
+  try {
+    if (signal.aborted) { cancel(); throw signal.reason; }
+    const output = await limited(child.stdout, signal);
+    const code = await child.exited;
+    if (signal.aborted) throw signal.reason;
+    if (code !== 0) throw Error('failed');
+    return output;
+  } finally {
+    signal.removeEventListener('abort', cancel);
+    child.kill('SIGKILL');
+    await child.exited;
+  }
+}

package/skills/axstack/scripts/fleet-sample-manifest.js

@@ -0,0 +1,34 @@
+import { record } from './fleet-config.js';
+const fail = (reason) => { throw Error(reason); };
+const keys = (obj, allowed) => record(obj) && Object.keys(obj).every((k) => allowed.includes(k));
+export function validateManifest(manifest, hosts) {
+  if (manifest?.schemaVersion !== 1) fail('schema-version: manifest');
+  if (!keys(manifest, ['schemaVersion', 'hosts']) || !Array.isArray(manifest.hosts)
+    || !manifest.hosts.length || manifest.hosts.length > 64) fail('manifest-schema');
+  const ids = new Set(); const destinations = new Set(); let local = false;
+  for (const h of manifest.hosts) {
+    if (!keys(h, ['hostId', 'environmentId', 'transport', 'destination', 'user'])) fail('manifest-schema');
+    if (!hosts.some((c) => c.id === h.hostId && c.environmentId === h.environmentId)) fail('manifest-host');
+    if (ids.has(h.hostId)) fail('manifest-duplicate');
+    ids.add(h.hostId);
+    if (!['local', 'ssh'].includes(h.transport)) fail('manifest-transport');
+    if (h.transport === 'local') {
+      if (h.destination !== undefined || h.user !== undefined) fail('manifest-schema');
+      if (local) fail('manifest-duplicate');
+      local = true;
+    } else {
+      // MagicDNS short names only. SSH aliases, IPs, ports and shell syntax are rejected.
+      if (typeof h.destination !== 'string' || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(h.destination)
+        || /^\d+$/.test(h.destination)) fail('manifest-destination');
+      if (h.user !== undefined && (typeof h.user !== 'string' || !/^[a-z_][a-z0-9_-]{0,31}$/.test(h.user))) fail('manifest-user');
+      if (destinations.has(h.destination)) fail('manifest-duplicate');
+      destinations.add(h.destination);
+    }
+  }
+  return manifest;
+}
+export function sampleOptions({ intervalMs = 5000, timeoutMs = 10000 } = {}) {
+  if (!Number.isSafeInteger(intervalMs) || intervalMs < 5000 || intervalMs > 60000) fail('sample-interval');
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < intervalMs + 1000 || timeoutMs > 120000) fail('sample-timeout');
+  return { intervalMs, timeoutMs };
+}