@aiwg/cli 2026.8.4 → 2026.8.7

package/dist/src/artifacts/move.js

@@ -108,21 +108,30 @@ export async function moveProjectArtifacts(options) {
     const source = path.resolve(options.from ? expandProjectArtifactPath(options.from, projectDir) : resolveProjectAiwgDir(projectDir));
     const destination = path.resolve(expandProjectArtifactPath(options.to, projectDir));
     const dryRun = options.dryRun === true;
+    const attach = options.attach === true;
     const reindex = options.reindex !== false;
     const syncFortemi = options.syncFortemi !== false;
-    if (samePath(source, destination)) {
+    if (!attach && samePath(source, destination)) {
         throw new Error(`Source and destination are the same directory: ${source}`);
     }
-    if (!existsSync(source)) {
+    if (!attach && !existsSync(source)) {
         throw new Error(`Source AIWG artifact directory does not exist: ${source}`);
     }
-    if (existsSync(destination) && !(await isEmptyDirectory(destination))) {
+    if (attach) {
+        if (!existsSync(destination) || !(await stat(destination)).isDirectory()) {
+            throw new Error(`Artifact root to attach does not exist or is not a directory: ${destination}`);
+        }
+        if (!existsSync(path.join(destination, 'aiwg.config'))) {
+            throw new Error(`Artifact root to attach has no aiwg.config: ${destination}`);
+        }
+    }
+    else if (existsSync(destination) && !(await isEmptyDirectory(destination))) {
         throw new Error(`Destination already exists and is not empty: ${destination}`);
     }
     const pointerValue = pointerValueFor(projectDir, destination);
     const pointerPath = path.join(projectDir, PROJECT_AIWG_LOCATION_FILE);
     const gitignoreUpdated = await ensureGitignorePointer(projectDir, dryRun);
-    if (!dryRun) {
+    if (!dryRun && !attach) {
         await moveDirectory(source, destination);
     }
     await writePointer(projectDir, pointerValue, dryRun);
@@ -144,7 +153,8 @@ export async function moveProjectArtifacts(options) {
         to: destination,
         pointerPath,
         pointerValue,
-        moved: !dryRun,
+        moved: !dryRun && !attach,
+        attached: attach && !dryRun,
         gitignoreUpdated,
         reindexed,
         fortemiSynced,

package/dist/src/cli/handlers/artifacts.js

@@ -5,9 +5,11 @@ function usage() {
         'aiwg artifacts — Manage the project AIWG artifact root',
         '',
         'Usage:',
-        '  aiwg artifacts move --to <path> [--from <path>] [--dry-run] [--force] [--no-reindex] [--no-sync]',
+        '  aiwg artifacts move --to <path> [--from <path>] [--dry-run] [--no-reindex] [--no-sync]',
+        '  aiwg artifacts attach --to <existing-path> [--dry-run] [--no-reindex] [--no-sync]',
         '',
         'Notes:',
+        '  move relocates a local artifact root; attach adopts an existing populated root.',
         '  --to points at the artifact directory itself, not its parent.',
         '  AIWG_ARTIFACTS_PATH overrides the generated .aiwg-location pointer.',
     ].join('\n');
@@ -30,7 +32,7 @@ export const artifactsHandler = {
         if (action === 'help' || ctx.args.includes('--help') || ctx.args.includes('-h')) {
             return { exitCode: 0, message: usage() };
         }
-        if (action !== 'move') {
+        if (action !== 'move' && action !== 'attach') {
             return { exitCode: 1, message: `Unknown artifacts action: ${action}\n\n${usage()}` };
         }
         const to = valueAfter(ctx.args, '--to');
@@ -42,12 +44,15 @@ export const artifactsHandler = {
                 projectDir: getProjectDir(ctx, ctx.args),
                 from: valueAfter(ctx.args, '--from'),
                 to,
+                attach: action === 'attach',
                 dryRun: ctx.dryRun || ctx.args.includes('--dry-run'),
                 force: ctx.args.includes('--force'),
                 reindex: !ctx.args.includes('--no-reindex'),
                 syncFortemi: !ctx.args.includes('--no-sync'),
             });
-            const verb = result.dryRun ? 'Would move' : 'Moved';
+            const verb = result.dryRun
+                ? (action === 'attach' ? 'Would attach' : 'Would move')
+                : (result.attached ? 'Attached' : 'Moved');
             return {
                 exitCode: 0,
                 message: [

package/dist/src/mcp/cli.mjs

@@ -415,7 +415,7 @@ CORE TOOLS (15, always registered):
   command-run                       Allow-listed CLI dispatch; confirmation-gated when needed
   artifact-read / artifact-write    Project .aiwg/ artifact IO
 
-OPT-IN TOOLSETS (51 additional tools):
+OPT-IN TOOLSETS (60 additional tools):
   flows          flow-list / flow-show / flow-run
   missions       mission-guide / mission-dispatch / mission-status
   memory         memory-* and reflections-* storage operations
@@ -426,9 +426,10 @@ OPT-IN TOOLSETS (51 additional tools):
   ralph          start / status / abort / attach
   mc             start / dispatch / status / stop / list
   ops            status / list / use / push
+  sandbox        fleet inventory / mutation / reconciliation and governed activity
 
 Enable opt-in tools:
-  AIWG_MCP_TOOLSETS=flows,missions,memory,kb,ralph aiwg mcp serve
+  AIWG_MCP_TOOLSETS=flows,missions,memory,kb,ralph,sandbox aiwg mcp serve
   aiwg mcp serve --toolsets=all
 
 RESOURCES:
@@ -451,6 +452,8 @@ TRANSPORTS:
 ENVIRONMENT:
   AIWG_ROOT          Path to AIWG installation (default: ~/.local/share/ai-writing-guide)
   AIWG_MCP_TOOLSETS  Comma-separated opt-in toolsets; use all for every toolset
+  AIWG_SANDBOX_MANAGEMENT_URL         Sandbox management API origin (HTTPS except loopback)
+  AIWG_SANDBOX_MANAGEMENT_TOKEN_FILE  Mode-0600 management bearer file for sandbox tools
 
 Docs:
   docs/integrations/mcp-capability-audit.md

package/dist/src/mcp/server.mjs

@@ -68,7 +68,7 @@ export function createServer() {
   // Opt-in subsystem toolsets (#1322-#1332)
   //
   // Enabled via AIWG_MCP_TOOLSETS env or `aiwg mcp serve --toolsets=`.
-  // Known: flows, missions, memory, kb, research, activity-log, index, ralph, mc, ops, all
+  // Known: flows, missions, memory, kb, research, activity-log, index, ralph, mc, ops, sandbox, all
   // Default: none (core only — discovery + command-run)
   // ============================================
   const requested = parseToolsets(process.env.AIWG_MCP_TOOLSETS || '');

package/dist/src/mcp/tools/agentic-sandbox.mjs

@@ -0,0 +1,232 @@
+/**
+ * Governed Agentic Sandbox fleet and activity MCP surface.
+ *
+ * Credentials are file-backed server configuration, never tool arguments.
+ * Every tool in this module uses the management bearer domain; executor-plane
+ * credentials are deliberately out of scope and cannot be substituted.
+ *
+ * @implements #2015
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+import { z } from 'zod';
+import { mcpError, mcpJson } from '../helpers.mjs';
+
+const FLEET_VERSION = 'agentic-orchestration/v1';
+const ACTIVITY_VERSION = 'activity.event/v1';
+const SCOPE_HEADERS = {
+  tenant_id: 'x-agentic-tenant-id',
+  host_id: 'x-agentic-host-id',
+  instance_id: 'x-agentic-instance-id',
+  agent_id: 'x-agentic-agent-id',
+};
+const RESTRICTED_KEY = /(?:^|_)(?:content|terminal|prompt|environment|env|credential|secret|password|authorization|bearer|token|private_key|certificate|restricted_(?:url|uri|link))(?:$|_)/i;
+
+function configuredBaseUrl(env = process.env) {
+  const raw = String(env.AIWG_SANDBOX_MANAGEMENT_URL ?? '').trim();
+  if (!raw) throw new Error('AIWG_SANDBOX_MANAGEMENT_URL is required for the sandbox toolset');
+  const url = new URL(raw);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error('AIWG_SANDBOX_MANAGEMENT_URL must be an HTTP(S) origin without credentials, query, or fragment');
+  }
+  if (url.protocol !== 'https:' && !['127.0.0.1', 'localhost', '::1'].includes(url.hostname)) {
+    throw new Error('AIWG_SANDBOX_MANAGEMENT_URL requires HTTPS outside loopback');
+  }
+  return url.toString().replace(/\/$/, '');
+}
+
+async function managementBearer(env = process.env) {
+  const tokenFile = String(env.AIWG_SANDBOX_MANAGEMENT_TOKEN_FILE ?? '').trim();
+  if (!tokenFile) throw new Error('AIWG_SANDBOX_MANAGEMENT_TOKEN_FILE is required for the sandbox toolset');
+  const metadata = await stat(tokenFile);
+  if (!metadata.isFile()) throw new Error('sandbox management token path is not a regular file');
+  if (process.platform !== 'win32' && (metadata.mode & 0o077) !== 0) {
+    throw new Error('sandbox management token file must not be accessible by group or other users');
+  }
+  const token = String(await readFile(tokenFile, 'utf8')).trim();
+  if (!token || /[\r\n]/.test(token)) throw new Error('sandbox management token file must contain one non-empty bearer token');
+  return token;
+}
+
+function containsRestricted(value) {
+  if (Array.isArray(value)) return value.some(containsRestricted);
+  if (!value || typeof value !== 'object') return false;
+  return Object.entries(value).some(([key, child]) => RESTRICTED_KEY.test(key) || containsRestricted(child));
+}
+
+function requireSafePayload(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  if (containsRestricted(value)) throw new Error(`${label} contains credential or restricted-content fields`);
+  return value;
+}
+
+function safeResponse(value) {
+  if (containsRestricted(value)) throw Object.assign(new Error('sandbox response contained prohibited credential or restricted-content fields'), { code: 'sandbox_restricted_response' });
+  return value;
+}
+
+function requireFleetRecord(record) {
+  requireSafePayload(record, 'fleet workload');
+  if (record.document_type !== 'workload' || record.api_version !== FLEET_VERSION) throw new Error(`fleet workload must use ${FLEET_VERSION}`);
+  if (!record.lineage || typeof record.lineage.child_id !== 'string' || !record.lineage.child_id) throw new Error('fleet workload requires lineage.child_id');
+  if (!record.status || !Number.isInteger(record.status.revision) || record.status.revision < 0) throw new Error('fleet workload requires a non-negative status.revision');
+  return record;
+}
+
+function requireInventory(value) {
+  safeResponse(value);
+  if (value?.document_type !== 'inventory' || value?.api_version !== FLEET_VERSION || !Number.isInteger(value?.inventory_revision) || !Array.isArray(value?.records)) {
+    throw new Error('invalid fleet inventory envelope');
+  }
+  value.records.forEach(requireFleetRecord);
+  return value;
+}
+
+function requireReconciliation(value) {
+  safeResponse(value);
+  if (value?.document_type !== 'reconciliation' || value?.api_version !== FLEET_VERSION || !Number.isInteger(value?.before_revision) || !Number.isInteger(value?.after_revision) || !Array.isArray(value?.rows)) {
+    throw new Error('invalid fleet reconciliation envelope');
+  }
+  return value;
+}
+
+function requireActivityEnvelope(value, scope, { eventsRequired = false, exportEnvelope = false } = {}) {
+  safeResponse(value);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid activity envelope');
+  if (!exportEnvelope && value.schema_version !== ACTIVITY_VERSION) throw new Error(`activity envelope must use ${ACTIVITY_VERSION}`);
+  if (!exportEnvelope && (!Array.isArray(value.coverage) || typeof value.completeness?.complete !== 'boolean')) throw new Error('activity envelope requires coverage and completeness');
+  if (eventsRequired && !Array.isArray(value.events)) throw new Error('activity timeline requires events');
+  for (const event of value.events ?? []) {
+    if (
+      event?.schema_version !== ACTIVITY_VERSION
+      || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(event?.event_id ?? '')
+      || !/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(event?.event_name ?? '')
+      || !['session', 'action', 'network', 'runtime', 'system', 'integrity'].includes(event?.plane)
+      || Number.isNaN(Date.parse(event?.occurred_at ?? ''))
+      || Number.isNaN(Date.parse(event?.observed_at ?? ''))
+      || !event?.source || typeof event.source.collector !== 'string' || !event.source.collector
+      || !['guest', 'runtime', 'host', 'control-plane', 'provider'].includes(event.source.layer)
+      || !['qemu-kvm', 'cloud-hypervisor', 'docker', 'host', 'unknown'].includes(event.source.runtime)
+      || !['observed', 'attested', 'self-reported', 'derived'].includes(event.source.trust)
+      || event?.sensitivity !== 'metadata'
+      || !['standard', 'security', 'forensic-hold', 'ephemeral'].includes(event?.retention_class)
+      || !event?.payload || typeof event.payload !== 'object' || Array.isArray(event.payload)
+      || !Number.isInteger(event?.integrity?.collector_sequence) || event.integrity.collector_sequence < 1
+    ) throw new Error('activity event violates schema or sensitivity policy');
+    for (const [key, expected] of Object.entries(scope)) if (event?.correlation?.[key] !== expected) throw new Error(`activity event ${key} scope mismatch`);
+  }
+  if (exportEnvelope) {
+    const manifest = value.manifest;
+    if (!manifest || manifest.tenant_id !== scope.tenant_id || !Number.isInteger(manifest.event_count) || manifest.event_count < 0 || !/^[0-9a-f]{64}$/.test(manifest.merkle_root ?? '') || typeof manifest.key_id !== 'string' || !manifest.key_id || typeof manifest.signature !== 'string' || !manifest.signature) {
+      throw new Error('activity export manifest is malformed or out of scope');
+    }
+  }
+  return value;
+}
+
+function typedResult(body, status, validate) {
+  if (status === 404 || status === 405) return mcpJson({ supported: false, reason: 'capability_absent', status });
+  if (status < 200 || status >= 300) {
+    const safe = safeResponse(body);
+    return {
+      ...mcpJson({ supported: true, ok: false, status, error_code: safe?.error ?? safe?.code ?? `http_${status}`, details: safe }),
+      isError: true,
+    };
+  }
+  return mcpJson({ supported: true, ok: true, status, data: validate(body) });
+}
+
+export class AgenticSandboxMcpClient {
+  constructor({ env = process.env, fetch = globalThis.fetch.bind(globalThis) } = {}) {
+    this.env = env;
+    this.fetch = fetch;
+  }
+
+  async request(path, { method = 'GET', body, headers = {}, validate = (value) => safeResponse(value) } = {}) {
+    const baseUrl = configuredBaseUrl(this.env);
+    const token = await managementBearer(this.env);
+    const response = await this.fetch(`${baseUrl}${path}`, {
+      method,
+      headers: { accept: 'application/json', authorization: `Bearer ${token}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }), ...headers },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    let parsed;
+    try {
+      parsed = await response.json();
+    } catch {
+      if (response.status === 404 || response.status === 405) parsed = {};
+      else return mcpError(`sandbox returned non-JSON HTTP ${response.status}`);
+    }
+    try {
+      return typedResult(parsed, response.status, validate);
+    } catch (error) {
+      return mcpError(`${error.code ?? 'sandbox_malformed_response'}: ${error.message}`);
+    }
+  }
+}
+
+const scopeSchema = {
+  tenant_id: z.string().min(1).max(255).regex(/^[^\r\n]+$/),
+  host_id: z.string().min(1).max(255).regex(/^[^\r\n]+$/),
+  instance_id: z.string().min(1).max(255).regex(/^[^\r\n]+$/),
+  agent_id: z.string().min(1).max(255).regex(/^[^\r\n]+$/),
+};
+const activityFilterSchema = z.object({
+  event_name: z.string().min(1).max(255).optional(), collector: z.string().min(1).max(255).optional(),
+  trust: z.string().min(1).max(255).optional(), plane: z.string().min(1).max(255).optional(),
+  outcome: z.string().min(1).max(255).optional(), session_id: z.string().min(1).max(255).optional(),
+  mission_id: z.string().min(1).max(255).optional(), task_id: z.string().min(1).max(255).optional(),
+  tool_call_id: z.string().min(1).max(255).optional(), command_id: z.string().min(1).max(255).optional(),
+  process_id: z.string().min(1).max(255).optional(), trace_id: z.string().regex(/^[0-9a-f]{32}$/).optional(),
+  since: z.string().datetime().optional(), until: z.string().datetime().optional(), limit: z.number().int().min(1).max(1000).optional(),
+}).strict().optional();
+
+function scopeHeaders(args) {
+  return Object.fromEntries(Object.entries(SCOPE_HEADERS).map(([key, header]) => [header, args[key]]));
+}
+
+function activityQuery(filter = {}) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(filter)) query.set(key, String(value));
+  return query.size ? `?${query}` : '';
+}
+
+function confirmationError(name) {
+  return mcpError(`${name} requires confirmed=true`, { requiresConfirmation: true, remediation: 'Review the exact scope and payload, then re-invoke with confirmed=true.' });
+}
+
+export function registerAgenticSandboxToolset(server, { client = new AgenticSandboxMcpClient() } = {}) {
+  const register = (name, config, handler) => server.registerTool(name, config, async (args) => {
+    try { return await handler(args); } catch (error) { return mcpError(`${name}: ${error.message}`); }
+  });
+
+  register('sandbox-fleet-list', { title: 'List Agentic Sandbox fleet workloads', description: 'Read revisioned v2026.8.3+ fleet inventory using the management credential domain.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION) }, annotations: { readOnlyHint: true, destructiveHint: false } },
+    () => client.request('/api/v2/fleet/workloads', { validate: requireInventory }));
+  register('sandbox-fleet-get', { title: 'Get Agentic Sandbox fleet workload', description: 'Read one revisioned fleet workload by child identity.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), child_id: z.string().min(1).max(255) }, annotations: { readOnlyHint: true, destructiveHint: false } },
+    ({ child_id }) => client.request(`/api/v2/fleet/workloads/${encodeURIComponent(child_id)}`, { validate: requireFleetRecord }));
+  register('sandbox-fleet-reconcile-preview', { title: 'Preview fleet reconciliation', description: 'Compute a read-only reconciliation preview from inventory; never calls POST /reconcile.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), before_revision: z.number().int().min(0), child_ids: z.array(z.string().min(1).max(255)).max(1000) }, annotations: { readOnlyHint: true, destructiveHint: false } },
+    async ({ before_revision, child_ids }) => client.request('/api/v2/fleet/workloads', { validate: (value) => {
+      const inventory = requireInventory(value);
+      const byId = new Map(inventory.records.map((record) => [record.lineage.child_id, record]));
+      return { document_type: 'reconciliation-preview', api_version: FLEET_VERSION, before_revision, inventory_revision: inventory.inventory_revision, stale: before_revision !== inventory.inventory_revision, rows: child_ids.map((child_id) => ({ child_id, present: byId.has(child_id), observed_state: byId.get(child_id)?.status?.observed_state ?? 'unknown', revision: byId.get(child_id)?.status?.revision ?? null })) };
+    } }));
+  register('sandbox-fleet-admit', { title: 'Admit Agentic Sandbox fleet workload', description: 'Mutating fleet admission; requires an exact v1 workload and confirmed=true.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), workload: z.record(z.unknown()), confirmed: z.boolean().default(false) }, annotations: { readOnlyHint: false, destructiveHint: true } },
+    ({ workload, confirmed }) => confirmed ? client.request('/api/v2/fleet/workloads', { method: 'POST', body: requireFleetRecord(workload), validate: (value) => ({ replayed: value?.replayed === true, workload: requireFleetRecord(value?.workload) }) }) : confirmationError('sandbox-fleet-admit'));
+  register('sandbox-fleet-observe', { title: 'Record fleet workload observation', description: 'Mutating monotonic observation update; requires confirmed=true and expected revision.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), child_id: z.string().min(1).max(255), expected_revision: z.number().int().min(0), status: z.record(z.unknown()), runtime_identity: z.object({ session_id: z.string().optional(), task_id: z.string().optional(), command_id: z.string().optional() }).strict().optional(), confirmed: z.boolean().default(false) }, annotations: { readOnlyHint: false, destructiveHint: true } },
+    ({ child_id, expected_revision, status, runtime_identity, confirmed }) => confirmed ? client.request(`/api/v2/fleet/workloads/${encodeURIComponent(child_id)}/observations`, { method: 'POST', body: requireSafePayload({ expected_revision, status, ...(runtime_identity ? { runtime_identity } : {}) }, 'fleet observation'), validate: requireFleetRecord }) : confirmationError('sandbox-fleet-observe'));
+  register('sandbox-fleet-reconcile', { title: 'Reconcile fleet workloads', description: 'Mutating restart reconciliation; requires confirmed=true.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), before_revision: z.number().int().min(0), child_ids: z.array(z.string().min(1).max(255)).max(1000), confirmed: z.boolean().default(false) }, annotations: { readOnlyHint: false, destructiveHint: true } },
+    ({ before_revision, child_ids, confirmed }) => confirmed ? client.request('/api/v2/fleet/reconcile', { method: 'POST', body: { before_revision, child_ids }, validate: requireReconciliation }) : confirmationError('sandbox-fleet-reconcile'));
+
+  for (const [kind, eventsRequired] of [['coverage', false], ['timeline', true]]) {
+    register(`sandbox-activity-${kind}`, { title: `${kind === 'coverage' ? 'Inspect coverage for' : 'Read timeline from'} Agentic Sandbox activity`, description: `Read governed, exactly scoped activity ${kind}; preserves capability and authorization status.`, inputSchema: { contract_version: z.literal(ACTIVITY_VERSION).default(ACTIVITY_VERSION), ...scopeSchema, filter: activityFilterSchema }, annotations: { readOnlyHint: true, destructiveHint: false } },
+      (args) => { const scope = Object.fromEntries(Object.keys(SCOPE_HEADERS).map((key) => [key, args[key]])); return client.request(`/api/v2/activity/${kind}${activityQuery(args.filter)}`, { headers: scopeHeaders(args), validate: (value) => requireActivityEnvelope(value, scope, { eventsRequired }) }); });
+  }
+  register('sandbox-activity-export', { title: 'Export signed Agentic Sandbox activity evidence', description: 'Evidence export requires confirmed=true even though it does not mutate server state.', inputSchema: { contract_version: z.literal(ACTIVITY_VERSION).default(ACTIVITY_VERSION), ...scopeSchema, filter: activityFilterSchema, confirmed: z.boolean().default(false) }, annotations: { readOnlyHint: false, destructiveHint: true } },
+    (args) => { if (!args.confirmed) return confirmationError('sandbox-activity-export'); const scope = Object.fromEntries(Object.keys(SCOPE_HEADERS).map((key) => [key, args[key]])); return client.request('/api/v2/activity/export', { method: 'POST', headers: scopeHeaders(args), body: args.filter ?? {}, validate: (value) => requireActivityEnvelope(value, scope, { eventsRequired: true, exportEnvelope: true }) }); });
+}
+
+export const AGENTIC_SANDBOX_TOOL_NAMES = [
+  'sandbox-fleet-list', 'sandbox-fleet-get', 'sandbox-fleet-reconcile-preview',
+  'sandbox-fleet-admit', 'sandbox-fleet-observe', 'sandbox-fleet-reconcile',
+  'sandbox-activity-coverage', 'sandbox-activity-timeline', 'sandbox-activity-export',
+];

package/dist/src/mcp/tools/subsystems.mjs

@@ -17,6 +17,7 @@
 import { z } from 'zod';
 import { runAiwgCli, mcpError, mcpJson } from '../helpers.mjs';
 import { registerFlowToolset, registerMissionToolset } from './orchestration.mjs';
+import { registerAgenticSandboxToolset } from './agentic-sandbox.mjs';
 
 /**
  * Wrap an `aiwg <subsystem> <verb>` CLI call as an MCP tool.
@@ -586,6 +587,7 @@ const TOOLSET_REGISTRY = {
   ralph: registerRalphToolset,
   mc: registerMcToolset,
   ops: registerOpsToolset,
+  sandbox: registerAgenticSandboxToolset,
 };
 
 /**

package/dist/src/resources/web-release.d.ts

@@ -49,6 +49,13 @@ export interface WebReleaseOptions {
     credentialProvider?: () => Promise<string | null>;
     /** Test/development escape hatch. HTTP remains restricted to loopback. */
     allowInsecureLoopbackHttp?: boolean;
+    /** Structured cache diagnostics; never includes URLs, headers, or credentials. */
+    onDiagnostic?: (diagnostic: WebReleaseDiagnostic) => void;
+}
+export interface WebReleaseDiagnostic {
+    resource: "channel" | "version-index";
+    outcome: "conditional-hit" | "revalidated" | "unconditional";
+    validator: "etag" | "last-modified" | "none";
 }
 export interface VerifiedReleaseDescriptor {
     path: string;

package/dist/src/resources/web-release.js

@@ -386,6 +386,69 @@ async function fetchBytes(fetcher, url, label, maxBytes, bearerToken) {
         clearTimeout(timeout);
     }
 }
+function validatorFromResponse(response, payloadSha256) {
+    // Preserve the origin's ETag octets, including the W/ prefix for weak tags.
+    // HTTP validators only suppress transfer; Ed25519 and SHA-256 remain the
+    // authority for every cached representation accepted by this module.
+    const etag = response.headers.get("etag")?.trim();
+    const lastModified = response.headers.get("last-modified")?.trim();
+    if (!etag && !lastModified)
+        return undefined;
+    return {
+        schemaVersion: "aiwg.http-validator/v1",
+        payloadSha256,
+        ...(etag ? { etag } : { lastModified: lastModified }),
+    };
+}
+function readMetadataValidator(pathname, payloadSha256) {
+    if (!fs.existsSync(pathname))
+        return undefined;
+    const value = parseJson(readVerifiedRegularFile(pathname, {
+        label: "cached HTTP metadata validator",
+        maxBytes: MAX_COMPLETION_MARKER_BYTES,
+    }), "cached HTTP metadata validator");
+    if (!isRecord(value) || value.schemaVersion !== "aiwg.http-validator/v1" || value.payloadSha256 !== payloadSha256) {
+        throw new Error("cached HTTP metadata validator does not match the verified signed payload");
+    }
+    const etag = typeof value.etag === "string" && value.etag.trim() ? value.etag.trim() : undefined;
+    const lastModified = typeof value.lastModified === "string" && value.lastModified.trim() ? value.lastModified.trim() : undefined;
+    if (!etag && !lastModified)
+        throw new Error("cached HTTP metadata validator is empty");
+    return { schemaVersion: "aiwg.http-validator/v1", payloadSha256, ...(etag ? { etag } : { lastModified }) };
+}
+async function fetchMetadata(fetcher, url, label, maxBytes, cachedValidator) {
+    const headers = { "accept-encoding": "identity" };
+    if (cachedValidator?.etag)
+        headers["if-none-match"] = cachedValidator.etag;
+    else if (cachedValidator?.lastModified)
+        headers["if-modified-since"] = cachedValidator.lastModified;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), RESOURCE_FETCH_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetcher(url, { redirect: "error", headers, signal: controller.signal });
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new Error(`${label} request timed out after ${RESOURCE_FETCH_TIMEOUT_MS}ms`);
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    if (response.status === 304) {
+        if (!cachedValidator)
+            throw new Error(`${label} returned 304 without a verified cached representation`);
+        return {
+            notModified: true,
+            validator: validatorFromResponse(response, cachedValidator.payloadSha256) ?? cachedValidator,
+        };
+    }
+    if (!response.ok)
+        throw new Error(`${label} fetch failed (${response.status}): ${url}`);
+    const bytes = await fetchBytes(async () => response, url, label, maxBytes);
+    return { notModified: false, bytes, validator: validatorFromResponse(response, sha256(bytes)) };
+}
 function verifyDescriptor(bytes, descriptor, label = descriptor.path) {
     if (bytes.byteLength !== descriptor.size || sha256(bytes) !== descriptor.sha256) {
         throw new Error(`release descriptor size or digest verification failed: ${label}`);
@@ -623,7 +686,14 @@ function readCachedChannel(cacheRoot, channel, publicKeyPem) {
             if (candidate.name !== `${manifest.sequence}-${digest}`) {
                 throw new Error(`cached channel ${channel} generation name does not match its signed metadata`);
             }
-            valid.push({ manifest, bytes, signatureBytes, digest });
+            let validator;
+            try {
+                validator = readMetadataValidator(path.join(dir, "http-validator.json"), digest);
+            }
+            catch {
+                validator = undefined;
+            }
+            valid.push({ manifest, bytes, signatureBytes, digest, validator });
         }
         catch {
             corrupt = true;
@@ -658,10 +728,23 @@ function readCachedVersionIndex(cacheRoot, publicKeyPem) {
         label: "cached resource version index signature",
         maxBytes: MAX_SIGNATURE_BYTES,
     });
-    verifySignedResourceBytes(bytes, signatureBytes, publicKeyPem, "cached resource version index");
-    return validateVersionIndex(parseJson(bytes, "cached resource version index"));
+    const digest = verifySignedResourceBytes(bytes, signatureBytes, publicKeyPem, "cached resource version index");
+    return {
+        index: validateVersionIndex(parseJson(bytes, "cached resource version index")),
+        bytes,
+        signatureBytes,
+        digest,
+        validator: (() => {
+            try {
+                return readMetadataValidator(path.join(dir, "http-validator.json"), digest);
+            }
+            catch {
+                return undefined;
+            }
+        })(),
+    };
 }
-function cacheVersionIndex(cacheRoot, bytes, signatureBytes) {
+function cacheVersionIndex(cacheRoot, bytes, signatureBytes, validator) {
     const target = versionIndexCacheDir(cacheRoot);
     const stagingRoot = path.join(cacheRoot, ".staging", "versions");
     fs.mkdirSync(stagingRoot, { recursive: true });
@@ -669,6 +752,8 @@ function cacheVersionIndex(cacheRoot, bytes, signatureBytes) {
     try {
         fs.writeFileSync(path.join(stage, "versions.json"), bytes, { flag: "wx" });
         fs.writeFileSync(path.join(stage, "versions.sig"), signatureBytes, { flag: "wx" });
+        if (validator)
+            fs.writeFileSync(path.join(stage, "http-validator.json"), `${JSON.stringify(validator)}\n`, { flag: "wx" });
         if (fs.existsSync(target))
             fs.rmSync(target, { recursive: true, force: true });
         installGeneration(stage, target);
@@ -678,19 +763,33 @@ function cacheVersionIndex(cacheRoot, bytes, signatureBytes) {
         throw error;
     }
 }
-async function fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem) {
-    const indexBytes = await fetchBytes(fetcher, resourceUrl(base, "resources/versions.json"), "resource version index", MAX_VERSION_INDEX_BYTES);
+async function fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem, diagnostic) {
+    let cached = null;
+    try {
+        cached = readCachedVersionIndex(cacheRoot, publicKeyPem);
+    }
+    catch {
+        cached = null;
+    }
+    const fetched = await fetchMetadata(fetcher, resourceUrl(base, "resources/versions.json"), "resource version index", MAX_VERSION_INDEX_BYTES, cached?.validator);
+    if (fetched.notModified) {
+        cacheVersionIndex(cacheRoot, cached.bytes, cached.signatureBytes, fetched.validator);
+        diagnostic?.({ resource: "version-index", outcome: "conditional-hit", validator: cached.validator.etag ? "etag" : "last-modified" });
+        return cached.index;
+    }
+    const indexBytes = fetched.bytes;
     const signatureBytes = await fetchBytes(fetcher, resourceUrl(base, "resources/versions.sig"), "resource version index signature", MAX_SIGNATURE_BYTES);
     verifySignedResourceBytes(indexBytes, signatureBytes, publicKeyPem, "resource version index");
     const index = validateVersionIndex(parseJson(indexBytes, "resource version index"));
-    cacheVersionIndex(cacheRoot, indexBytes, signatureBytes);
+    cacheVersionIndex(cacheRoot, indexBytes, signatureBytes, fetched.validator);
+    diagnostic?.({ resource: "version-index", outcome: cached?.validator ? "revalidated" : "unconditional", validator: fetched.validator?.etag ? "etag" : fetched.validator?.lastModified ? "last-modified" : "none" });
     return index;
 }
-async function resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, offline) {
+async function resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, offline, diagnostic) {
     if (offline) {
         const cached = readCachedVersionIndex(cacheRoot, publicKeyPem);
         if (cached)
-            return cached;
+            return cached.index;
         const versions = cachedReleaseVersions(cacheRoot).flatMap((version) => cachedDigests(cacheRoot, version).map((digest) => ({
             version,
             releaseManifest: `/resources/${version}/manifest.json`,
@@ -703,12 +802,14 @@ async function resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, offli
     if (!fetcher)
         throw new Error("No fetch implementation is available for AIWG web resources");
     try {
-        return await fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem);
+        return await fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem, diagnostic);
     }
     catch (error) {
+        if (error instanceof Error && /fetch failed \((?:401|403|429|5\d\d)\)/.test(error.message))
+            throw error;
         const cached = readCachedVersionIndex(cacheRoot, publicKeyPem);
         if (cached)
-            return cached;
+            return cached.index;
         throw error;
     }
 }
@@ -776,7 +877,7 @@ function fsyncTree(root) {
     }
     fsyncDirectory(root);
 }
-function cacheChannel(cacheRoot, manifest, bytes, signatureBytes, digest) {
+function cacheChannel(cacheRoot, manifest, bytes, signatureBytes, digest, validator) {
     const root = channelGenerationRoot(cacheRoot, manifest.channel);
     const stagingRoot = path.join(cacheRoot, ".staging", "channels");
     fs.mkdirSync(stagingRoot, { recursive: true });
@@ -784,6 +885,8 @@ function cacheChannel(cacheRoot, manifest, bytes, signatureBytes, digest) {
     try {
         fs.writeFileSync(path.join(stage, "channel.json"), bytes, { flag: "wx" });
         fs.writeFileSync(path.join(stage, "channel.sig"), signatureBytes, { flag: "wx" });
+        if (validator)
+            fs.writeFileSync(path.join(stage, "http-validator.json"), `${JSON.stringify(validator)}\n`, { flag: "wx" });
         const target = path.join(root, `${manifest.sequence}-${digest}`);
         if (fs.existsSync(target)) {
             let matches = false;
@@ -797,7 +900,11 @@ function cacheChannel(cacheRoot, manifest, bytes, signatureBytes, digest) {
                         readVerifiedRegularFile(path.join(target, "channel.sig"), {
                             label: `cached channel ${manifest.channel} signature`,
                             maxBytes: MAX_SIGNATURE_BYTES,
-                        }).equals(Buffer.from(signatureBytes));
+                        }).equals(Buffer.from(signatureBytes)) &&
+                        (validator
+                            ? readMetadataValidator(path.join(target, "http-validator.json"), digest)?.etag === validator.etag &&
+                                readMetadataValidator(path.join(target, "http-validator.json"), digest)?.lastModified === validator.lastModified
+                            : !fs.existsSync(path.join(target, "http-validator.json")));
             }
             catch {
                 matches = false;
@@ -921,8 +1028,20 @@ export async function resolveWebRelease(options = {}) {
         return fetchAndCacheRelease(base, fetcher, cacheRoot, selector, selector.value, publicKeyPem);
     }
     if (selector.kind === "range" || selector.kind === "digest") {
+        if (!options.offline && selector.kind === "digest") {
+            for (const version of cachedReleaseVersions(cacheRoot)) {
+                if (!cachedDigests(cacheRoot, version).includes(selector.digest))
+                    continue;
+                try {
+                    return verifyCachedGeneration(cacheRoot, version, selector.digest, selector, publicKeyPem, base, selector.digest);
+                }
+                catch {
+                    // A corrupt immutable generation cannot bypass signed index resolution.
+                }
+            }
+        }
         const fetcher = authorize;
-        const index = await resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, options.offline);
+        const index = await resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, options.offline, options.onDiagnostic);
         const selected = selectVersionFromIndex(index, selector);
         if (options.offline) {
             return resolveOfflineExact(cacheRoot, selector, selected.version, publicKeyPem, base, selected.releaseManifestSha256);
@@ -941,11 +1060,23 @@ export async function resolveWebRelease(options = {}) {
     if (!fetcher)
         throw new Error("No fetch implementation is available for AIWG web resources");
     const channelPrefix = `resources/channels/${selector.value}`;
-    const channelBytes = await fetchBytes(fetcher, resourceUrl(base, `${channelPrefix}.json`), `channel ${selector.value}`, MAX_SIGNED_METADATA_BYTES);
+    let prior = null;
+    try {
+        prior = readCachedChannel(cacheRoot, selector.value, publicKeyPem);
+    }
+    catch {
+        prior = null;
+    }
+    const fetched = await fetchMetadata(fetcher, resourceUrl(base, `${channelPrefix}.json`), `channel ${selector.value}`, MAX_SIGNED_METADATA_BYTES, prior?.validator);
+    if (fetched.notModified) {
+        cacheChannel(cacheRoot, prior.manifest, prior.bytes, prior.signatureBytes, prior.digest, fetched.validator);
+        options.onDiagnostic?.({ resource: "channel", outcome: "conditional-hit", validator: prior.validator.etag ? "etag" : "last-modified" });
+        return fetchAndCacheRelease(base, fetcher, cacheRoot, selector, prior.manifest.version, publicKeyPem, prior.manifest.releaseManifestSha256, prior.manifest.sequence);
+    }
+    const channelBytes = fetched.bytes;
     const channelSignatureBytes = await fetchBytes(fetcher, resourceUrl(base, `${channelPrefix}.sig`), `channel ${selector.value} signature`, MAX_SIGNATURE_BYTES);
     const channelDigest = verifySignedResourceBytes(channelBytes, channelSignatureBytes, publicKeyPem, `channel ${selector.value}`);
     const channel = validateChannelManifest(parseJson(channelBytes, `channel ${selector.value}`), selector.value);
-    const prior = readCachedChannel(cacheRoot, selector.value, publicKeyPem);
     if (prior && channel.sequence < prior.manifest.sequence) {
         throw new Error(`channel ${selector.value} sequence rollback detected (${channel.sequence} < ${prior.manifest.sequence})`);
     }
@@ -957,7 +1088,8 @@ export async function resolveWebRelease(options = {}) {
         throw new Error(`channel ${selector.value} sequence ${channel.sequence} has conflicting signed metadata`);
     }
     const release = await fetchAndCacheRelease(base, fetcher, cacheRoot, selector, channel.version, publicKeyPem, channel.releaseManifestSha256, channel.sequence);
-    cacheChannel(cacheRoot, channel, channelBytes, channelSignatureBytes, channelDigest);
+    cacheChannel(cacheRoot, channel, channelBytes, channelSignatureBytes, channelDigest, fetched.validator);
+    options.onDiagnostic?.({ resource: "channel", outcome: prior?.validator ? "revalidated" : "unconditional", validator: fetched.validator?.etag ? "etag" : fetched.validator?.lastModified ? "last-modified" : "none" });
     return release;
 }
 export async function fetchVerifiedRawResource(release, resourcePath, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.4",
+  "version": "2026.8.7",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",