@loomhelm/multi-task-flow 0.2.7 → 0.2.9

package/toolkit/skills/multi-task-flow/lib/view.ts

@@ -37,18 +37,125 @@ export type PlannedInterval = {
 
 const RELATIVE_EPOCH = Date.parse("2000-01-01T00:00:00.000Z");
 
-function deliveryGateDiagnostics(group: Ledger["groups"][number]): Record<string, string>[] {
-  const workspaceAtom = group.atoms.find((atom) => atom.lifecycle_stage === "workspace_ready");
+function deliveryUnitPr(group: Ledger["groups"][number]) {
+  if (group.pr && "state" in group.pr) return "pr" in group.pr ? group.pr.pr : null;
+  return group.parent_pr;
+}
+
+function latestParentPrFact(ledger: Ledger, groupId: string) {
+  return ledger.facts
+    .filter((fact) => fact.kind === "pr_published" && fact.subject_id === groupId)
+    .sort((left, right) => left.observed_at.localeCompare(right.observed_at))
+    .at(-1);
+}
+
+function sameExternalRef(left: { provider: string; repository: string; id: string }, right: { provider: string; repository: string; id: string }): boolean {
+  return left.provider === right.provider && left.repository === right.repository && left.id === right.id;
+}
+
+function parentPrReady(ledger: Ledger, group: Ledger["groups"][number]): boolean {
+  const pr = deliveryUnitPr(group);
+  const canonicalState = group.pr && "state" in group.pr ? group.pr.state : null;
   const prAtom = group.atoms.find((atom) => atom.lifecycle_stage === "pr_created");
+  const latest = latestParentPrFact(ledger, group.id);
+  return Boolean(
+    group.lifecycle.pr_created === "passed" &&
+      prAtom?.status === "completed" &&
+      pr &&
+      (canonicalState === null || canonicalState === "published") &&
+      latest?.status === "passed" &&
+      latest.receipt?.resource_type === "pr" &&
+      latest.receipt.resource_id === pr.id &&
+      latest.receipt.pr &&
+      sameExternalRef(latest.receipt.pr, pr) &&
+      latest.receipt.state === "open",
+  );
+}
+
+function parentPrDefinitivelyAbsent(ledger: Ledger, group: Ledger["groups"][number]): boolean {
+  const latest = latestParentPrFact(ledger, group.id);
+  const publicationPending = ledger.operations.some(
+    (operation) =>
+      operation.kind === "publish_pr" &&
+      operation.target_id === group.id &&
+      ["claimed", "unknown"].includes(operation.status),
+  );
+  return Boolean(
+    !publicationPending &&
+      latest &&
+      latest.status === "failed" &&
+      latest.receipt?.resource_type === "pr" &&
+      latest.receipt.state === "absent" &&
+      !deliveryUnitPr(group),
+  );
+}
+
+function allowsBootstrapMainOwnedStart(
+  ledger: Ledger,
+  group: Ledger["groups"][number],
+  task?: Ledger["tasks"][number],
+): boolean {
+  const workspaceAtom = group.atoms.find((atom) => atom.lifecycle_stage === "workspace_ready");
+  return Boolean(
+    task &&
+      group.state === "active" &&
+      group.delivery_unit_kind === "bootstrap" &&
+      group.owner_kind === "main" &&
+      task.execution_owner === "main" &&
+      task.conversation_policy === "main_owned" &&
+      group.lifecycle.workspace_ready === "passed" &&
+      workspaceAtom?.status === "completed" &&
+      parentPrDefinitivelyAbsent(ledger, group),
+  );
+}
+
+function allowsBootstrapGroupStart(
+  ledger: Ledger,
+  group: Ledger["groups"][number],
+): boolean {
+  const workspaceAtom = group.atoms.find((atom) => atom.lifecycle_stage === "workspace_ready");
+  return Boolean(
+    group.state === "active" &&
+      group.delivery_unit_kind === "bootstrap" &&
+      group.owner_kind === "main" &&
+      group.lifecycle.workspace_ready === "passed" &&
+      workspaceAtom?.status === "completed" &&
+      parentPrDefinitivelyAbsent(ledger, group),
+  );
+}
+
+function deliveryGateDiagnostics(
+  ledger: Ledger,
+  group: Ledger["groups"][number],
+  task?: Ledger["tasks"][number],
+): Record<string, string>[] {
+  const workspaceAtom = group.atoms.find((atom) => atom.lifecycle_stage === "workspace_ready");
   const diagnostics: Record<string, string>[] = [];
+  if (group.state !== "active")
+    diagnostics.push({ code: "DELIVERY_UNIT_NOT_ACTIVE", message: "交付单元尚未进入 active 状态" });
   if (group.lifecycle.workspace_ready !== "passed" || workspaceAtom?.status !== "completed")
     diagnostics.push({ code: "DELIVERY_WORKSPACE_GATE_PENDING", message: "交付单元尚未完成 workspace_ready 原子任务" });
-  const deliveryPr = group.pr && "state" in group.pr ? ("pr" in group.pr ? group.pr.pr : null) : group.parent_pr;
-  if (group.lifecycle.pr_created !== "passed" || !deliveryPr || prAtom?.status !== "completed")
+  const bootstrapGroupException = !task && allowsBootstrapGroupStart(ledger, group);
+  if (!allowsBootstrapMainOwnedStart(ledger, group, task) && !bootstrapGroupException && !parentPrReady(ledger, group))
     diagnostics.push({ code: "DELIVERY_PARENT_PR_GATE_PENDING", message: "父 PR 尚未创建、核验并完成交付原子任务" });
   return diagnostics;
 }
 
+function taskPrProjection(
+  task: Ledger["tasks"][number],
+  owner: Ledger["groups"][number] | undefined,
+): { url: string | null } | null {
+  if (!task.pr || typeof task.pr !== "object" || !("state" in task.pr))
+    return task.pr && "url" in task.pr ? { url: task.pr.url ?? null } : null;
+  if (task.pr.state === "shared_delivery_unit") {
+    const deliveryPr = owner?.pr;
+    if (deliveryPr && typeof deliveryPr === "object" && "state" in deliveryPr && "pr" in deliveryPr)
+      return { url: deliveryPr.pr.url ?? null };
+    return owner?.parent_pr ? { url: owner.parent_pr.url ?? null } : null;
+  }
+  return "pr" in task.pr ? { url: task.pr.pr.url ?? null } : null;
+}
+
 function formalExecutionWarnings(ledger: Ledger): Record<string, unknown>[] {
   return ledger.groups.flatMap((group) => {
     if (group.state !== "active" || group.coordination_execution.state !== "running")
@@ -806,8 +913,9 @@ export function buildView(
       const derivedStatus = deriveBusinessStatus(canonicalAtomicNodes, { kind: "task", task_id: task.id }, milestoneEvaluations);
       return {
         ...task,
+        pr: taskPrProjection(task, owner),
         ...(() => {
-          const gateDiagnostics = owner && isContributionKind(task.kind) ? deliveryGateDiagnostics(owner) : [];
+          const gateDiagnostics = owner && isContributionKind(task.kind) ? deliveryGateDiagnostics(ledger, owner, task) : [];
           return { gateDiagnostics };
         })(),
         dispatch_diagnostics: [
@@ -815,14 +923,14 @@ export function buildView(
           ...(owner && owner.delivery_unit_kind === "regular" && !owner.agent_thread_id
             ? [{ code: "DELIVERY_AGENT_NOT_BOUND", message: "regular delivery unit 未绑定交付 Agent" }]
             : []),
-          ...((owner && isContributionKind(task.kind)) ? deliveryGateDiagnostics(owner) : []),
+          ...((owner && isContributionKind(task.kind)) ? deliveryGateDiagnostics(ledger, owner, task) : []),
         ],
         dispatch_readiness:
           task.execution_owner === null && task.conversation_policy === null && task.delivery_policy === null
             ? "unknown"
             : taskExecutionPolicyIssues(task).length > 0
               ? "blocked"
-              : owner && isContributionKind(task.kind) && deliveryGateDiagnostics(owner).length > 0
+              : owner && isContributionKind(task.kind) && deliveryGateDiagnostics(ledger, owner, task).length > 0
                 ? "blocked"
               : owner && (owner.delivery_unit_kind === "bootstrap" || !!owner.agent_thread_id)
               ? "ready"
@@ -852,6 +960,10 @@ export function buildView(
   const allTasksDispatchReady = tasks.every(
     (task) => task.dispatch_readiness === "ready",
   );
+  const allDeliveryUnitsDispatchReady = ledger.groups.every((item) =>
+    deliveryGateDiagnostics(ledger, item).length === 0 &&
+    (item.delivery_unit_kind === "bootstrap" || !!item.agent_thread_id),
+  );
   const planSummary = ledger.plans.map((item) => ({
     id: item.id,
     created_at: item.created_at,
@@ -896,7 +1008,7 @@ export function buildView(
         activePlan.id !== executionPlan.id ||
         activePlan.lifecycle !== "approved",
       scheduling_eligible: schedulingStatus === "eligible",
-      dispatch_readiness: ledger.groups.every((item) => item.delivery_unit_kind === "bootstrap" || !!item.agent_thread_id) && allTasksDispatchReady ? "ready" : "blocked",
+      dispatch_readiness: allDeliveryUnitsDispatchReady && allTasksDispatchReady ? "ready" : "blocked",
       delivery_agent_readiness: ledger.groups.some((item) => item.delivery_unit_kind === "regular" && !item.agent_thread_id) ? "unbound" : "bound",
       proposal: {
         status: completenessIssues.length === 0 ? "complete" : "blocked",
@@ -927,14 +1039,16 @@ export function buildView(
       ...item,
       derived_status: deriveBusinessStatus(canonicalAtomicNodes, { kind: "delivery_unit", delivery_unit_id: item.id }, milestoneEvaluations),
       ...(() => {
-        const gateDiagnostics = item.delivery_unit_kind === "regular" ? deliveryGateDiagnostics(item) : [];
+        const gateDiagnostics = deliveryGateDiagnostics(ledger, item);
         return { gateDiagnostics };
       })(),
       delivery_agent_readiness: item.delivery_unit_kind === "bootstrap" ? "not_applicable" : item.agent_thread_id ? "bound" : "unbound",
-      dispatch_readiness: item.delivery_unit_kind === "bootstrap" || (!!item.agent_thread_id && deliveryGateDiagnostics(item).length === 0) ? "ready" : "blocked",
+      dispatch_readiness: item.delivery_unit_kind === "bootstrap"
+        ? deliveryGateDiagnostics(ledger, item).length === 0 ? "ready" : "blocked"
+        : !!item.agent_thread_id && deliveryGateDiagnostics(ledger, item).length === 0 ? "ready" : "blocked",
       dispatch_diagnostics: [
         ...(item.delivery_unit_kind === "regular" && !item.agent_thread_id ? [{ code: "DELIVERY_AGENT_NOT_BOUND", message: "regular delivery unit 未绑定交付 Agent" }] : []),
-        ...(item.delivery_unit_kind === "regular" ? deliveryGateDiagnostics(item) : []),
+        ...deliveryGateDiagnostics(ledger, item),
       ],
       ...profileProjection(ledger, "group", item),
       coordinator: coordinatorProjection(ledger, item),

package/toolkit/skills/multi-task-flow/references/shared-viewer.md

@@ -2,7 +2,7 @@
 
 The formal root is `~/.local/share/multi-task-flow/`: `config/`, `data/runs/`, `releases/`, `state/`, `logs/`. `CODEX_HOME` and the invoking worktree do not select a formal instance. `MULTI_TASK_FLOW_PROFILE=test|development` requires an absolute `MULTI_TASK_FLOW_ROOT`, distinct from the formal root. Isolated profiles derive separate launchd labels, port scopes and registry roots. `TASK_ORCHESTRATION_DATA_ROOT` is an explicit ledger-only fixture override; never use it to create a second formal authority.
 
-All commands use `service.ts <command> --input -`, consuming one JSON object. Normal usage:
+All commands use `multi-task-flow service <command> --input -`, consuming one JSON object. Normal usage:
 
 - `ensure`, `renew`, `release`: `{"run_id":"example","thread_id":"main-thread","api_version":1}`.
 - `status`, `doctor`: `{}`. Inspect configured identity and runtime before remediation.

package/toolkit/skills/multi-task-flow/scripts/check-client-skills.ts

@@ -8,8 +8,9 @@ const path = resolve(root, 'skills/source-manifest.json');
 const manifest = JSON.parse(readFileSync(path, 'utf8'));
 const hash = data => createHash('sha256').update(data).digest('hex');
 const refresh = process.argv.includes('--write');
-const additional = [...JSON.parse(readFileSync(resolve(root, 'skills/support-manifest.json'), 'utf8')), 'skills/bin/modules/core/runtime.ts', 'skills/bin/package.json', 'skills/multi-task-flow/tests/service-release.test.ts', 'skills/multi-task-flow/lib/notification-delivery.ts', 'skills/multi-task-flow/tests/notification-delivery.test.ts', 'skills/multi-task-flow/lib/conversation-archive.ts', 'skills/multi-task-flow/lib/task-runtime.ts', 'skills/multi-task-flow/web/task-state.ts', 'skills/multi-task-flow/web/conversation-control.ts', 'skills/multi-task-flow/tests/ui/conversation-control.test.ts', 'skills/multi-task-flow/tests/task-runtime.test.ts'];
-if (refresh) manifest.additions = additional.map(path => ({ path, installedSha256: hash(readFileSync(resolve(root, path))) }));
+const additional = [...JSON.parse(readFileSync(resolve(root, 'skills/support-manifest.json'), 'utf8')), 'skills/bin/modules/core/runtime.ts', 'skills/bin/package.json', 'skills/multi-task-flow/tests/service-release.test.ts', 'skills/multi-task-flow/lib/notification-delivery.ts', 'skills/multi-task-flow/tests/notification-delivery.test.ts', 'skills/multi-task-flow/lib/conversation-archive.ts', 'skills/multi-task-flow/lib/task-runtime.ts', 'skills/multi-task-flow/web/task-state.ts', 'skills/multi-task-flow/web/conversation-control.ts', 'skills/multi-task-flow/tests/ui/conversation-control.test.ts', 'skills/multi-task-flow/tests/task-runtime.test.ts', 'skills/multi-task-flow/lib/atomic-orchestration.ts', 'skills/multi-task-flow/tests/atomic-orchestration-schema.test.ts', 'skills/multi-task-flow/tests/task-kind.test.ts', 'skills/multi-task-flow/web/atomic-graph-view.tsx'];
+const sourcePath = file => file.sourcePath ?? file.path;
+if (refresh) manifest.additions = additional.map(path => { const source = path.startsWith('skills/multi-task-flow/') ? 'skills/multi-task-flow-runtime/' + path.slice('skills/multi-task-flow/'.length) : path; return { path, sourcePath: source, installedSha256: hash(readFileSync(resolve(root, source))) }; });
 const findings = [];
 const gitRoot = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd:root, encoding:'utf8' });
 if (gitRoot.status === 0 && gitRoot.stdout.trim() === root) {
@@ -18,6 +19,7 @@ if (gitRoot.status === 0 && gitRoot.stdout.trim() === root) {
   const covered = new Set([...manifest.files,...(manifest.additions ?? [])].map(file => file.path));
   for (const file of tracked.stdout.split('\0').filter(Boolean)) {
     if (/\.(?:js|mjs|cjs)$/.test(file)) findings.push('owned-source-must-be-typescript:'+file);
+    if (file.startsWith('skills/multi-task-flow-runtime/')) continue;
     if (file.startsWith('skills/') && !covered.has(file) && !['skills/source-manifest.json','skills/catalog.json'].includes(file)) findings.push('unlisted:'+file);
   }
 }
@@ -27,8 +29,9 @@ for (const excluded of manifest.exclusions ?? []) {
   if (manifest.files.some(file => file.source.startsWith(excluded.sourcePrefix)) || existsSync(resolve(root, installed))) findings.push(`excluded-resource:${installed}`);
 }
 for (const file of [...manifest.files, ...(manifest.additions ?? [])]) {
-  const target = resolve(root, file.path);
-  if (!file.path.startsWith('skills/') || !target.startsWith(root + '/') || !existsSync(target)) { findings.push(`missing:${file.path}`); continue; }
+  const source = resolve(root, sourcePath(file));
+  if (!file.path.startsWith('skills/') || !source.startsWith(root + '/') || !existsSync(source)) { findings.push(`missing:${file.path}`); continue; }
+  const target = source;
   const stat = lstatSync(target);
   if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) { findings.push(`unsafe:${file.path}`); continue; }
   const digest = hash(readFileSync(target));

package/toolkit/skills/multi-task-flow/scripts/check-skills-installation.ts

@@ -12,6 +12,11 @@ export function checkSkillsInstallation(root, { probe = false } = {}) {
   const inventory = resolve(root, 'skills/source-manifest.json');
   if (!existsSync(inventory)) return { ok: false, code: 'SKILLS_INVENTORY_MISSING', root, missing: ['skills/source-manifest.json'] };
   const manifest = JSON.parse(readFileSync(inventory, 'utf8'));
+  const localPath = resource => {
+    const target = resolve(root, resource.path);
+    if (existsSync(target)) return resource.path;
+    return resource.sourcePath ?? resource.path;
+  };
   const contained = path => {
     const file = resolve(root, path);
     if (!existsSync(file)) return false;
@@ -19,14 +24,15 @@ export function checkSkillsInstallation(root, { probe = false } = {}) {
     return stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 1 && realpathSync(file) === file && realpathSync(file).startsWith(realpathSync(resolve(root, 'skills')) + '/');
   };
   const missing = [...manifest.files, ...(manifest.additions ?? [])]
-    .map(file => file.path).filter(path => !path.startsWith('skills/') || path.split('/').includes('..') || !contained(path));
-  const modified = [...manifest.files, ...(manifest.additions ?? [])].filter(file => !missing.includes(file.path) && createHash("sha256").update(readFileSync(resolve(root,file.path))).digest("hex") !== file.installedSha256).map(file => file.path);
+    .map(file => localPath(file)).filter(path => !path.startsWith('skills/') || path.split('/').includes('..') || !contained(path));
+  const modified = [...manifest.files, ...(manifest.additions ?? [])].filter(file => { const path = localPath(file); return !missing.includes(path) && createHash("sha256").update(readFileSync(resolve(root,path))).digest("hex") !== file.installedSha256; }).map(file => file.path);
   const escapedImports = [];
   for (const file of [...manifest.files, ...(manifest.additions ?? [])]) {
-    if (!/\.(ts|mjs)$/.test(file.path) || !file.path.startsWith('skills/') || file.path.split('/').includes('..') || !contained(file.path)) continue;
-    const text = readFileSync(resolve(root, file.path), 'utf8');
+    const path = localPath(file);
+    if (!/\.(ts|mjs)$/.test(path) || !path.startsWith('skills/') || path.split('/').includes('..') || !contained(path)) continue;
+    const text = readFileSync(resolve(root, path), 'utf8');
     for (const match of text.matchAll(/(?:from\s*|import\s*\(?\s*)["'](\.[^"']+)["']/g)) {
-      const target = resolve(root, dirname(file.path), match[1]);
+      const target = resolve(root, dirname(path), match[1]);
       if (!target.startsWith(resolve(root, 'skills') + '/')) escapedImports.push({ file: file.path, import: match[1] });
     }
   }
@@ -46,7 +52,7 @@ export function checkSkillsInstallation(root, { probe = false } = {}) {
   const dependencies = { status:!sourceComplete ? 'not_checked' : dependencyMissing.length ? 'missing' : 'prepared', missing:dependencyMissing };
   const entrypoints = { status: dependencyMissing.length ? 'blocked' : 'not_checked', results: [] };
   if (probe && sourceComplete && runtime.available && dependencyMissing.length === 0) {
-    for (const [script, args] of [['skills/bin/plan-cli.sh',['--help']], ['skills/dot-codex-development/scripts/context.ts',['--help']], ['skills/multi-task-flow/scripts/orchestrate.ts',['view','--input','-']]]) {
+    for (const [script, args] of [['skills/bin/plan-cli.sh',['--help']], ['skills/dot-codex-development/scripts/context.ts',['--help']], ['skills/multi-task-flow-runtime/scripts/orchestrate.ts',['view','--input','-']]]) {
       const result = spawnSync(script.endsWith('.sh') ? '/bin/bash' : process.execPath, [...(script.endsWith('.sh') ? ['-p'] : ['--no-install']), resolve(root,script), ...args], { cwd:root, env: { ...process.env, BUN_RUNTIME_TRANSPILER_CACHE_PATH:'0' }, input:'{}', encoding:'utf8', timeout:30000 });
       const expected = script.endsWith('orchestrate.ts') ? 2 : 0;
       entrypoints.results.push({script, code:result.status, ok:!result.error && result.status === expected, error: result.error ? String(result.error) : result.status === expected ? undefined : result.stderr});
@@ -69,11 +75,11 @@ if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1]
   const probe = process.argv.includes('--probe');
   const args = process.argv.slice(2).filter(arg => arg !== '--probe');
   if (args.length !== 0 && (args.length !== 2 || args[0] !== '--root')) {
-    console.error('Usage: bun skills/multi-task-flow/scripts/check-skills-installation.ts [--root PATH] [--probe]');
+    console.error('Usage: bun skills/multi-task-flow-runtime/scripts/check-skills-installation.ts [--root PATH] [--probe]');
     process.exitCode = 2;
   } else {
     try {
-      const report = checkSkillsInstallation(args[1] ?? resolve(import.meta.dirname, '../..'), {probe});
+      const report = checkSkillsInstallation(args[1] ?? resolve(import.meta.dirname, '../../..'), {probe});
       console.log(JSON.stringify(report));
       process.exitCode = report.ok ? 0 : 1;
     } catch (error) {

package/toolkit/skills/multi-task-flow/scripts/import-client-skills.ts

@@ -7,7 +7,7 @@ import { dirname, resolve } from 'node:path';
 
 const source = process.argv[2];
 const commit = process.argv[3] ?? 'HEAD';
-if (!source) throw new Error('Usage: bun skills/multi-task-flow/scripts/import-client-skills.ts SOURCE_REPOSITORY [SOURCE_REF]');
+if (!source) throw new Error('Usage: bun skills/multi-task-flow-runtime/scripts/import-client-skills.ts SOURCE_REPOSITORY [SOURCE_REF]');
 const git = (...args) => execFileSync('git', ['-C', source, ...args], { maxBuffer: 32 * 1024 * 1024 });
 const tree = git('ls-tree', '-rz', commit, 'skills', 'bin', 'docs').toString().split('\0').filter(Boolean);
 const files = [];

package/toolkit/skills/multi-task-flow/scripts/package-client-skills.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env -S bun --no-install
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, relative, resolve, sep } from 'node:path';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
 const root = resolve(import.meta.dirname, '../../..');
 const target = resolve(root, 'clients/typescript/toolkit');
 const manifest = JSON.parse(readFileSync(resolve(root, 'skills/source-manifest.json'), 'utf8'));
@@ -42,36 +42,15 @@ const gitTag = process.env.LOOMHELM_GIT_TAG?.trim() || null;
 if (gitTag !== null && gitTag !== `multi-task-flow-v${buildVersion}`) throw new Error('LOOMHELM_GIT_TAG does not match package version');
 const tarballDigest = process.env.LOOMHELM_TARBALL_DIGEST?.trim() || null;
 if (tarballDigest !== null && !sha256.test(tarballDigest)) throw new Error('LOOMHELM_TARBALL_DIGEST must be a SHA-256 digest');
-type DependencyDeclaration = { name: string; version: string; resourceRoot: string };
-type PreparedDependency = { name: string; version: string; path: string; entry: string };
-const dependencyDeclarations = new Map<string, DependencyDeclaration>();
-function declareDependencies(metadata: { dependencies?: Record<string, string> }, resourceRoot: string): void {
-  for (const [name, version] of Object.entries(metadata.dependencies ?? {})) {
-    const existing = dependencyDeclarations.get(name);
-    if (existing) {
-      if (existing.version !== version) throw new Error(`Conflicting dependency declaration: ${name}`);
-      continue;
-    }
-    dependencyDeclarations.set(name, { name, version, resourceRoot });
-  }
-}
-const skillsPackageMetadata = JSON.parse(readFileSync(resolve(root, 'skills/package.json'), 'utf8')) as { dependencies?: Record<string, string> };
-const flowPackageMetadata = JSON.parse(readFileSync(resolve(root, 'skills/multi-task-flow/package.json'), 'utf8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
-declareDependencies(skillsPackageMetadata, 'skills/node_modules');
-// The viewer's React/ELK dependencies are build-time inputs for the static
-// assets. The portable CLI only needs the runtime Skill dependencies above;
-// shipping the entire frontend dependency tree makes the tarball hundreds of
-// megabytes and slows every `bunx` startup. Keep the package's normal npm
-// dependency declarations for consumers that need the frontend, while bundling
-// only the dependencies executed by Skill scripts.
-if (flowPackageMetadata.dependencies?.zod) {
-  dependencyDeclarations.set('zod', {
-    name: 'zod',
-    version: flowPackageMetadata.dependencies.zod,
-    resourceRoot: 'skills/multi-task-flow/node_modules',
-  });
-}
-const requiredDependencies = [...dependencyDeclarations.values()].sort((left, right) => left.name.localeCompare(right.name));
+type ConsumerDependency = { name: string; version: string; mode: 'consumer-install' };
+const runtimeDependencyNames = ['playwright', 'sharp', 'zod'] as const;
+const declaredDependencies = packageMetadata.dependencies as Record<string, string> | undefined;
+if (!declaredDependencies || JSON.stringify(Object.keys(declaredDependencies).sort()) !== JSON.stringify([...runtimeDependencyNames])) throw new Error('Package production dependencies must be exactly playwright, sharp, and zod');
+const requiredDependencies: ConsumerDependency[] = runtimeDependencyNames.map(name => {
+  const version = declaredDependencies[name];
+  if (typeof version !== 'string' || !version) throw new Error(`Missing runtime dependency declaration: ${name}`);
+  return { name, version, mode: 'consumer-install' };
+});
 // Only this exact disposable resource output is replaced. TS is never emitted.
 if (existsSync(target)) {
   if (lstatSync(target).isSymbolicLink() || realpathSync(target) !== target) throw new Error('Unsafe toolkit output directory');
@@ -81,8 +60,8 @@ const outputs = new Map<string, { path: string; sha256: string }>();
 function record(path: string, contents: Uint8Array): void {
   outputs.set(path, { path, sha256: createHash('sha256').update(contents).digest('hex') });
 }
-function copy(path: string, expected: string | undefined, dependency = false): void {
-  const source = resolve(root, path);
+function copy(path: string, expected: string | undefined, dependency = false, sourcePath = path): void {
+  const source = resolve(root, sourcePath);
   if (!path.startsWith('skills/') || !source.startsWith(resolve(root, 'skills') + '/')) throw new Error('Unsafe toolkit resource path');
   const stat = lstatSync(source);
   if (!stat.isFile() || stat.isSymbolicLink() || (!dependency && stat.nlink !== 1) || realpathSync(source) !== source) throw new Error('Unsafe toolkit resource: ' + path);
@@ -109,22 +88,15 @@ function writeGenerated(path: string, contents: Uint8Array): void {
   writeFileSync(output, contents);
   record(path, contents);
 }
-function dependencyMetadata(sourceRoot: string, name: string, expectedVersion: string): { name: string; version: string; entry: string } {
-  const dependencyBase = resolve(root, sourceRoot);
-  const packageRoot = resolve(dependencyBase, name);
-  if (!packageRoot.startsWith(`${dependencyBase}${sep}`)) throw new Error(`Unsafe prepared dependency path: ${name}`);
-  const packageJsonPath = resolve(packageRoot, 'package.json');
-  if (!existsSync(packageJsonPath)) throw new Error(`Prepared dependency missing: ${name}`);
-  const metadata = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { name?: string; version?: string; module?: string; main?: string };
-  if (metadata.name !== name || metadata.version !== expectedVersion) throw new Error(`Prepared dependency version mismatch: ${name}`);
-  const declaredEntry = metadata.module ?? metadata.main ?? 'index.js';
-  const candidates = [declaredEntry, `${declaredEntry}.js`, `${declaredEntry}.mjs`, `${declaredEntry}.cjs`, `${declaredEntry}/index.js`];
-  const entry = candidates.find(candidate => {
-    const sourceEntry = resolve(packageRoot, candidate);
-    return sourceEntry.startsWith(`${packageRoot}${sep}`) && existsSync(sourceEntry) && lstatSync(sourceEntry).isFile() && realpathSync(sourceEntry) === sourceEntry;
-  });
-  if (!entry) throw new Error(`Unsafe prepared dependency entry: ${name}`);
-  return { name, version: expectedVersion, entry: entry.replace(/^\.\//, '') };
+function validateInstalledDependencies(): void {
+  const packageRoot = resolve(root, 'clients/typescript');
+  for (const dependency of requiredDependencies) {
+    const dependencyRoot = resolve(packageRoot, 'node_modules', dependency.name);
+    const dependencyManifest = resolve(dependencyRoot, 'package.json');
+    if (!existsSync(dependencyManifest) || lstatSync(dependencyRoot).isSymbolicLink() || realpathSync(dependencyRoot) !== dependencyRoot) throw new Error(`Consumer dependency is not installed: ${dependency.name}`);
+    const metadata = JSON.parse(readFileSync(dependencyManifest, 'utf8')) as { name?: string; version?: string };
+    if (metadata.name !== dependency.name || metadata.version !== dependency.version) throw new Error(`Consumer dependency version mismatch: ${dependency.name}`);
+  }
 }
 function copyPackageManifest(): void {
   const files = manifest.files.filter(file => !packageOmissionPaths.has(file.path));
@@ -132,113 +104,11 @@ function copyPackageManifest(): void {
   const packageManifest = { ...manifest, files, additions, packageOmissions };
   writeGenerated('skills/source-manifest.json', Buffer.from(JSON.stringify(packageManifest, null, 2) + '\n'));
 }
-for (const file of [...manifest.files, ...(manifest.additions ?? [])]) if (!packageOmissionPaths.has(file.path)) copy(file.path, file.installedSha256);
+for (const file of [...manifest.files, ...(manifest.additions ?? [])]) if (!packageOmissionPaths.has(file.path)) copy(file.path, file.installedSha256, false, file.sourcePath ?? file.path);
 copyPackageManifest();
 copy('skills/catalog.json');
-for (const name of ['index.html','app.js','app.css']) copy(`skills/multi-task-flow/dist/${name}`);
-const copyDependencies = (path: string, dependencyNames?: string[]): boolean => {
-  const sourceRoot = resolve(root, path);
-  if (!existsSync(sourceRoot)) {
-    if (requireDependencies) throw new Error(`Prepared dependency directory missing: ${path}`);
-    return false;
-  }
-  const rootStat = lstatSync(sourceRoot);
-  if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || realpathSync(sourceRoot) !== sourceRoot) throw new Error('Unsafe dependency directory: ' + path);
-  const resolvedRoot = realpathSync(sourceRoot);
-  let preparedFiles = 0;
-  const copyBinLauncher = (child: string, source: string): void => {
-    const resolvedSource = realpathSync(source);
-    const relSource = relative(sourceRoot, resolvedSource);
-    if (relative(resolvedRoot, resolvedSource).startsWith(`..${sep}`) || relative(resolvedRoot, resolvedSource) === '..' || relSource.startsWith(`..${sep}`) || relSource === '..' || !lstatSync(resolvedSource).isFile()) throw new Error('Unsafe dependency launcher: ' + `${path}/${child}`);
-    const outputPath = resolve(target, path, child);
-    const targetPath = resolve(target, path, relSource);
-    const targetRel = relative(dirname(outputPath), targetPath).split(sep).join('/');
-    const launcher = `#!/usr/bin/env bun\nawait import(new URL(${JSON.stringify(targetRel)}, import.meta.url).href);\n`;
-    mkdirSync(dirname(outputPath), { recursive: true });
-    writeFileSync(outputPath, launcher, { mode: 0o755 });
-    record(`${path}/${child}`, Buffer.from(launcher));
-  };
-  const recordPreparedFile = (destination: string, source: string): void => {
-    const resolvedSource = realpathSync(source);
-    const relativeSource = relative(resolvedRoot, resolvedSource);
-    const stat = lstatSync(source);
-    if (relativeSource.startsWith(`..${sep}`) || relativeSource === '..' || !stat.isFile() || stat.isSymbolicLink() || resolvedSource !== source) throw new Error('Unsafe prepared dependency: ' + destination);
-    const output = resolve(target, destination);
-    mkdirSync(dirname(output), { recursive: true });
-    const contents = readFileSync(resolvedSource);
-    cpSync(resolvedSource, output);
-    record(destination, contents);
-    preparedFiles += 1;
-  };
-  const walk = (relativePath: string): void => {
-    for (const entry of readdirSync(resolve(sourceRoot, relativePath), { withFileTypes: true })) {
-      if (entry.name === '.cache') continue;
-      const child = relativePath ? `${relativePath}/${entry.name}` : entry.name;
-      const source = resolve(sourceRoot, child);
-      if (entry.isSymbolicLink()) {
-        if (relativePath !== '.bin' && !relativePath.startsWith(`.bin${sep}`)) throw new Error('Unsafe dependency symlink: ' + `${path}/${child}`);
-        if (productPartitionBuild) recordPreparedFile(`${path}/${child}`, realpathSync(source));
-        else copyBinLauncher(child, source);
-      } else if (entry.isDirectory()) walk(child);
-      else if (productPartitionBuild) recordPreparedFile(`${path}/${child}`, source);
-      else copy(`${path}/${child}`, undefined, true);
-    }
-  };
-  if (!dependencyNames) {
-    walk('');
-    return preparedFiles > 0;
-  }
-  const roots = new Map<string, string>();
-  const queue = dependencyNames.map(name => ({ name, relativePath: name }));
-  while (queue.length > 0) {
-    const current = queue.shift()!;
-    if (roots.has(current.relativePath)) continue;
-    const packageJson = resolve(sourceRoot, current.relativePath, 'package.json');
-    if (!existsSync(packageJson)) throw new Error(`Prepared dependency missing: ${current.name}`);
-    roots.set(current.relativePath, current.name);
-    const metadata = JSON.parse(readFileSync(packageJson, 'utf8')) as { dependencies?: Record<string, string>; optionalDependencies?: Record<string, string> };
-    for (const dependencyName of Object.keys(metadata.dependencies ?? {})) {
-      const nested = `${current.relativePath}/node_modules/${dependencyName}`;
-      const root = existsSync(resolve(sourceRoot, nested, 'package.json')) ? nested : dependencyName;
-      if (!roots.has(root)) queue.push({ name: dependencyName, relativePath: root });
-    }
-    for (const dependencyName of Object.keys(metadata.optionalDependencies ?? {})) {
-      const nested = `${current.relativePath}/node_modules/${dependencyName}`;
-      const root = existsSync(resolve(sourceRoot, nested, 'package.json')) ? nested : dependencyName;
-      if (existsSync(resolve(sourceRoot, root, 'package.json')) && !roots.has(root)) queue.push({ name: dependencyName, relativePath: root });
-    }
-  }
-  for (const relativePath of roots.keys()) walk(relativePath);
-  return preparedFiles > 0;
-};
-let preparedDependencies: PreparedDependency[];
-if (productPartitionBuild) {
-  for (const resourceRoot of new Set(requiredDependencies.map(dependency => dependency.resourceRoot))) {
-    copyDependencies(resourceRoot, requiredDependencies.filter(dependency => dependency.resourceRoot === resourceRoot).map(dependency => dependency.name));
-  }
-  preparedDependencies = requiredDependencies.map(dependency => {
-    const metadata = dependencyMetadata(dependency.resourceRoot, dependency.name, dependency.version);
-    const path = `${dependency.resourceRoot}/${dependency.name}`;
-    if (!outputs.has(`${path}/package.json`)) throw new Error(`Prepared dependency was not copied: ${dependency.name}`);
-    return { name: dependency.name, version: dependency.version, path, entry: metadata.entry };
-  });
-} else {
-  // The published package must be runnable from an isolated `bunx` install.
-  // Bun's workspace install may materialize dependency entries as shims that
-  // point outside the package; copying the prepared dependency trees keeps
-  // every runtime import inside the tarball and makes the artifact portable.
-  for (const resourceRoot of new Set(requiredDependencies.map(dependency => dependency.resourceRoot))) {
-    copyDependencies(resourceRoot, requiredDependencies.filter(dependency => dependency.resourceRoot === resourceRoot).map(dependency => dependency.name));
-  }
-  preparedDependencies = requiredDependencies.map(dependency => {
-    const metadata = dependencyMetadata(dependency.resourceRoot, dependency.name, dependency.version);
-    const path = `${dependency.resourceRoot}/${dependency.name}`;
-    if (!outputs.has(`${path}/package.json`)) throw new Error(`Prepared dependency was not copied: ${dependency.name}`);
-    return { name: dependency.name, version: dependency.version, path, entry: metadata.entry };
-  });
-}
-const dependenciesBundled = preparedDependencies.length === requiredDependencies.length && requiredDependencies.length > 0;
-if (requireDependencies && !dependenciesBundled) throw new Error('Prepared dependency closure is incomplete');
+for (const name of ['index.html','app.js','app.css']) copy(`skills/multi-task-flow/dist/${name}`, undefined, false, `skills/multi-task-flow-runtime/dist/${name}`);
+if (requireDependencies) validateInstalledDependencies();
 copyRootFile('AGENTS.md');
 const packageIdentityBase = {
   packageName: packageMetadata.name,
@@ -251,6 +121,7 @@ const packageIdentityBase = {
   contracts: { ledgerContract: packageContracts.ledger, apiVersion: packageContracts.api, frontendContract: packageContracts.frontend, viewerContract: packageContracts.viewer, serviceVersion: packageContracts.service },
   tarballDigest,
   gitTag,
+  canonicalDigestAlgorithm: 'path-byte-v2',
 };
 const generatedPackage = JSON.stringify({ private: true, type: 'module', packageName: packageMetadata.name, packageVersion: buildVersion, compatibilityLine: packageConfig.compatibilityLine, skillVersion: packageConfig.skillVersion }, null, 2) + '\n';
 writeFileSync(resolve(target, 'package.json'), generatedPackage);
@@ -258,6 +129,6 @@ writeFileSync(resolve(target, 'package.json'), generatedPackage);
 const finalInventory = [...outputs.values()].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
 const buildId = createHash('sha256').update(JSON.stringify({ ...packageIdentityBase, files: finalInventory })).digest('hex');
 const identity = { ...packageIdentityBase, buildId };
-const artifact = { schemaVersion: 2, packageName: packageMetadata.name, packageVersion: buildVersion, compatibilityLine: packageConfig.compatibilityLine, skillVersion: packageConfig.skillVersion, sourceCommit: manifest.commit, sourceSha, mergeSha: packageIdentityBase.mergeSha, candidateSha: sourceSha, dirty, runtime: 'bun@1.4.4', identity, buildId, tarballDigest, gitTag, dependenciesBundled, dependencies: preparedDependencies, omittedResources: packageOmissions, files: finalInventory };
+const artifact = { schemaVersion: 3, packageName: packageMetadata.name, packageVersion: buildVersion, compatibilityLine: packageConfig.compatibilityLine, skillVersion: packageConfig.skillVersion, sourceCommit: manifest.commit, sourceSha, mergeSha: packageIdentityBase.mergeSha, candidateSha: sourceSha, dirty, runtime: 'bun@1.4.4', identity, buildId, tarballDigest, gitTag, canonicalDigestAlgorithm: 'path-byte-v2', dependenciesBundled: false, dependencies: requiredDependencies, omittedResources: packageOmissions, files: finalInventory };
 writeFileSync(resolve(target, 'artifact-manifest.json'), JSON.stringify(artifact, null, 2) + '\n');
-console.log(JSON.stringify({ artifact: target, package: packageMetadata.name, version: buildVersion, compatibilityLine: packageConfig.compatibilityLine, runtime: 'bun@1.4.4', resources: finalInventory.length, dependenciesBundled, source: sourceSha, merge: packageIdentityBase.mergeSha, buildId, dirty }));
+console.log(JSON.stringify({ artifact: target, package: packageMetadata.name, version: buildVersion, compatibilityLine: packageConfig.compatibilityLine, runtime: 'bun@1.4.4', resources: finalInventory.length, dependenciesBundled: false, dependencies: requiredDependencies, source: sourceSha, merge: packageIdentityBase.mergeSha, buildId, dirty }));

package/toolkit/skills/multi-task-flow/scripts/preview-source.ts

@@ -23,6 +23,7 @@ import {
 import { ServiceState } from "../lib/service-state";
 import { servicePaths } from "../lib/service-paths";
 import { ServiceAuth } from "../lib/service-auth";
+import { versionEnvelope } from "../lib/contract";
 import { runDaemon } from "../lib/service-lifecycle";
 import { compatibility, type ReleaseManifest } from "../lib/service-contract";
 import { buildId, digest } from "../lib/service-release";
@@ -112,9 +113,11 @@ files.viewer = digest(readFileSync(import.meta.path));
 const body = {
   schema_version: 1 as const,
   source_sha: source.stdout.toString().trim(),
+  ledger_contract: 3,
   service_version: "source-preview",
   platform:
     `${process.platform}-${process.arch}` as ReleaseManifest["platform"],
+  ...versionEnvelope,
   ...compatibility,
   files,
 };

package/toolkit/skills/multi-task-flow/scripts/test-viewer-source.ts

@@ -10,7 +10,7 @@ const temporary = realpathSync(mkdtempSync(join(tmpdir(), 'viewer-source-test-')
 const output = join(temporary, 'package');
 const env = { ...process.env, MULTI_TASK_FLOW_PROFILE:'test', MULTI_TASK_FLOW_ROOT:join(temporary,'state') };
 try {
-  const build=spawnSync(process.execPath,[join(root,'skills/multi-task-flow/scripts/build-service.ts'),'--output',output,'--service-version','0.0.0-test'],{cwd:temporary,env,encoding:'utf8',timeout:120000});
+  const build=spawnSync(process.execPath,[join(root,'skills/multi-task-flow-runtime/scripts/build-service.ts'),'--output',output,'--service-version','0.0.0-test'],{cwd:temporary,env,encoding:'utf8',timeout:120000});
   assert.equal(build.status,0,build.stderr);
   const manifest=JSON.parse(readFileSync(join(output,'manifest.json'),'utf8'));
   assert.equal(manifest.schema_version,2);