@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/src/runtime/lock.ts

@@ -0,0 +1,40 @@
+import { mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+
+export class StateLock {
+  private constructor(private path: string, private token: string) {}
+  static async acquire(directory: string): Promise<StateLock> {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, 'writer.lock');
+    const token = randomUUID();
+    const file = await open(path, 'wx', 0o600).catch(error => {
+      if (error.code === 'EEXIST') throw new Error(`State directory locked: ${path}; inspect owner before explicit recovery`);
+      throw error;
+    });
+    try { await file.writeFile(JSON.stringify({ token, pid: process.pid, hostname: hostname(), createdAt: new Date().toISOString() })); await file.sync(); }
+    finally { await file.close(); }
+    return new StateLock(path, token);
+  }
+  /** Explicit repair only: exact token, same host and a demonstrably dead PID. */
+  static async recover(directory: string, expectedToken: string): Promise<void> {
+    const guardPath = join(directory, 'writer.recovery.lock');
+    const guard = await open(guardPath, 'wx', 0o600);
+    try {
+      const path = join(directory, 'writer.lock');
+      const original = await readFile(path, 'utf8');
+      const owner = JSON.parse(original);
+      if (!expectedToken || owner.token !== expectedToken || owner.hostname !== hostname() || !Number.isSafeInteger(owner.pid) || owner.pid < 1) throw new Error('Lock recovery identity mismatch');
+      try { process.kill(owner.pid, 0); throw new Error('Lock owner is alive'); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error; }
+      if (await readFile(path, 'utf8') !== original) throw new Error('Lock ownership changed');
+      await unlink(path);
+    } finally { await guard.close(); await unlink(guardPath); }
+  }
+  async release(): Promise<void> {
+    const owner = JSON.parse(await readFile(this.path, 'utf8'));
+    if (owner.token !== this.token) throw new Error('Lock ownership changed');
+    await unlink(this.path);
+  }
+}

package/src/runtime/process.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+
+export interface ProcessResult { code: number | null; signal: NodeJS.Signals | null; stdout: string; stderr: string }
+export interface ProcessOptions { cwd?: string; timeoutMs?: number; maxOutputBytes?: number; signal?: AbortSignal; env?: NodeJS.ProcessEnv; input?: string | Uint8Array }
+/** Owns only its direct child; no detached services or shell expansion. */
+export function runProcess(command: string, args: readonly string[], options: ProcessOptions = {}): Promise<ProcessResult> {
+  const timeout = options.timeoutMs ?? 30_000;
+  const limit = options.maxOutputBytes ?? 1024 * 1024;
+  if (typeof command !== 'string' || !command.trim() || !Array.isArray(args) || args.some(arg => typeof arg !== 'string')) return Promise.reject(new Error('Invalid process command'));
+  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2_147_483_647 || !Number.isSafeInteger(limit) || limit < 1) return Promise.reject(new Error('Invalid process limits'));
+  if (options.signal?.aborted) return Promise.reject(new Error('Process aborted'));
+  return new Promise((resolve, reject) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command, [...args], { cwd: options.cwd, env: options.env, shell: false, stdio: [options.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    const stdout: Buffer[] = [], stderr: Buffer[] = [];
+    let bytes = 0, failure: Error | undefined, escalation: ReturnType<typeof setTimeout> | undefined;
+    const stop = (reason: Error) => {
+      if (failure) return;
+      failure = reason;
+      child.kill('SIGTERM');
+      // Keep the streams alive until close so callers get a deterministic
+      // completion point even when a child exits while it is being stopped.
+      escalation = setTimeout(() => child.kill('SIGKILL'), 250);
+    };
+    const collect = (chunks: Buffer[]) => (chunk: Buffer) => {
+      bytes += chunk.length;
+      if (bytes > limit) stop(new Error('Process output limit exceeded'));
+      else chunks.push(chunk);
+    };
+    child.stdout!.on('data', collect(stdout)); child.stderr!.on('data', collect(stderr));
+    const abort = () => stop(new Error('Process aborted'));
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => stop(new Error('Process timed out')), timeout);
+    child.once('error', error => { failure = error; });
+    if (child.stdin) { child.stdin.on('error', error => { if ((error as NodeJS.ErrnoException).code !== 'EPIPE') stop(error); }); child.stdin.end(options.input); }
+    child.once('close', (code, signal) => {
+      clearTimeout(timer); clearTimeout(escalation); options.signal?.removeEventListener('abort', abort);
+      if (failure) reject(failure);
+      else resolve({ code, signal, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') });
+    });
+  });
+}

package/src/runtime-identity.ts

@@ -0,0 +1,61 @@
+import { identityDigest, validatePackageIdentity, type PackageIdentity } from './release.ts';
+import type { ToolkitArtifactFile, ToolkitArtifactManifest } from './toolkit.ts';
+
+export interface RuntimeBuildInfo {
+  package_name: string;
+  version: string;
+  source_sha: string;
+  merge_sha: string | null;
+  compatibility_line: string;
+  skill_version: string;
+  build_id: string;
+  tarball_digest: string | null;
+  contracts: {
+    ledger: number;
+    api: number;
+    frontend: number;
+    viewer: number;
+    service: string;
+  };
+  policy: 'loomhelm-manual-v1';
+}
+
+function validatedIdentity(artifact: ToolkitArtifactManifest): PackageIdentity {
+  const identity = validatePackageIdentity(artifact.identity);
+  if (identity.packageName !== artifact.packageName || identity.packageVersion !== artifact.packageVersion || identity.compatibilityLine !== artifact.compatibilityLine || identity.skillVersion !== artifact.skillVersion || identity.sourceSha !== artifact.sourceSha || identity.mergeSha !== artifact.mergeSha || identity.dirty !== artifact.dirty || identity.buildId !== artifact.buildId || identity.tarballDigest !== artifact.tarballDigest || identity.gitTag !== artifact.gitTag) throw new Error('Toolkit artifact identity mismatch');
+  const { buildId, ...withoutBuildId } = identity;
+  const files = artifact.files as readonly ToolkitArtifactFile[];
+  if (identityDigest({ ...withoutBuildId, files }) !== buildId) throw new Error('Toolkit artifact build ID mismatch');
+  return identity;
+}
+
+export function buildInfoFromArtifact(artifact: ToolkitArtifactManifest): RuntimeBuildInfo {
+  const identity = validatedIdentity(artifact);
+  return Object.freeze({
+    package_name: identity.packageName,
+    version: identity.packageVersion,
+    source_sha: identity.sourceSha,
+    merge_sha: identity.mergeSha,
+    compatibility_line: identity.compatibilityLine,
+    skill_version: identity.skillVersion,
+    build_id: identity.buildId,
+    tarball_digest: identity.tarballDigest,
+    contracts: {
+      ledger: identity.contracts.ledgerContract,
+      api: identity.contracts.apiVersion,
+      frontend: identity.contracts.frontendContract,
+      viewer: identity.contracts.viewerContract,
+      service: identity.contracts.serviceVersion,
+    },
+    policy: 'loomhelm-manual-v1',
+  });
+}
+
+export function requirePublishableArtifact(artifact: ToolkitArtifactManifest): PackageIdentity {
+  const identity = validatedIdentity(artifact);
+  if (artifact.dirty) throw new Error('Publication requires a clean toolkit artifact');
+  if (identity.mergeSha === null || identity.mergeSha !== artifact.sourceSha) throw new Error('Publication requires artifact merge provenance');
+  if (identity.tarballDigest === null) throw new Error('Publication requires tarball provenance');
+  if (identity.gitTag !== `multi-task-flow-v${identity.packageVersion}`) throw new Error('Publication requires a matching Git tag provenance');
+  return identity;
+}

package/src/tasks/ledger.ts

@@ -0,0 +1,81 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { atomicWrite } from '../runtime/files.ts';
+import { StateLock } from '../runtime/lock.ts';
+import { applyOperation, emptyState, identifier, type Operation, type TaskState } from './model.ts';
+
+export interface Receipt { sequence: number; operationId: string; at: string; operation: Operation; previousHash: string; hash: string }
+const genesis = '0'.repeat(64);
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
+  if (value && typeof value === 'object') return '{' + Object.keys(value).sort().map(k => JSON.stringify(k) + ':' + canonical((value as Record<string, unknown>)[k])).join(',') + '}';
+  return JSON.stringify(value);
+}
+const digest = (value: unknown) => createHash('sha256').update(canonical(value)).digest('hex');
+
+/** A single local writer, immutable fact history, atomically replaced file. */
+export class Ledger {
+  private receipts: Receipt[] = [];
+  private state = emptyState();
+  private queue: Promise<unknown> = Promise.resolve();
+  private closed = false;
+  private constructor(private path: string, private lock: StateLock) {}
+  static async open(directory: string): Promise<Ledger> {
+    const lock = await StateLock.acquire(directory);
+    const ledger = new Ledger(join(directory, 'ledger.json'), lock);
+    try {
+      let text: string | undefined;
+      try { text = await readFile(ledger.path, 'utf8'); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      if (text !== undefined) {
+        const data = JSON.parse(text);
+        if (data.schemaVersion !== 1 || !Array.isArray(data.receipts)) throw new Error('Unsupported or invalid ledger');
+        const identities = new Set<string>();
+        for (const receipt of data.receipts as Receipt[]) {
+          identifier(receipt.operationId);
+          const { hash, ...body } = receipt;
+          if (receipt.sequence !== ledger.receipts.length + 1 || identities.has(receipt.operationId) || receipt.previousHash !== (ledger.receipts.at(-1)?.hash ?? genesis) || hash !== digest(body) || typeof receipt.at !== 'string' || !Number.isFinite(Date.parse(receipt.at))) throw new Error('Invalid receipt chain');
+          applyOperation(ledger.state, receipt.operation, receipt.at);
+          ledger.receipts.push(receipt); identities.add(receipt.operationId);
+        }
+      }
+      // An uncertain external side effect is never silently retried.
+      for (const run of Object.values(ledger.state.runs)) if (run.status === 'running') {
+        await ledger.execute(`recovery.${randomUUID()}`, { type: 'run.finish', runId: run.id, status: 'interrupted', detail: 'Client restarted; reconcile external effects before retry' });
+      }
+      return ledger;
+    } catch (error) { await lock.release(); throw error; }
+  }
+  snapshot(): TaskState { return structuredClone(this.state); }
+  history(): Receipt[] { return structuredClone(this.receipts); }
+  execute(operationId: string, operation: Operation): Promise<Receipt> {
+    if (this.closed) return Promise.reject(new Error('Ledger closed'));
+    // Capture caller input before asynchronous execution.
+    const input = JSON.parse(JSON.stringify(operation)) as Operation;
+    const action = this.queue.then(async () => {
+      identifier(operationId);
+      const prior = this.receipts.find(receipt => receipt.operationId === operationId);
+      if (prior) {
+        if (canonical(prior.operation) !== canonical(input)) throw new Error('Operation identity conflict');
+        return structuredClone(prior);
+      }
+      const at = new Date().toISOString();
+      const next = structuredClone(this.state);
+      applyOperation(next, input, at);
+      const body = { sequence: this.receipts.length + 1, operationId, at, operation: input, previousHash: this.receipts.at(-1)?.hash ?? genesis };
+      const receipt = { ...body, hash: digest(body) };
+      const receipts = [...this.receipts, receipt];
+      await atomicWrite(this.path, { schemaVersion: 1, receipts });
+      this.receipts = receipts; this.state = next;
+      return structuredClone(receipt);
+    });
+    this.queue = action.catch(() => {});
+    return action;
+  }
+  async close(): Promise<void> {
+    if (this.closed) { await this.queue; return; }
+    this.closed = true;
+    await this.queue;
+    await this.lock.release();
+  }
+}

package/src/tasks/model.ts

@@ -0,0 +1,58 @@
+export type TaskStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'blocked' | 'interrupted' | 'cancelled' | 'skipped';
+export interface TaskInput { id: string; goal: string; scope: string; acceptance: string; dependencies: string[]; repository?: string }
+export interface Task extends TaskInput { status: TaskStatus; runIds: string[] }
+export interface Run { id: string; taskId: string; attempt: number; status: TaskStatus; startedAt: string; endedAt?: string; detail?: string }
+export interface TaskState { tasks: Record<string, Task>; runs: Record<string, Run> }
+export type Operation =
+  | { type: 'task.create'; task: TaskInput }
+  | { type: 'run.start'; taskId: string; runId: string; command?: string[] }
+  | { type: 'run.finish'; runId: string; status: 'succeeded' | 'failed' | 'blocked' | 'interrupted'; detail: string }
+  | { type: 'task.stop'; taskId: string; status: 'cancelled' | 'skipped'; detail: string };
+export const emptyState = (): TaskState => ({ tasks: Object.create(null), runs: Object.create(null) });
+export function identifier(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value) || ['__proto__', 'constructor', 'prototype'].includes(value)) throw new Error('Invalid identity');
+}
+function content(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('Nonempty text required');
+}
+export function applyOperation(state: TaskState, operation: Operation, at: string): void {
+  if (!operation || typeof operation !== 'object') throw new Error('Invalid operation');
+  switch (operation.type) {
+    case 'task.create': {
+      const task = operation.task;
+      identifier(task.id); content(task.goal); content(task.scope); content(task.acceptance);
+      if (task.repository !== undefined) content(task.repository);
+      if (state.tasks[task.id]) throw new Error('Task already exists');
+      if (!Array.isArray(task.dependencies) || new Set(task.dependencies).size !== task.dependencies.length) throw new Error('Invalid dependencies');
+      for (const id of task.dependencies) { identifier(id); if (id === task.id || !state.tasks[id]) throw new Error('Dependency must already exist'); }
+      state.tasks[task.id] = { ...task, status: 'pending', runIds: [] };
+      return;
+    }
+    case 'run.start': {
+      identifier(operation.taskId); identifier(operation.runId);
+      if (operation.command !== undefined && (!Array.isArray(operation.command) || operation.command.length === 0 || operation.command.some(arg => typeof arg !== 'string') || !operation.command[0])) throw new Error('Invalid command');
+      const task = state.tasks[operation.taskId];
+      if (!task || !['pending', 'failed', 'blocked', 'interrupted'].includes(task.status)) throw new Error('Task cannot start');
+      if (state.runs[operation.runId]) throw new Error('Run already exists');
+      if (task.dependencies.some(id => state.tasks[id]?.status !== 'succeeded')) throw new Error('Dependencies not satisfied');
+      const run: Run = { id: operation.runId, taskId: task.id, attempt: task.runIds.length + 1, status: 'running', startedAt: at };
+      state.runs[run.id] = run; task.runIds.push(run.id); task.status = 'running'; return;
+    }
+    case 'run.finish': {
+      identifier(operation.runId); content(operation.detail);
+      if (!['succeeded', 'failed', 'blocked', 'interrupted'].includes(operation.status)) throw new Error('Invalid run outcome');
+      const run = state.runs[operation.runId];
+      if (!run || run.status !== 'running') throw new Error('Run is not active');
+      run.status = operation.status; run.endedAt = at; run.detail = operation.detail;
+      state.tasks[run.taskId]!.status = operation.status; return;
+    }
+    case 'task.stop': {
+      identifier(operation.taskId); content(operation.detail);
+      if (!['cancelled', 'skipped'].includes(operation.status)) throw new Error('Invalid stop status');
+      const task = state.tasks[operation.taskId];
+      if (!task || ['running', 'succeeded', 'cancelled', 'skipped'].includes(task.status)) throw new Error('Task cannot stop');
+      task.status = operation.status; return;
+    }
+    default: throw new Error('Unknown operation');
+  }
+}

package/src/toolkit.ts

@@ -0,0 +1,176 @@
+import { createHash } from 'node:crypto';
+import { access, lstat, readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { delimiter, isAbsolute, relative, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { runProcess, type ProcessOptions, type ProcessResult } from './runtime/process.ts';
+import { identityDigest, validatePackageIdentity, type PackageIdentity } from './release.ts';
+
+export interface SkillCapabilityReport { name: string; ready: boolean; readinessScope: 'all-declared-scenarios'; resourcesValid: boolean; dependencies: { skill: string; kind: 'skill' | 'command' | 'host'; strength: string; condition: string; available: boolean; code: string }[]; platform: string; arch: string; nativeSupported: boolean; source: string }
+export interface ToolkitResource { path: string; source?: string; sourceSha256?: string; installedSha256?: string }
+export interface ToolkitManifest { schemaVersion: 1; commit: string; skills: string[]; files: ToolkitResource[]; additions?: ToolkitResource[] }
+export interface ToolkitOmittedResource { path: string; reason: string }
+export interface ToolkitArtifactFile { path: string; sha256: string }
+export interface ToolkitDependency { name: string; version: string; path: string; entry: string }
+export interface ToolkitArtifactManifest {
+  schemaVersion: 2;
+  packageName: string;
+  packageVersion: string;
+  compatibilityLine: string;
+  skillVersion: string;
+  sourceCommit: string;
+  sourceSha: string;
+  mergeSha: string | null;
+  candidateSha: string;
+  dirty: boolean;
+  runtime: 'bun@1.4.4';
+  identity: PackageIdentity;
+  buildId: string;
+  tarballDigest: string | null;
+  gitTag: string | null;
+  dependenciesBundled: boolean;
+  dependencies: ToolkitDependency[];
+  omittedResources: ToolkitOmittedResource[];
+  files: ToolkitArtifactFile[];
+}
+
+function resourceFiles(manifest: ToolkitManifest): ToolkitResource[] {
+  return [...manifest.files, ...(manifest.additions ?? [])];
+}
+
+function isSafeResourcePath(path: string): boolean {
+  return !isAbsolute(path) && !path.split(/[\\/]/).some(part => !part || part === '.' || part === '..');
+}
+
+function isSafePackageName(name: string): boolean {
+  return /^@?[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)?$/.test(name);
+}
+
+/** The packaged resources are authoritative; never fall back to a host checkout. */
+export class SkillsRuntime {
+  constructor(readonly root = fileURLToPath(new URL('../toolkit/', import.meta.url))) {}
+  async manifest(): Promise<ToolkitManifest> {
+    const value = JSON.parse(await readFile(resolve(this.root, 'skills/source-manifest.json'), 'utf8')) as ToolkitManifest;
+    if (value.schemaVersion !== 1 || typeof value.commit !== 'string' || !Array.isArray(value.skills) || value.skills.length !== 29 || new Set(value.skills).size !== 29 || !Array.isArray(value.files)) throw new Error('Invalid toolkit resource manifest');
+    return value;
+  }
+  async artifact(): Promise<ToolkitArtifactManifest> {
+    const value = JSON.parse(await readFile(resolve(this.root, 'artifact-manifest.json'), 'utf8')) as ToolkitArtifactManifest & { identity?: unknown };
+    if (value.schemaVersion !== 2 || value.packageName !== '@loomhelm/multi-task-flow' || value.runtime !== 'bun@1.4.4' || typeof value.sourceCommit !== 'string' || !/^[a-f0-9]{40}$/.test(value.sourceCommit) || typeof value.sourceSha !== 'string' || !/^[a-f0-9]{40}$/.test(value.sourceSha) || typeof value.candidateSha !== 'string' || !/^[a-f0-9]{40}$/.test(value.candidateSha) || value.candidateSha !== value.sourceSha || typeof value.dirty !== 'boolean' || value.dependenciesBundled !== true || !Array.isArray(value.dependencies) || value.dependencies.length === 0 || value.dependencies.some(item => !item || !isSafePackageName(item.name) || typeof item.version !== 'string' || item.version.length === 0 || !isSafeResourcePath(item.path) || !isSafeResourcePath(item.entry)) || new Set(value.dependencies.map(item => item.name)).size !== value.dependencies.length || !Array.isArray(value.omittedResources) || value.omittedResources.some(item => !item || typeof item.path !== 'string' || !isSafeResourcePath(item.path) || typeof item.reason !== 'string' || item.reason.length === 0) || new Set(value.omittedResources.map(item => item.path)).size !== value.omittedResources.length || !Array.isArray(value.files) || value.files.some(file => !file || typeof file.path !== 'string' || !isSafeResourcePath(file.path) || !/^[a-f0-9]{64}$/.test(file.sha256)) || new Set(value.files.map(file => file.path)).size !== value.files.length || !value.identity) throw new Error('Invalid toolkit artifact manifest');
+    const identity = validatePackageIdentity(value.identity);
+    if (identity.packageName !== value.packageName || identity.packageVersion !== value.packageVersion || identity.compatibilityLine !== value.compatibilityLine || identity.skillVersion !== value.skillVersion || identity.sourceSha !== value.sourceSha || identity.mergeSha !== value.mergeSha || identity.dirty !== value.dirty || identity.buildId !== value.buildId || identity.tarballDigest !== value.tarballDigest || identity.gitTag !== value.gitTag) throw new Error('Toolkit artifact identity mismatch');
+    const { buildId, ...withoutBuildId } = identity;
+    if (identityDigest({ ...withoutBuildId, files: value.files }) !== buildId) throw new Error('Toolkit artifact build ID mismatch');
+    for (const dependency of value.dependencies) {
+      try {
+        const dependencyRoot = resolve(this.root, dependency.path);
+        const dependencyManifest = resolve(dependencyRoot, 'package.json');
+        if (await realpath(dependencyRoot) !== dependencyRoot || !(await stat(dependencyRoot)).isDirectory() || await realpath(dependencyManifest) !== dependencyManifest || !(await stat(dependencyManifest)).isFile()) throw new Error('Unsafe toolkit dependency: ' + dependency.name);
+        const metadata = JSON.parse(await readFile(dependencyManifest, 'utf8')) as { name?: string; version?: string };
+        if (metadata.name !== dependency.name || metadata.version !== dependency.version) throw new Error('Toolkit dependency identity mismatch: ' + dependency.name);
+        const entry = resolve(dependencyRoot, dependency.entry);
+        const entryRel = relative(dependencyRoot, entry);
+        if (isAbsolute(entryRel) || entryRel === '..' || entryRel.startsWith(`..${sep}`) || await realpath(entry) !== entry || !(await stat(entry)).isFile()) throw new Error('Unsafe toolkit dependency entry: ' + dependency.name);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw new Error('Missing toolkit dependency: ' + dependency.name);
+        throw error;
+      }
+    }
+    const packageManifest = resolve(this.root, '..', 'package.json');
+    try {
+      const packageMetadata = JSON.parse(await readFile(packageManifest, 'utf8')) as { dependencies?: Record<string, unknown> };
+      for (const dependency of value.dependencies) if (packageMetadata.dependencies?.[dependency.name] !== dependency.version) throw new Error('Toolkit package dependency declaration mismatch: ' + dependency.name);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    return value;
+  }
+  private async validateArtifact(): Promise<ToolkitArtifactManifest> {
+    const rootStat = await lstat(this.root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('Unsafe toolkit root');
+    const root = await realpath(this.root);
+    if (root !== resolve(this.root)) throw new Error('Unsafe toolkit root');
+    const artifact = await this.artifact();
+    const seen = new Set<string>();
+    for (const file of artifact.files) {
+      if (!file || typeof file.path !== 'string' || !isSafeResourcePath(file.path) || seen.has(file.path) || !/^[a-f0-9]{64}$/.test(file.sha256)) throw new Error('Invalid resource inventory path');
+      seen.add(file.path);
+      const target = resolve(root, file.path);
+      const rel = relative(root, target);
+      if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`) || await realpath(target) !== target || !(await stat(target)).isFile()) throw new Error('Unsafe toolkit resource: ' + file.path);
+      if (createHash('sha256').update(await readFile(target)).digest('hex') !== file.sha256) throw new Error('Toolkit resource checksum mismatch: ' + file.path);
+    }
+    const omitted = new Set(artifact.omittedResources.map(item => item.path));
+    const actual = new Set<string>();
+    const walk = async (relativePath: string): Promise<void> => {
+      const directory = resolve(root, relativePath);
+      for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const child = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+        const target = resolve(root, child);
+        if (entry.isSymbolicLink()) throw new Error('Unsafe toolkit resource: ' + child);
+        if (entry.isDirectory()) { await walk(child); continue; }
+        if (!entry.isFile() || await realpath(target) !== target) throw new Error('Unsafe toolkit resource: ' + child);
+        actual.add(child);
+      }
+    };
+    await walk('');
+    for (const path of actual) if (!seen.has(path) && !omitted.has(path)) throw new Error('Unlisted toolkit resource: ' + path);
+    return artifact;
+  }
+  async validate(): Promise<ToolkitArtifactManifest> { return this.validateArtifact(); }
+  async list(): Promise<{ name: string; path: string; scripts: string[] }[]> {
+    const manifest = await this.manifest();
+    await this.validateArtifact();
+    const resources = resourceFiles(manifest);
+    return manifest.skills.map(name => ({ name, path: resolve(this.root, 'skills', name, 'SKILL.md'), scripts: resources.filter(file => file.path.startsWith(`skills/${name}/scripts/`)).map(file => file.path) }));
+  }
+  async check(name: string, externalRoots = [resolve(homedir(), '.agents/skills'), resolve(process.env.CODEX_HOME ?? resolve(homedir(), '.codex'), 'skills')], advertisedHostCapabilities: readonly string[] = []): Promise<SkillCapabilityReport> {
+    const manifest = await this.manifest();
+    if (!manifest.skills.includes(name)) throw new Error('Unknown toolkit Skill');
+    type Requirement = { strength: string; condition: string };
+    const catalog = JSON.parse(await readFile(resolve(this.root, 'skills/catalog.json'), 'utf8')) as { entries: { name: string; externalSkills: (Requirement & { skill: string })[]; externalCommands: (Requirement & { command: string })[]; hostCapabilities: (Requirement & { capability: string })[] }[] };
+    const entry = catalog.entries.find(entry => entry.name === name)!;
+    const dependencies: SkillCapabilityReport['dependencies'] = await Promise.all(entry.externalSkills.map(async dependency => {
+      let available = false;
+      for (const root of externalRoots) {
+        try { if ((await stat(resolve(root, dependency.skill, 'SKILL.md'))).isFile()) { available = true; break; } }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      }
+      return { ...dependency, kind: 'skill' as const, available, code: available ? 'AVAILABLE' : 'HOST_SKILL_UNAVAILABLE' };
+    }));
+    for (const dependency of entry.externalCommands) {
+      let available = false;
+      for (const dir of (process.env.PATH ?? '').split(delimiter).filter(dir => isAbsolute(dir))) {
+        const path = resolve(dir, dependency.command);
+        try { if ((await stat(path)).isFile()) { await access(path, constants.X_OK); available = true; break; } }
+        catch (error) { if (!['ENOENT', 'ENOTDIR', 'EACCES'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error; }
+      }
+      dependencies.push({ skill: dependency.command, kind: 'command', strength: dependency.strength, condition: dependency.condition, available, code: available ? 'AVAILABLE' : 'HOST_COMMAND_UNAVAILABLE' });
+    }
+    for (const dependency of entry.hostCapabilities) {
+      // Only the invoking native host can advertise its actual tools. A socket
+      // pathname or a Skill file alone never proves native capability support.
+      const available = advertisedHostCapabilities.includes(dependency.capability);
+      dependencies.push({ skill: dependency.capability, kind: 'host', strength: dependency.strength, condition: dependency.condition, available, code: available ? 'HOST_ADVERTISED' : 'HOST_CAPABILITY_UNVERIFIED' });
+    }
+    await this.validateArtifact();
+    const nativeSupported = (process.platform === 'darwin' && process.arch === 'arm64') || (process.platform === 'linux' && process.arch === 'x64');
+    return { name, ready: nativeSupported && dependencies.every(dependency => dependency.available), readinessScope: 'all-declared-scenarios', resourcesValid: true, dependencies, platform: process.platform, arch: process.arch, nativeSupported, source: manifest.commit };
+  }
+  async run(script: string, args: readonly string[], options: ProcessOptions = {}): Promise<ProcessResult> {
+    const manifest = await this.manifest();
+    await this.validateArtifact();
+    if (!resourceFiles(manifest).some(file => file.path === script) || !/^(skills\/[^/]+\/scripts|skills\/bin)\/.+/.test(script)) throw new Error('Unknown toolkit script');
+    const root = await realpath(this.root);
+    const target = await realpath(resolve(root, script));
+    const rel = relative(root, target);
+    if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`) || !(await stat(target)).isFile()) throw new Error('Unsafe toolkit script');
+    const firstLine = (await readFile(target, 'utf8')).split('\n', 1)[0]!;
+    const executable = script.endsWith('.ts') ? process.execPath : script.endsWith('.sh') ? '/bin/bash' : script.endsWith('.py') ? 'python3' : /^#!.*\bruby\b/.test(firstLine) ? 'ruby' : /^#!.*\b(bash|sh)\b/.test(firstLine) ? '/bin/bash' : undefined;
+    if (!executable) throw new Error('Unsupported toolkit script interpreter');
+    const env = { ...process.env, ...(options.env ?? {}) };
+    if (options.env?.LOOMHELM_TOOLKIT_ROOT === undefined) env.LOOMHELM_TOOLKIT_ROOT = root;
+    return runProcess(executable, [...(script.endsWith('.ts') ? ['--no-install'] : executable === '/bin/bash' ? ['-p'] : []), target, ...args], { ...options, cwd: options.cwd ?? root, env });
+  }
+}

package/src/version.ts

@@ -0,0 +1,23 @@
+import { buildInfo } from './build-info.ts';
+export { buildInfo };
+export const versionHeader = 'X-Loomhelm-Version';
+export class ProductVersionError extends Error {
+  readonly code = 'PRODUCT_VERSION_INCOMPATIBLE';
+  constructor() { super('Update the client before reconnecting; local mode and state remain available.'); }
+}
+export async function checkServerVersion(baseUrl: string, fetcher: typeof fetch = fetch): Promise<void> {
+  if (buildInfo.version === 'dev') return;
+  const response = await fetcher(new URL('/version', baseUrl), { cache: 'no-store', redirect: 'error' });
+  const value: unknown = await response.json().catch(() => { throw new ProductVersionError(); });
+  if (!response.ok || !value || typeof value !== 'object' || !('version' in value) || !('policy' in value) || value.version !== buildInfo.version || value.policy !== buildInfo.policy) throw new ProductVersionError();
+}
+export async function versionedFetch(baseUrl: string, input: string | URL, init: RequestInit = {}, fetcher: typeof fetch = fetch): Promise<Response> {
+  const destination = new URL(input, baseUrl);
+  if (destination.origin !== new URL(baseUrl).origin) throw new Error('Cross-origin client request rejected');
+  await checkServerVersion(baseUrl, fetcher);
+  const headers = new Headers(init.headers);
+  headers.set(versionHeader, buildInfo.version);
+  const response = await fetcher(destination, { ...init, headers, redirect: 'error' });
+  if (response.status === 426) throw new ProductVersionError();
+  return response;
+}

package/src/workflow/README.md

@@ -0,0 +1,92 @@
+# 局部验证与通用 Skill 目录读取
+
+`workflow/index.ts` 仅提供通用 Skills 目录读取和局部验证 API；正式迁入入口由 `SkillsRuntime` 与根 `skills/` 提供。局部验证不代表完整工程交付、PR 就绪或发布完成。`workflow/cli.ts` 是独立机器可读入口，由 Bun 1.4.4 直接调用 TS；现有客户端公共入口不因本模块改变。实现以 `docs/design/client.md` 中的 Skills 和工作流职责为边界，参考已安装 `project-engineering-workflow` 的本地阶段语义。
+
+## Skills
+
+调用 `loadSkills({ project, user })`，参数直接指向 Skills 目录，例如仓库的 `.agents/skills` 和用户的 `~/.agents/skills`；调用方也可显式传入 `.codex/skills` 等现有目录。模块不推断宿主配置、不写全局技能、不执行 Skill 中的代码。每个目录的直接子目录对应一个 Skill，并支持符号链接安装。缺失根目录视为空目录；权限或其他目录读取错误向上传递。
+
+每个 Skill 必须有 `SKILL.md`，frontmatter 包含与目录一致的 `name` 和非空 `description`。名称使用小写字母、数字和短横线；这两个字段支持普通单行、双引号 JSON 字符串或单引号 YAML 字符串，其他正文和字段保持原样。多行 YAML 标量等未支持的语法会给出诊断，不会猜测解释。
+
+同名项目 Skill 优先于用户 Skill。项目副本无效或不适用时仍占用该名称，不会静默回退到用户副本。其他正常 Skills 可以继续加载；调用方必须处理 `diagnostics`，或通过 `requireSkill` 确认需要的 Skill 可用。
+
+可在 Skill 旁添加可选的 `loomhelm.json`，供客户端检查兼容性；它是客户端独立的机器合同，不要求改写已安装 Skill。示例：
+
+```json
+{
+  "schemaVersion": 1,
+  "version": "1.2.3",
+  "scopes": ["project", "user"]
+}
+```
+
+清单只允许 `schemaVersion`、`version`、`scopes`；`scopes` 必须声明允许从哪个来源加载，不能用于授予文件或命令执行权限。没有清单或没有 `version` 时版本为 `null`，仍可按名称加载；一旦要求版本范围，未知版本会拒绝。未声明版本的全局 `project-engineering-workflow` 可只读加载，但不能被当作满足某个版本约束。版本不从目录名、frontmatter 或 Git 历史猜测。
+
+`requireSkill(catalog, name, { range, scopes })` 检查选中的 Skill。版本支持严格的三段非负整数，以及 `*`、精确版本、`^`、`~` 和空格连接的 `>=`、`<=`、`>`、`<`、`=` 比较式；不支持预发布版本、通配分段和 `||`。`^0.2.3` 的上界为 `0.3.0`，`^0.0.3` 仅接受 `0.0.3`。所有约束都会先完成语法检查。`digest` 是正文与清单原文组成的 SHA-256 指纹，仅作内容身份，不证明可信来源。
+
+```ts
+const catalog = await loadSkills({ project: projectSkills, user: userSkills });
+const skill = requireSkill(catalog, 'engineering', {
+  range: '>=1.0.0 <2.0.0',
+  scopes: ['project', 'user'],
+});
+```
+
+## 本地阶段
+
+`LocalValidation.open(repository, baseRef, flowType)` 完成执行上下文检查：必须有可解析的明确 base、非 `main`/`master` 的命名分支、干净工作区，以及从 base 派生的 HEAD。模块仅检查本地 Git，不 fetch、不变更 remote，也不修改已有改动。
+
+| 调用 | 完成的本地阶段 | 下一阶段 |
+| - | - | - |
+| `open` | 执行上下文 | `durable-contracts` |
+| `settleContracts` | 记录 Spec 和 ADR 的适用性结论及文件指纹 | `delivery-slices` |
+| `recordImplementation` | 记录调用方已完成的实现说明 | `validation` |
+| `validate` | 执行显式配置的验证命令并保存结果 | `locally-validated` 或 `validation` |
+| `readiness` | 重新读取 Git 和合同文件，检查结果是否仍适用 | 返回当前门禁 |
+
+`settleContracts` 必须分别包含 Spec 和 ADR 的结论：`link` 要求存在的仓库相对文件路径，`not-needed` 要求空路径列表，两者均要求理由。真实路径不能经符号链接逃出仓库。设计决策及批准由调用方负责；模块不创建或替代 Spec/ADR，也不把说明文字当作人工批准。合同变化后必须重新结算合同、记录实现并验证。
+
+每条验证包含唯一 `id`、可执行文件 `command` 和字符串数组 `args`，默认是必需验证。命令在仓库根目录通过现有 `runProcess` 执行，禁用隐式 shell 展开。验证默认超时 30 秒、输出上限 1 MiB，可显式调整至最多 1800 秒和 64 MiB。命令本身拥有当前用户权限，调用方须只提交已授权的命令；本模块不是命令沙箱。
+
+至少需要一条必需验证。所有必需验证通过、整套验证执行结束且候选未变化，才能进入 `locally-validated`。可选验证失败会保留失败事实，不阻塞必需验证；任何验证造成 Git 状态或合同变化都会阻止就绪。非零退出、超时、输出超限、启动失败与取消都不会被记作通过。取消之后未开始的条目不生成执行收据；完整套件缺失条目时不能就绪。
+
+收据包含随机执行身份、命令、仓库、base、HEAD、实际开始与结束时间、退出码、信号、状态、输出与输出摘要。现有进程适配器在超时、取消、输出超限等异常时只返回异常，因此这些收据不声称保留部分 stdout/stderr。状态快照使用深拷贝；单实例拒绝并行变更，每次验证调用都重新运行命令。调用方负责持久保存返回结果、跨实例锁与重启恢复，本模块不伪造持久化或幂等执行保证。
+
+`locally-validated` 只表示该模块覆盖的本地阶段已通过，不是远端发布授权、完整 Review Readiness、merge-ready 或 Flow Complete。调用方仍负责项目适用的 Spec 同步、视觉证据、经验验收、审查层级与正式 review/CI 等门禁。`flowType` 保留 `normal`、`fast-track`、`local-merge` 路由身份，但不从中继承 push、PR、merge 或 release 权限。候选 HEAD 变化、工作区变脏或合同指纹变化后，`readiness()` 返回未完成门禁，旧收据保留为历史事实。
+
+## 验证入口
+
+先在 `clients/typescript/` 下执行 `bun install --frozen-lockfile` 和 `bun --no-install run build`。命令输出 JSON，失败退出码为 1；参数或配置错误输出 JSON 到 stderr，实际验证失败的结果输出到 stdout。
+
+```sh
+bun --no-install src/workflow/cli.ts skills /path/to/repo/.agents/skills /path/to/user/.agents/skills
+bun --no-install src/workflow/cli.ts local-verify /path/to/workflow.json
+```
+
+`verify` 清单示例：
+
+```json
+{
+  "schemaVersion": 1,
+  "repository": "./repo",
+  "base": "HEAD",
+  "flowType": "normal",
+  "skills": {
+    "project": ".agents/skills",
+    "user": "/path/to/user/.agents/skills",
+    "requirements": [{ "name": "engineering", "range": "^1.0.0", "scopes": ["project", "user"] }]
+  },
+  "contracts": [
+    { "kind": "spec", "disposition": "link", "reason": "Existing acceptance contract", "paths": ["docs/specs/feature/SPEC.md"] },
+    { "kind": "adr", "disposition": "not-needed", "reason": "No architectural boundary change", "paths": [] }
+  ],
+  "implementation": "Implementation committed and ready for local validation",
+  "validations": [
+    { "id": "tests", "command": "bun", "args": ["test", "test/feature.test.ts"], "timeoutMs": 30000 }
+  ]
+}
+```
+
+`repository` 相对于清单所在目录解析，Skills 路径相对于仓库解析；`skills` 可省略。验证命令固定以仓库根目录为工作目录。建议将清单与输出放在仓库外或既有忽略的证据目录，避免验证自身产生未跟踪文件使候选变脏。输出的 `selectedSkills` 保留实际加载的内容、来源、版本与指纹；Skill 检查在执行命令前进行，不声称锁定全局 Skill 文件或检测验证期间的外部变更。
+
+行为验证使用 `bun --no-install run test`。`test/workflow.test.ts` 使用临时真实 Git 仓库和真实 Bun 子进程，覆盖 Skills 覆盖与兼容性、阶段顺序、命令结果、取消、合同逃逸、合同漂移、候选污染、HEAD 变化，以及无服务端的 CLI 验证链路。