harness-everything 0.2.2 → 0.4.0

package/fable-mode/scripts/model-selector.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const MATRIX_PATH = path.join(__dirname, '..', 'model-matrix.json');
+const SESSION_REGISTRY_DIR = 'session-workspaces';
+const SESSION_REGISTRY_VERSION = 1;
+const UNBOUND_WORKSPACE_KEY = 'unbound-workspace';
+const HOST_CONTEXT_KEYS = ['host_id', 'hostId', 'agent_id', 'agentId', 'client_id', 'clientId', 'machine_id', 'machineId', 'runtime_id', 'runtimeId'];
+
+// This script ships standalone (copied whole into every install target,
+// e.g. .claude/skills/fable-mode/scripts/), so it can't require the source
+// repo's scripts/lib/workspace.js. The audit log is genuine runtime state
+// though - not a project artifact - so it needs to land in the same global,
+// workspace-keyed root that hooks/scripts/lib/harness-state.js resolves to,
+// not scattered under cwd (issue #42). Duplicated here, algorithm-for-
+// algorithm, same as opencode-plugin/index.mjs's own inlined copy.
+function findWorkspaceRoot(startPath, allowNonGit = false) {
+  if (typeof startPath !== 'string' || !startPath.trim()) return null;
+  let dir = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.git'))) return canonicalPath(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return allowNonGit ? canonicalPath(startPath) : null;
+}
+
+function canonicalPath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const resolved = path.resolve(value);
+  try { return fs.realpathSync(resolved); } catch (err) { return resolved; }
+}
+
+function getSessionId(context) {
+  if (!context || typeof context !== 'object') return null;
+  return context.session_id || context.sessionId || null;
+}
+
+function getHostId(context) {
+  if (!context || typeof context !== 'object') return process.env.FABLE_HOST_ID || process.env.HARNESS_HOST_ID || null;
+  for (const key of HOST_CONTEXT_KEYS) {
+    if (typeof context[key] === 'string' && context[key].trim()) return context[key].trim();
+  }
+  return process.env.FABLE_HOST_ID || process.env.HARNESS_HOST_ID || null;
+}
+
+function getSessionRegistryPath(sessionId, hostId) {
+  const namespace = hostId ? `${hostId}\0${sessionId}` : String(sessionId);
+  const hash = crypto.createHash('sha256').update(namespace).digest('hex');
+  const home = process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything');
+  return path.join(home, SESSION_REGISTRY_DIR, `${hash}.json`);
+}
+
+function readRegistryRecord(filePath) {
+  try {
+    const record = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return record.version === SESSION_REGISTRY_VERSION && typeof record.workspaceRoot === 'string' ? record : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+function getBoundWorkspace(sessionId, context) {
+  if (!sessionId) return null;
+  const hostId = getHostId(context);
+  const records = [];
+  const preferred = readRegistryRecord(getSessionRegistryPath(sessionId, hostId));
+  if (preferred && (!hostId || !preferred.hostId || preferred.hostId === hostId)) records.push(preferred);
+  if (hostId) {
+    const unscoped = readRegistryRecord(getSessionRegistryPath(sessionId, null));
+    if (unscoped && !unscoped.hostId) records.push(unscoped);
+  }
+  try {
+    const home = process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything');
+    const dir = path.join(home, SESSION_REGISTRY_DIR);
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+      const record = readRegistryRecord(path.join(dir, entry.name));
+      if (record && record.sessionId === sessionId && (!hostId || !record.hostId || record.hostId === hostId)) records.push(record);
+    }
+  } catch (err) { /* no registry yet */ }
+  const unique = [...new Map(records.map(record => [`${record.hostId || ''}\0${record.workspaceRoot}`, record])).values()];
+  if (unique.length === 1) return unique[0].workspaceRoot;
+  if (unique.length > 1 && new Set(unique.map(record => canonicalPath(record.workspaceRoot))).size === 1) return unique[0].workspaceRoot;
+  return null;
+}
+
+function getRegistryRecord(sessionId, context) {
+  const root = getBoundWorkspace(sessionId, context);
+  return root ? { workspaceRoot: root } : null;
+}
+
+function bindWorkspace(sessionId, root, context) {
+  if (!sessionId) return;
+  if (!root) return;
+  const hostId = getHostId(context);
+  const target = getSessionRegistryPath(sessionId, hostId);
+  const record = { version: SESSION_REGISTRY_VERSION, sessionId, hostId: hostId || undefined, workspaceRoot: root, updatedAt: new Date().toISOString() };
+  let temporary;
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(record, null, 2), 'utf8');
+    if (fs.existsSync(target)) fs.unlinkSync(temporary);
+    else fs.renameSync(temporary, target);
+  } catch (err) {
+    try { if (temporary && fs.existsSync(temporary)) fs.unlinkSync(temporary); } catch (cleanupErr) { /* ignore */ }
+  }
+}
+
+function getWorkspaceRoot(context) {
+  const sessionId = getSessionId(context);
+  const bound = getRegistryRecord(sessionId, context);
+  if (bound) return bound.workspaceRoot;
+  const explicit = context && (context.workspace_root || context.workspaceRoot || context.cwd);
+  const hostRoot = explicit || process.env.HARNESS_WORKSPACE_ROOT || process.env.FABLE_WORKSPACE_ROOT;
+  const root = findWorkspaceRoot(hostRoot || process.cwd(), Boolean(hostRoot));
+  if (sessionId) bindWorkspace(sessionId, root, context);
+  return root;
+}
+
+function getWorkspaceStateDir(root) {
+  const home = process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything');
+  if (!root) return path.join(home, 'workspaces', UNBOUND_WORKSPACE_KEY);
+  let real = path.resolve(root);
+  try { real = fs.realpathSync(real); } catch (err) { /* path may not exist yet */ }
+  const slug = path.basename(real).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'workspace';
+  const hashInput = process.platform === 'win32' ? real.toLowerCase() : real;
+  const hash = crypto.createHash('sha1').update(hashInput).digest('hex').slice(0, 12);
+  return path.join(home, 'workspaces', `${slug}-${hash}`);
+}
+const REQUIRED = ['stageBrief', 'passCondition', 'verificationCommand', 'verifierResult'];
+const VALID_VERIFIER_RESULTS = new Set(['pending', 'pass', 'fail', 'not-run', 'blocked']);
+
+function loadMatrix() {
+  return JSON.parse(fs.readFileSync(MATRIX_PATH, 'utf8'));
+}
+
+function normalizeModel(value, matrix) {
+  const input = String(value || '').trim().toLowerCase();
+  for (const [model, definition] of Object.entries(matrix.modes)) {
+    if (definition.aliases.includes(input)) return model;
+  }
+  return null;
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--help' || token === '-h') return { help: true };
+    if (!token.startsWith('--')) throw new Error(`unknown argument: ${token}`);
+    const key = token.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    const value = argv[i + 1];
+    if (typeof value === 'undefined' || value.startsWith('--')) throw new Error(`missing value for --${key}`);
+    args[key] = value;
+    i += 1;
+  }
+  return args;
+}
+
+function resolveMode(input, matrix = loadMatrix()) {
+  const requestedModel = normalizeModel(input.requested, matrix);
+  if (!requestedModel) throw new Error('requested model must be one of haiku, sonnet, sonnect, or opus');
+
+  const availableModels = String(input.available || '')
+    .split(/[\s,]+/)
+    .map(model => normalizeModel(model, matrix))
+    .filter(Boolean);
+  const availableAgents = String(input.availableAgents || '')
+    .split(/[\s,]+/)
+    .map(agent => agent.trim())
+    .filter(Boolean);
+  const fallback = input.fallback || 'stop';
+  if (!Object.prototype.hasOwnProperty.call(matrix.fallbacks, fallback)) {
+    throw new Error('fallback must be inline or stop');
+  }
+
+  for (const field of REQUIRED) {
+    if (!String(input[field] || '').trim()) throw new Error(`${field} is required for an auditable stage`);
+  }
+  if (!VALID_VERIFIER_RESULTS.has(input.verifierResult)) {
+    throw new Error(`verifierResult must be one of ${[...VALID_VERIFIER_RESULTS].join(', ')}`);
+  }
+
+  const requestedAgent = matrix.modes[requestedModel].agent;
+  const modelAvailable = availableModels.includes(requestedModel);
+  const agentAvailable = availableAgents.includes(requestedAgent);
+  const selected = modelAvailable && agentAvailable;
+  const hostModel = String(input.hostModel || 'current-host').trim();
+  const fallbackDefinition = matrix.fallbacks[fallback];
+  const status = selected ? 'selected' : fallbackDefinition.status;
+  const effectiveModel = selected
+    ? requestedModel
+    : fallback === 'inline'
+      ? hostModel
+      : fallbackDefinition.effectiveModel;
+  const missing = [];
+  if (!modelAvailable) missing.push(`${requestedModel} is not in availableModels`);
+  if (!agentAvailable) missing.push(`${requestedAgent} is not in availableAgents`);
+  const fallbackReason = selected
+    ? 'none'
+    : `${fallbackDefinition.reason}: ${missing.join('; ')}`;
+
+  return {
+    schemaVersion: matrix.schemaVersion,
+    status,
+    requestedModel,
+    requestedInput: String(input.requested).trim(),
+    effectiveModel,
+    availableModels: [...new Set(availableModels)],
+    availableAgents: [...new Set(availableAgents)],
+    fallbackPolicy: fallback,
+    fallbackReason,
+    agent: selected ? requestedAgent : null,
+    modelRole: matrix.modes[requestedModel].role,
+    stageBrief: String(input.stageBrief).trim(),
+    passCondition: String(input.passCondition).trim(),
+    verificationCommand: String(input.verificationCommand).trim(),
+    verifierResult: input.verifierResult,
+    escalationRequired: status === 'blocked'
+  };
+}
+
+function printHelp() {
+  console.log('Usage: node fable-mode/scripts/model-selector.js --requested <haiku|sonnet|sonnect|opus> --available <models> --available-agents <agent names> --stage-brief <text> --pass-condition <text> --verification-command <command> --verifier-result <pending|pass|fail|not-run|blocked> [--fallback <inline|stop>] [--host-model <model>] [--audit-file <path>]');
+}
+
+function appendAuditRecord(record, auditFile, context) {
+  const target = auditFile || process.env.FABLE_AUDIT_FILE ||
+    path.join(getWorkspaceStateDir(getWorkspaceRoot(context)), 'state', 'fable-mode', 'audit.jsonl');
+  fs.mkdirSync(path.dirname(path.resolve(target)), { recursive: true });
+  fs.appendFileSync(target, `${JSON.stringify(record)}\n`, 'utf8');
+}
+
+function main(argv = process.argv.slice(2)) {
+  try {
+    const input = parseArgs(argv);
+    if (input.help) {
+      printHelp();
+      return 0;
+    }
+    const record = resolveMode(input);
+    appendAuditRecord(record, input.auditFile, input);
+    console.log(JSON.stringify(record, null, 2));
+    return record.status === 'blocked' ? 2 : 0;
+  } catch (error) {
+    console.error(`[fable-mode/model-selector] ${error.message}`);
+    return 2;
+  }
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = { loadMatrix, normalizeModel, parseArgs, resolveMode, main };

package/fable-mode/scripts/workflow-plan-consumer.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const STAGE_CONTRACT_VERSION = 2;
+const FABLE_STRATEGIES = new Set([
+  'fable-staged',
+  'fable-parallel',
+  'fable-multi-agent-workspace',
+]);
+
+function canonicalPath(value) {
+  const resolved = path.resolve(value || process.cwd());
+  try { return fs.realpathSync(resolved); } catch (_) { return resolved; }
+}
+
+function getStateHome() {
+  return process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything');
+}
+
+// Keep this algorithm identical to scripts/lib/workspace.js. This skill ships
+// standalone, so it cannot depend on the source repository being present.
+function getWorkspaceKey(root) {
+  const real = canonicalPath(root);
+  const slug = path.basename(real).toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'workspace';
+  const hashInput = process.platform === 'win32' ? real.toLowerCase() : real;
+  const hash = crypto.createHash('sha1').update(hashInput).digest('hex').slice(0, 12);
+  return `${slug}-${hash}`;
+}
+
+function getWorkspaceStateRoot(root) {
+  return path.join(getStateHome(), 'workspaces', getWorkspaceKey(root), 'state');
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.keys(value).sort().reduce((acc, key) => {
+    acc[key] = stableValue(value[key]);
+    return acc;
+  }, {});
+}
+
+function derivePlanId(routerContract) {
+  const canonical = JSON.stringify(stableValue(routerContract));
+  return `plan-${crypto.createHash('sha256').update(canonical).digest('hex').slice(0, 16)}`;
+}
+
+function sanitizeId(value, label) {
+  const text = String(value || '').trim();
+  if (!text) throw new Error(`${label} is required`);
+  if (!/^[A-Za-z0-9._-]+$/.test(text)) throw new Error(`${label} contains unsupported characters: ${text}`);
+  return text.slice(0, 128);
+}
+
+function normalizeWritePath(value) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('writeSet entries must be non-empty strings');
+  let normalized = value.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  normalized = normalized.replace(/\/+$/g, '');
+  if (!normalized || normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized)) {
+    throw new Error(`writeSet paths must be repository-relative: ${value}`);
+  }
+  const parts = normalized.split('/');
+  if (parts.some(part => !part || part === '.' || part === '..')) {
+    throw new Error(`writeSet path escapes or ambiguously names repository scope: ${value}`);
+  }
+  if (/[*?\[\]]/.test(normalized)) {
+    throw new Error(`writeSet uses unsupported glob syntax; declare concrete path scopes: ${value}`);
+  }
+  return normalized;
+}
+
+function normalizeStage(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('stage must be an object');
+  const stageId = sanitizeId(raw.stageId, 'stageId');
+  if (typeof raw.goal !== 'string' || !raw.goal.trim()) throw new Error(`${stageId}: goal is required`);
+  if (typeof raw.agent !== 'string' || !raw.agent.trim()) throw new Error(`${stageId}: agent is required`);
+  if (typeof raw.task !== 'string' || !raw.task.trim()) throw new Error(`${stageId}: task is required`);
+  if (!Array.isArray(raw.dependsOn)) throw new Error(`${stageId}: dependsOn must be an array (use [] for a root stage)`);
+  if (!Array.isArray(raw.writeSet)) throw new Error(`${stageId}: writeSet must be an array (use [] for read-only)`);
+
+  const dependsOn = [...new Set(raw.dependsOn.map(value => sanitizeId(value, `${stageId}.dependsOn`)))];
+  const writeSet = [...new Set(raw.writeSet.map(normalizeWritePath))].sort();
+
+  return {
+    stageId,
+    goal: raw.goal.trim(),
+    agent: raw.agent.trim(),
+    task: raw.task.trim(),
+    inputs: Array.isArray(raw.inputs) ? raw.inputs : [],
+    expectedOutputs: Array.isArray(raw.expectedOutputs) ? raw.expectedOutputs : [],
+    outputPath: raw.outputPath === undefined ? null : raw.outputPath,
+    dependsOn,
+    writeSet,
+    checkCommand: typeof raw.checkCommand === 'string' && raw.checkCommand.trim() ? raw.checkCommand.trim() : null,
+    passCondition: typeof raw.passCondition === 'string' && raw.passCondition.trim() ? raw.passCondition.trim() : null,
+    failureReturn: typeof raw.failureReturn === 'string' && raw.failureReturn.trim()
+      ? raw.failureReturn.trim()
+      : 'failure summary + evidence + missing prerequisite',
+  };
+}
+
+function validateStageGraph(stages) {
+  const normalized = stages.map(normalizeStage);
+  const byId = new Map();
+  for (const stage of normalized) {
+    if (byId.has(stage.stageId)) throw new Error(`duplicate stageId: ${stage.stageId}`);
+    byId.set(stage.stageId, stage);
+  }
+
+  for (const stage of normalized) {
+    for (const dependency of stage.dependsOn) {
+      if (dependency === stage.stageId) throw new Error(`${stage.stageId}: stage cannot depend on itself`);
+      if (!byId.has(dependency)) throw new Error(`${stage.stageId}: unresolved dependency ${dependency}`);
+    }
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(stageId) {
+    if (visiting.has(stageId)) throw new Error(`cyclic stage dependency detected at ${stageId}`);
+    if (visited.has(stageId)) return;
+    visiting.add(stageId);
+    for (const dependency of byId.get(stageId).dependsOn) visit(dependency);
+    visiting.delete(stageId);
+    visited.add(stageId);
+  }
+  for (const stage of normalized) visit(stage.stageId);
+  return normalized;
+}
+
+function pathScopesOverlap(left, right) {
+  const a = normalizeWritePath(left);
+  const b = normalizeWritePath(right);
+  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+
+function validateParallelBatch(stages) {
+  for (let i = 0; i < stages.length; i++) {
+    for (let j = i + 1; j < stages.length; j++) {
+      for (const left of stages[i].writeSet) {
+        for (const right of stages[j].writeSet) {
+          if (pathScopesOverlap(left, right)) {
+            throw new Error(`parallel write-set overlap: ${stages[i].stageId}:${left} conflicts with ${stages[j].stageId}:${right}`);
+          }
+        }
+      }
+    }
+  }
+}
+
+function dependencyBatches(stages, validateWrites) {
+  const byId = new Map(stages.map(stage => [stage.stageId, stage]));
+  const remaining = new Set(byId.keys());
+  const completed = new Set();
+  const batches = [];
+
+  while (remaining.size > 0) {
+    const ready = [...remaining]
+      .filter(stageId => byId.get(stageId).dependsOn.every(dep => completed.has(dep)))
+      .sort();
+    if (ready.length === 0) throw new Error('unresolved or cyclic dependency graph');
+    const batch = ready.map(stageId => byId.get(stageId));
+    if (validateWrites) validateParallelBatch(batch);
+    batches.push(batch.map(stage => stage.stageId));
+    for (const stageId of ready) {
+      remaining.delete(stageId);
+      completed.add(stageId);
+    }
+  }
+  return batches;
+}
+
+function topologicalBatches(stages) {
+  return dependencyBatches(stages, true);
+}
+
+function sequentialBatches(stages) {
+  return dependencyBatches(stages, false).flat().map(stageId => [stageId]);
+}
+
+function validateRouterPlan(routerContract) {
+  if (!routerContract || typeof routerContract !== 'object' || Array.isArray(routerContract)) {
+    throw new Error('router contract must be an object');
+  }
+  const plan = routerContract.workflowPlan;
+  if (!plan || typeof plan !== 'object') throw new Error('router contract is missing workflowPlan');
+  if (plan.strategySelection !== 'selected') throw new Error(`workflow strategy is not selected: ${plan.strategySelection}`);
+  if (!FABLE_STRATEGIES.has(plan.strategy)) throw new Error(`workflow strategy is not a Fable consumer topology: ${plan.strategy}`);
+  if (plan.fallback && plan.fallback.disposition === 'blocked') {
+    throw new Error(`workflow plan is blocked: ${(plan.fallback.reasonCodes || []).join(', ') || 'unspecified reason'}`);
+  }
+  if (plan.strategy === 'fable-parallel' && (!plan.parallelism || plan.parallelism.allowed !== true)) {
+    throw new Error('fable-parallel requires workflowPlan.parallelism.allowed=true');
+  }
+  return plan;
+}
+
+function atomicWriteJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  fs.renameSync(tempPath, filePath);
+}
+
+function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId = null }) {
+  const plan = validateRouterPlan(routerContract);
+  const normalizedStages = validateStageGraph(stages || []);
+  if (normalizedStages.length === 0) throw new Error('at least one stage contract is required');
+
+  const planId = derivePlanId(routerContract);
+  const resolvedRunId = sanitizeId(runId || `run-${crypto.randomUUID()}`, 'runId');
+  const root = canonicalPath(workspaceRoot || process.cwd());
+  const stateRoot = getWorkspaceStateRoot(root);
+  const runRoot = path.join(stateRoot, 'fable-runs', resolvedRunId);
+  if (fs.existsSync(runRoot)) throw new Error(`runId already exists in this workspace: ${resolvedRunId}`);
+
+  const batches = plan.strategy === 'fable-parallel'
+    ? topologicalBatches(normalizedStages)
+    : sequentialBatches(normalizedStages);
+
+  const createdAt = new Date().toISOString();
+  const contractsDir = path.join(runRoot, 'contracts');
+  const evidenceDir = path.join(runRoot, 'evidence');
+  fs.mkdirSync(contractsDir, { recursive: true });
+  fs.mkdirSync(evidenceDir, { recursive: true });
+
+  for (const stage of normalizedStages) {
+    atomicWriteJson(path.join(contractsDir, `${stage.stageId}.json`), {
+      schemaVersion: STAGE_CONTRACT_VERSION,
+      planId,
+      runId: resolvedRunId,
+      sessionId: sessionId || null,
+      workspaceRoot: root,
+      ...stage,
+      workerId: null,
+      status: 'planned',
+      verificationEvidence: null,
+      createdAt,
+      updatedAt: createdAt,
+    });
+  }
+
+  const runManifest = {
+    schemaVersion: 1,
+    planId,
+    runId: resolvedRunId,
+    sessionId: sessionId || null,
+    workspaceRoot: root,
+    workspaceKey: getWorkspaceKey(root),
+    strategy: plan.strategy,
+    router: {
+      routingStatus: plan.routingStatus,
+      tier: plan.tier,
+      reasonCodes: plan.reasonCodes || [],
+    },
+    execution: {
+      batches,
+      parallelism: plan.parallelism,
+      verification: plan.verification,
+      workspace: plan.workspace,
+      memory: plan.memory,
+      modelSelection: plan.modelSelection,
+      limits: plan.limits,
+    },
+    stageIds: normalizedStages.map(stage => stage.stageId),
+    createdAt,
+  };
+  atomicWriteJson(path.join(runRoot, 'run.json'), runManifest);
+  return { ...runManifest, runRoot };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--plan-file') args.planFile = argv[++i];
+    else if (token === '--stages-file') args.stagesFile = argv[++i];
+    else if (token === '--root') args.root = argv[++i];
+    else if (token === '--run-id') args.runId = argv[++i];
+    else if (token === '--session-id') args.sessionId = argv[++i];
+    else if (token === '--help' || token === '-h') args.help = true;
+    else throw new Error(`unknown argument: ${token}`);
+  }
+  return args;
+}
+
+function usage() {
+  return 'Usage: node fable-mode/scripts/workflow-plan-consumer.js --plan-file <router-contract.json> --stages-file <stages.json> [--root <workspace>] [--run-id <id>] [--session-id <id>]';
+}
+
+if (require.main === module) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (!args.planFile || !args.stagesFile) throw new Error(usage());
+    const routerContract = JSON.parse(fs.readFileSync(path.resolve(args.planFile), 'utf8'));
+    const stagesPayload = JSON.parse(fs.readFileSync(path.resolve(args.stagesFile), 'utf8'));
+    const stages = Array.isArray(stagesPayload) ? stagesPayload : stagesPayload.stages;
+    const manifest = prepareRun({
+      routerContract,
+      stages,
+      workspaceRoot: args.root || process.cwd(),
+      runId: args.runId,
+      sessionId: args.sessionId || null,
+    });
+    process.stdout.write(`${JSON.stringify(manifest)}\n`);
+  } catch (err) {
+    console.error(`[FABLE PLAN CONSUMER] ${err.message}`);
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  STAGE_CONTRACT_VERSION,
+  derivePlanId,
+  getWorkspaceKey,
+  getWorkspaceStateRoot,
+  normalizeStage,
+  normalizeWritePath,
+  pathScopesOverlap,
+  prepareRun,
+  sequentialBatches,
+  topologicalBatches,
+  validateParallelBatch,
+  validateRouterPlan,
+  validateStageGraph,
+};

package/find-skills/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: find-skills
+description: Search the agent-skills ecosystem (skills.sh / npx skills) when no installed skill fits; verify quality, apply ephemerally via temp cache by default, and install permanently via npx skills add only with explicit user approval 
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Find Skills
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Request to find an external skill. |
+| **Expected Output** | Skill pointer, applied skill, or fallback. |
+| **State Mutations** | Temp cache (default); native install opt-in. |
+| **Enforcement Gate** | Local first; explicit approval before applying third-party code; graceful npx failure. |
+
+## Workflow
+
+0. Check local coverage (router registry, `generated[]`) before live installs:
+```bash
+npx skills list --json          # project scope
+npx skills list -g --json       # global scope
+```
+1. Identify domain/task, check [skills.sh](https://skills.sh/), then search `npx skills find [query] [--owner <owner>]`.
+2. Verify: prefer 1K+ installs, official sources; read the unaudited SKILL.md.
+3. Present name/source/count; NEVER fetch/apply without explicit approval.
+4. Apply ephemerally (default, zero footprint):
+```bash
+node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>
+```
+Treat the printed output as binding for this request, like a loaded skill — not reference material. OS-temp cache (6h); nothing written to repo or manifest.json.
+5. Permanent install ONLY when the user says they will reuse it: `npx skills add <owner/repo[@skill]> --agent <agent> [-g] -y`
+6. Nothing exists? Help directly; suggest `npx skills init <name>` if recurring.
+
+Deep dive: <this-skill-dir>/references/discovery-flow.md
+
+## USE FOR:
+- finding an external skill when none installed fits
+- vetting third-party skills before applying them
+- ephemeral skill use without permanent installs
+
+## DO NOT USE FOR:
+- authoring skills (`skill-creator`)
+- installing anything without explicit user approval