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

package/toolkit/skills/multi-task-flow/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "multi-task-flow",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "bun test --path-ignore-patterns 'tests/ui/**'",
+    "test:ui": "bun test --preload ./tests/ui/setup.ts tests/ui",
+    "test:all": "bun run test && bun run test:ui",
+    "build": "bun run scripts/build.ts",
+    "verify": "bun run test:all && bun run build",
+    "demo:static": "bun run build && bun run scripts/demo-static.ts",
+    "preview:idle-archive": "bun run scripts/preview-source.ts --scenario agent-idle-archive",
+    "preview:source": "bun run scripts/preview-source.ts",
+    "demo:single-delivery-unit": "bun run build && bun run scripts/demo-static.ts --single-delivery-unit",
+    "preview:single-delivery-unit": "bun run scripts/preview-source.ts --single-delivery-unit"
+  },
+  "dependencies": {
+    "@xyflow/react": "12.12.1",
+    "elkjs": "0.12.1",
+    "lucide": "1.65.0",
+    "moment": "2.31.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "vis-data": "8.0.6",
+    "vis-timeline": "8.5.6",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "4.3.3",
+    "@testing-library/dom": "10.4.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "daisyui": "5.7.50",
+    "happy-dom": "21.0.4",
+    "playwright": "1.64.1",
+    "tailwindcss": "4.3.3",
+    "typescript": "5.9.3"
+  }
+}

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

@@ -0,0 +1,60 @@
+# Shared viewer operations
+
+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:
+
+- `ensure`, `renew`, `release`: `{"run_id":"example","thread_id":"main-thread","api_version":1}`.
+- `status`, `doctor`: `{}`. Inspect configured identity and runtime before remediation.
+- `login`: `{}` or `{"run_id":"example"}`. Its returned target URL contains a sensitive one-time query ticket.
+
+## Explicit maintenance
+
+Build from clean committed source after `bun --no-install run build` in the Skill: `bun --no-install scripts/build-service.ts --output /absolute/new-bundle --service-version <semver>`. The v2 bundle includes a shell launcher, TypeScript sources, prepared dependencies, browser assets and a manifest binding source SHA, platform, file digests and compatibility. A Skill update flow may place a newly built candidate under `candidates/<build-id>/`; the next `ensure` verifies and stages it, runs compatibility preflight, and uses the normal live switch and health-check rollback path. The launcher requires the trusted Bun 1.4.4 executable at the absolute path and SHA-256 pinned when building; it validates and snapshots that runtime before use. It runs independently of the caller working directory but does not include Bun. The maintenance CLI runs with Bun or the shell `viewer` launcher. The viewer preserves the caller environment and Bun configuration; it does not strip runtime variables or replace PATH. The launchd definition records the installing or upgrading caller PATH so background PR queries can resolve gh from the same tool environment. After changing tool locations, regenerate the definition through explicit service maintenance. Before loading package TypeScript through its integrity bootstrap, the launcher verifies all listed resources and rejects unlisted files, links and unsafe package permissions. Legacy compiled v1 bundles remain diagnostic-only and are never a startup or rollback fallback.
+
+- `install`: `{"source":"/absolute/bundle"}`; optional `registry_dir` selects the registry once. Installation initializes credentials and fixed high port, writes a private plist, and does not bootstrap/start it. Formal label: `cc.ivanli.loomhelm.multi-task-flow.viewer`. Next `ensure` bootstraps into the current user's GUI domain, or user domain on headless macOS, and kickstarts it.
+- `upgrade`: `{"source":"/absolute/bundle"}`. Validate hashes, platform and existing ledger/custom-view compatibility before stopping the old build. Switch the configuration atomically, start and health-check; failed health restores old configuration and existing lease deadlines. Old releases remain.
+- `rollback`: `{}`; the previous build must still support current data. This never restores an old data backup over new writes.
+- `credential-rotate`, `credential-revoke`: `{}`; replace the credential and revoke sessions, tickets and browser leases. Agent leases keep their deadlines.
+
+`ensure` performs none of these maintenance actions. No `sudo`, login autostart or unconditional KeepAlive is used. A crash is recovered on the next ensure. A lifetime instance lock, serialized startup and generation/PID guards prevent old processes from altering successor runtime/port ownership. Port conflict fails instead of changing the configured number or taking over another process. The registry directory is resolved at install and saved; no synthetic worktree or `agent_session` is recorded. Active lease registration covers actual runtime only. Logs contain fixed event identities, rotate at 5 MiB and retain three files.
+
+## Contracts
+
+Build ID, source SHA, API major, frontend contract, ledger schema/contract, ledger revision, run ID and plan ID are independent. This release publishes API v1 and frontend contract 1. Readable ledgers include schema 1 with absent legacy contract or contract 1, and schema 2 with contract 1, 2 or 3. Schema 2 contract 2 remains writable for compatibility, while new development baseline synchronization requires contract 3; legacy contracts remain read-only until explicit migration. No unpublished previous API is advertised. Future releases must explicitly publish every supported current/previous major and ledger combination. The newest reader must dual-read every supported historical shape; an older viewer is an isolated read-only fallback only when the newest reader cannot safely interpret that shape. Unsupported runs are marked individually; a CLI fails incompatible handshakes rather than installing or rewriting data.
+
+## Exact-source import and recovery
+
+`import` (alias `migrate`) accepts `{"source_root":"/absolute/legacy-data","run_id":"example"}`. It verifies one exact run under the ledger lock, stages and verifies a copy, journals the operation, renames the source to an adjacent hidden backup, and leaves a tombstone before publishing the destination. Bound legacy writers fail identity checks; the old path cannot be initialized over the tombstone. There is no automatic discovery, deletion, old-port listener or redirect. The result maps preserved run/plan identities to the new stable URL.
+
+Re-running the exact command is idempotent. A prepared journal after source sealing is resumed only after checking its exact operation paths and backup/ staging digests. A recreated source or changed destination blocks recovery; inspect the journal and retain both copies. No automatic rollback overwrites new data. Imports before source sealing can safely retry normal preparation. Code upgrades and this data operation remain separate explicit actions.
+
+## Compatibility preflight and ledger maintenance
+
+代码升级与持久迁移独立授权。`compatibility-check` 接受 `{ "source": "/absolute/bundle" }` 或 `{ "rollback": true }`，只读返回当前/目标构建、全部 run 的合同、revision、原始 SHA256、读写能力、fallback build、错误、写入降级项和 `report_digest`；预检会调用当前与候选 release 自身的 `reader-check`，不能只相信 manifest 的 `readable` 声明。若候选 reader 失败但当前 reader 仍能证明该 run 可读，报告会标记 `fallback_readable` 并允许切换，网页通过旧 viewer 只读投影继续访问；只有两者都无法证明读取安全时才阻塞升级。完成、会话归档、无使用租约都不免除读取兼容，也不证明需要继续写入。已有只读 run 不要求迁移。损坏、不可读或自定义 view 不兼容不能确认绕过。
+
+只有当前构建可写而目标不可写的新增降级需要主人逐次确认。展示准确报告后，`upgrade` 或 `rollback` 可附加 `write_downgrade_approval: { report_digest, approval_ref, maintenance_thread_id }`。应用持锁重算报告，run 内容或构建变化即拒绝旧确认；没有降级时不接受多余确认。`install` 无当前构建时只要求读取兼容。错误的 `details` 包含具体 run、能力及预检报告；不要根据通用错误盲目迁移所有 run。
+
+合同迁移使用 `ledger-maintenance-check` 和 `ledger-maintenance-apply`，不是目录导入的历史 `import/migrate` 别名。`schema-2/contract-2` 到 `schema-2/contract-3` 的迁移只更新合同判别和版本 envelope，保留 backup、source digest、owner、revision 证据，不补造 `baseline_verified` 或历史同步 event；普通 orchestration `migrate` 与 `execution-profile-migrate` 仍只允许绑定 main。维护入口使用真实维护身份，不恢复原会话、不改 owner、不取得业务控制权。
+
+历史 `schema-2/contract-2` 账本若任一任务缺少 `execution_owner`、`conversation_policy` 或 `delivery_policy`，普通写入会在 `requireLedgerCompatibility(..., "write")` 处先返回 `HISTORICAL_LEDGER_READ_ONLY`，因此不会进入 engine，也不会自动推断策略；完整声明但语义冲突或值非法的历史策略同样保持只读并要求显式恢复；这条只读链与缺失默认 execution profile 是两个独立门禁。
+
+对该历史形态，唯一正式修复是对准确 run 执行 `ledger-maintenance-check` / `ledger-maintenance-apply` 的 `action: "contract"`。candidate 只为完全缺失的策略键补出显式 `null` 声明，并在报告和 request result 的 `task_execution_policy_migration` 中记录任务与字段；部分声明会以 `TASK_EXECUTION_POLICY_INCOMPLETE` 拒绝，不推断 owner、对话归属、交付方式、PR 或生命周期事实。普通 orchestration `migrate` 仍只处理 legacy/contract-1，不能用它绕过该门禁。
+
+先用 `ledger-maintenance-check` 输入 `{ "run_id": "exact-run", "action": "contract" }`。执行配置是另一个独立动作：`{ "run_id": "exact-run", "action": "execution-profile", "execution_profile": { "model": "<owner-selected-model>", "thinking": "<owner-selected-thinking>" } }`。check 返回原 owner、revision、源 SHA256、目标、当前/迁移后读取能力、未决操作和 `operation_digest`，不写入状态。
+
+获得主人对准确动作的批准、暂停旧写入器后，apply 传入同样动作参数，并添加 `expected_owner_thread_id`、`expected_revision`、`expected_ledger_sha256`、`operation_digest`、唯一 `request_id`、实际 `maintenance_thread_id`、`approval_ref`、`reason` 和 `writers_paused: true`。`approval_ref` 和暂停声明是同 OS 用户维护信任边界内的审计记录，不是独立认证或进程隔离证明。不要冒用原 owner。claimed/unknown 创建、合并和切割操作须由原业务流程对账，维护命令不会替它们收口；服务租约本身不阻塞。
+
+安全顺序是先显式升级至同时可读源/目标合同的 viewer，再批准单 run 合同迁移，再按需单独批准完整 profile 迁移。只有机械、无语义推断、幂等、可恢复且经过备份和 digest 验证的迁移可以自动执行；历史内容不自动清理。已提交但缺少源摘要或请求 sidecar 的旧迁移记录无法安全证明备份绑定原始源数据，重放必须进入显式恢复流程，系统不会自动补写 sidecar 或接受该重放。若最新 viewer 无法读取某个 run，已配置 `previous_build` 的 viewer 可通过 `GET /api/v1/runs/<run-id>/legacy-view` 请求明确的旧 viewer 只读投影；该端点不创建 lease、不接受 mutation、不推进 owner 或 revision。服务未安装或不支持目标时 apply 拒绝；不为历史展示补造模型或完成事实。维护锁、run 锁覆盖复核和原子提交，完整旧文件写入 `ledger.maintenance-<request_id>.json`，并以 request identity sidecar 绑定 `request_id`、command 和 `canonical_input`；sidecar 先于新备份持久化，只有精确匹配的旧备份或仅 sidecar 中间状态可以补绑/恢复，损坏、不匹配或 replay 工件校验失败时 fail closed。真实维护身份和批准引用保留于账本 request result。每次变更 revision 增加 1；同请求同内容重放，异内容拒绝。
+
+维护迁移完成后，bootstrap 仍由绑定的 main conversation 持有：已完成文档/工作区 atom 只能对应已有的 workspace 和提交事实，`parent_pr` 仍为 `null`、`pr_created` 仍为 `unknown`，直到真实 `publish-pr` receipt 被记录；不得把其他 delivery unit 的实现 PR（例如 PR `#360`）挂到 bootstrap，也不得用迁移补造父 PR 或合并事实。
+
+备份后中断可用相同请求恢复，提交后响应丢失可安全重放。冲突保留双方证据，不覆盖备份或账本。代码健康失败恢复原构建和租约期限；新数据不被旧备份覆盖。迁移后旧构建不可读时 rollback 拒绝，采用兼容过渡构建或向前修复。合作锁不能防止同用户手工改文件或不遵守协议的旧写入器，主人必须确认这些写入已暂停。
+
+## 停服诊断
+
+`viewer.jsonl` 中 `stopping` 记录关闭入口，`stopped` 记录完成；`stop_started_at` 和 `stop_completed_at` 分别表示两个阶段。原因区分 `SIGTERM`、`SIGINT`、`leases_expired`、`lease_state_error`、`registry_heartbeat_error`、`startup_error` 和 `requested`。旧构建的 `signal` 也可能来自内部异常，不能据此推断 OS 信号或发送者。注册表锁超时以固定错误码 `REGISTRY_LOCK_TIMEOUT` 记录：前两次失败保留监听，第三次关闭；成功心跳产生恢复事件并清零。其他未知错误及所有权变化立即关闭。日志不输出异常消息、路径或凭据，诊断写入失败只输出固定提示。
+
+服务 label 从 `cn.ivan.multi-task-flow.viewer` 改为 `cc.ivanli.loomhelm.multi-task-flow.viewer`；隔离实例保留原有 profile 后缀。已有安装使用新 bundle 的维护 CLI 执行显式 `upgrade`，卸载当前 profile 的新旧 label，再生成新 plist 并启动。普通 `ensure` 遇到旧 plist 时要求升级，不自动迁移。数据根目录、端口 registry scope、凭据和运行账本保持原位。
+
+展示服务使用 launchd 的 `Interactive` 进程分类：它直接响应用户的 HTTP 操作，不使用 XPC 活动驱动的 `Adaptive` 分类。`Background` 的 I/O 限流会拖慢完整资源校验。启动、升级与恢复使用单调时钟限定 60 秒健康等待窗口，单次 HTTP 探测最多另占 1.5 秒；临时维护租约为 90 秒，在原生启动前后分别续租，覆盖整个健康等待窗口，结束或恢复失败后释放。已有 Agent／浏览器租约的期限不延长。超时仍执行既有失败恢复，完整性校验不跳过。

package/toolkit/skills/multi-task-flow/scripts/build-service.ts

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { compatibility } from "../lib/service-contract";
+import { buildId, digest, verifyRelease } from "../lib/service-release";
+import { requireCondition } from "../lib/errors";
+import { copySkillSources } from "../lib/package-source.ts";
+import { SKILL_ID, SKILL_VERSION, VIEWER_CONTRACT } from "../lib/contract";
+
+const args = process.argv.slice(2);
+const option = (name: string) => args[args.indexOf(name) + 1];
+const output = args.includes("--output") ? resolve(option("--output")!) : null;
+const version = args.includes("--service-version") ? option("--service-version") : null;
+requireCondition(output && version && /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(version), "INVALID_ARGUMENTS", "build-service.ts --output <new-directory> --service-version <semver>");
+requireCondition(!existsSync(output), "OUTPUT_EXISTS", "Build output must be a new directory");
+requireCondition(Bun.version === "1.4.4", "RUNTIME_REQUIRED", "Bun 1.4.4 is required");
+const root = resolve(import.meta.dir, "../../..");
+const source = Bun.spawnSync(["git", "rev-parse", "HEAD"], { cwd: root });
+requireCondition(source.exitCode === 0, "SOURCE_IDENTITY_REQUIRED", "Build requires a source commit");
+const clean = Bun.spawnSync(["git", "status", "--porcelain"], { cwd: root });
+requireCondition(clean.exitCode === 0 && !clean.stdout.toString().trim(), "DIRTY_SOURCE", "Release builds require committed clean source");
+const executable = realpathSync(process.execPath);
+const runtime = lstatSync(executable);
+requireCondition(runtime.isFile() && runtime.nlink === 1 && (runtime.mode & 0o022) === 0 && (runtime.uid === 0 || runtime.uid === process.getuid?.()), "RUNTIME_UNTRUSTED", "Bun runtime must be a trusted regular file");
+mkdirSync(output, { recursive: true, mode: 0o700 });
+const files: Record<string,string> = copySkillSources(root, output, { dependencies: true });
+const quote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+const runtimeSha = digest(readFileSync(executable));
+const manifest = { schema_version: 2 as const, source_sha: source.stdout.toString().trim(), skill_id: SKILL_ID, skill_version: SKILL_VERSION, ledger_contract: 3, viewer_contract: VIEWER_CONTRACT, service_version: version, platform: `${process.platform}-${process.arch}` as "darwin-arm64", api_versions: compatibility.api_versions, frontend_contracts: compatibility.frontend_contracts, readable: compatibility.readable, writable: compatibility.writable, readable_releases: [version], migration_guides: [], files };
+// Bind resource metadata before adding the launcher itself, avoiding a self-hash cycle.
+const resourceIdentity = buildId(manifest);
+const bootstrap = `import * as fs from "node:fs";import * as path from "node:path";import{createHash}from"node:crypto";
+const hash=v=>createHash("sha256").update(v).digest("hex");
+const root=process.env.LOOMHELM_VIEWER_RELEASE,temporary=process.env.LOOMHELM_VIEWER_RUNTIME_TEMP;
+delete process.env.LOOMHELM_VIEWER_RELEASE;delete process.env.LOOMHELM_VIEWER_RUNTIME_TEMP;
+try {
+const trusted=(p,stickyAncestor=false)=>{const s=fs.lstatSync(p);if(s.isSymbolicLink()||(s.uid!==0&&s.uid!==process.getuid())||((s.mode&0o022)!==0&&!(stickyAncestor&&s.isDirectory()&&s.uid===0&&(s.mode&0o1000)!==0)))throw Error("VIEWER_RESOURCE_UNTRUSTED");return s;};
+for(let p=root;;p=path.dirname(p)){if(!trusted(p,p!==root).isDirectory())throw Error("VIEWER_DIRECTORY_UNTRUSTED");if(p===path.dirname(p))break;}
+const read=p=>{const s=trusted(p);if(!s.isFile()||s.nlink!==1)throw Error("VIEWER_RESOURCE_UNTRUSTED");const fd=fs.openSync(p,fs.constants.O_RDONLY|fs.constants.O_NOFOLLOW);try{const a=fs.fstatSync(fd);if(a.dev!==s.dev||a.ino!==s.ino)throw Error("VIEWER_RESOURCE_CHANGED");return fs.readFileSync(fd);}finally{fs.closeSync(fd);}};
+const m=JSON.parse(read(path.join(root,"manifest.json"))),{build_id,...body}=m;
+const launcherHash=body.files.viewer;delete body.files.viewer;
+if(body.skill_id===${JSON.stringify(SKILL_ID)})delete body.skill_id;
+if(body.skill_version===${JSON.stringify(SKILL_VERSION)})delete body.skill_version;
+if(body.ledger_contract===2)delete body.ledger_contract;
+if(body.viewer_contract===2||body.viewer_contract===${VIEWER_CONTRACT})delete body.viewer_contract;
+body.files=Object.fromEntries(Object.entries(body.files).sort(([a],[b])=>a.localeCompare(b)));
+if(hash(JSON.stringify(body))!==${JSON.stringify(resourceIdentity)})throw Error("VIEWER_RESOURCE_IDENTITY_MISMATCH");
+body.files.viewer=launcherHash;
+// Reject additional files before Bun can resolve an extensionless import to them.
+const listed=new Set([...Object.keys(body.files),"manifest.json"]);
+const walk=directory=>{for(const name of fs.readdirSync(directory)){const p=path.join(directory,name),s=trusted(p);if(s.isDirectory())walk(p);else if(!s.isFile()||s.nlink!==1||!listed.has(path.relative(root,p).split(path.sep).join("/")))throw Error("VIEWER_RESOURCE_UNLISTED");}};
+walk(root);
+for(const [name,expected]of Object.entries(body.files)){
+if(name.includes("\\\\")||name.split("/").some(p=>!p||p==="."||p==="..")||(name!=="viewer"&&!name.startsWith("skills/")))throw Error("VIEWER_RESOURCE_PATH");
+const p=path.join(root,name);if(fs.realpathSync(p)!==p)throw Error("VIEWER_RESOURCE_PATH");
+for(let d=path.dirname(p);d!==root;d=path.dirname(d))if(!trusted(d).isDirectory())throw Error("VIEWER_DIRECTORY_UNTRUSTED");
+if(hash(read(p))!==expected)throw Error("VIEWER_RESOURCE_CHECKSUM");
+}
+} finally {fs.unlinkSync(path.join(temporary,"bun"));fs.rmdirSync(temporary);}
+`;
+const bootstrapUrl = "data:text/javascript;base64," + Buffer.from(bootstrap).toString("base64");
+const launcher = `#!/bin/bash
+set -euo pipefail
+viewer_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)
+runtime=${quote(executable)}
+os=$(uname -s)
+metadata() {
+  if [[ "$os" == Darwin ]]; then stat -f '%d:%i:%l:%u:%Lp' -- "$1"; else stat -c '%d:%i:%h:%u:%a' -- "$1"; fi
+}
+trusted() {
+  local path="$1" allow_group="\${2:-0}" uid mode sticky_directory=0
+  [[ -e "$path" && ! -L "$path" ]] || return 1
+  if [[ "$os" == Darwin ]]; then uid=$(stat -f '%u' -- "$path"); mode=$(stat -f '%Lp' -- "$path"); else uid=$(stat -c '%u' -- "$path"); mode=$(stat -c '%a' -- "$path"); fi
+  [[ -d "$path" ]] && sticky_directory=1
+  [[ "$uid" == 0 || "$uid" == "$(id -u)" ]] && (( (8#$mode & 18) == 0 || ($uid == 0 && $sticky_directory == 1 && (8#$mode & 512) != 0) || ($allow_group == 1 && $uid == $(id -u) && (8#$mode & 2) == 0) ))
+}
+# Validate the pinned executable and every ancestor before opening its descriptor.
+[[ -f "$runtime" && -x "$runtime" ]] && trusted "$runtime" || { echo BUN_RUNTIME_UNTRUSTED >&2; exit 2; }
+path=$(dirname -- "$runtime")
+while true; do trusted "$path" 1 || { echo BUN_RUNTIME_ANCESTOR_UNTRUSTED >&2; exit 2; }; [[ "$path" == / ]] && break; path=$(dirname -- "$path"); done
+identity=$(metadata "$runtime")
+exec 7<"$runtime"
+if [[ "$os" == Darwin ]]; then opened=$(env -i /usr/bin/perl -e 'my @s=stat(STDIN) or exit 1; printf "%d:%d:%d:%d:%o",$s[0],$s[1],$s[3],$s[4],$s[2]&07777' <&7); else opened=$(stat -L -c '%d:%i:%h:%u:%a' /proc/self/fd/7); fi
+[[ "$opened" == "$identity" ]] || { echo BUN_RUNTIME_CHANGED >&2; exit 2; }
+# A private executable snapshot avoids re-opening the checked runtime path.
+temporary_root=$(CDPATH= cd -- "\${TMPDIR:-/tmp}" && pwd -P) || { echo VIEWER_TEMP_UNTRUSTED >&2; exit 2; }
+path="$temporary_root"
+while true; do [[ -d "$path" ]] && trusted "$path" || { echo VIEWER_TEMP_UNTRUSTED >&2; exit 2; }; [[ "$path" == / ]] && break; path=$(dirname -- "$path"); done
+temporary=$(mktemp -d "$temporary_root/loomhelm-viewer.XXXXXX")
+chmod 700 "$temporary"
+cleanup() { rm -f -- "$temporary/bun"; rmdir -- "$temporary"; }
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM HUP
+(set -C; cat <&7 > "$temporary/bun")
+exec 7<&-
+chmod 700 "$temporary/bun"
+actual=$(shasum -a 256 "$temporary/bun")
+[[ "\${actual%% *}" == ${quote(runtimeSha)} ]] || { echo BUN_RUNTIME_CHANGED >&2; exit 2; }
+version=$("$temporary/bun" --version)
+[[ "$version" == 1.4.4 ]] || { echo BUN_RUNTIME_REQUIRED >&2; exit 2; }
+LOOMHELM_VIEWER_RELEASE="$viewer_dir" LOOMHELM_VIEWER_RUNTIME_TEMP="$temporary" exec "$temporary/bun" --preload=${quote(bootstrapUrl)} --no-install "$viewer_dir/skills/multi-task-flow/scripts/service.ts" "$@"
+`;
+
+writeFileSync(join(output,"viewer"), launcher, { mode: 0o700 });
+files.viewer = digest(launcher);
+writeFileSync(join(output,"manifest.json"), JSON.stringify({ ...manifest, build_id: buildId(manifest) },null,2)+'\n', {mode:0o600});
+const verified = verifyRelease(output);
+console.log(JSON.stringify({ok:true, build_id:verified.build_id, output, runtime:'bun@1.4.4'}));

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

@@ -0,0 +1,38 @@
+import { copyFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const root = join(import.meta.dir, "..");
+const outputIndex = process.argv.indexOf("--output");
+if (outputIndex >= 0 && !process.argv[outputIndex + 1])
+  throw new Error("Missing --output directory");
+const output =
+  outputIndex >= 0
+    ? resolve(process.argv[outputIndex + 1]!)
+    : join(root, "dist");
+mkdirSync(output, { recursive: true });
+const result = await Bun.build({
+  entrypoints: [join(root, "web", "app.ts")],
+  outdir: output,
+  naming: "app.js",
+  target: "browser",
+  minify: true,
+  define: { "process.env.NODE_ENV": JSON.stringify("production"), "import.meta.env": JSON.stringify({MODE:"production"}) },
+});
+if (!result.success) {
+  for (const log of result.logs) console.error(log);
+  process.exit(1);
+}
+const css = Bun.spawnSync(
+  [
+    join(root, "node_modules", ".bin", "tailwindcss"),
+    "-i",
+    "web/app.css",
+    "-o",
+    join(output, "app.css"),
+    "--minify",
+  ],
+  { cwd: root, stdout: "inherit", stderr: "inherit" },
+);
+if (css.exitCode !== 0) process.exit(css.exitCode ?? 1);
+copyFileSync(join(root, "web", "index.html"), join(output, "index.html"));
+console.log("Dashboard assets built successfully");

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

@@ -0,0 +1,54 @@
+#!/usr/bin/env -S bun --no-install
+import { readFileSync, writeFileSync } from 'node:fs';
+const manifest = JSON.parse(readFileSync('skills/source-manifest.json', 'utf8'));
+const files = manifest.files;
+const dependencyConditions = {
+  'git-sync': 'topic branch synchronization or detached-HEAD alignment',
+  'grill-with-docs': 'unresolved design decisions; must return to design rather than execute',
+  'agent-vm': 'isolated Linux / Docker / heavyweight integration verification',
+  'ego-browser': 'browser operations and controlled visual evidence',
+  'firmware-display-preview': 'firmware display visual scenarios only',
+};
+// Conservative inventory of conditional source requirements. Presence is not
+// authorization, login, or proof that a scenario has executed successfully.
+const delivery = ['project-engineering-workflow', 'normal-flow', 'fast-flow', 'local-merge-flow', 'flow-continue'];
+const cliRequirements = name => {
+  const result = [];
+  const add = (command, condition) => result.push({ command, strength: 'required-when-applicable', condition });
+  if ([...delivery, 'git-branch', 'git-worktree', 'git-cleanup', 'find-next-plan', 'docs-migrate', 'spec-sync', 'topic-spec', 'solution-sync', 'project-doc-promote', 'dot-codex-development', 'rust-crate-release', 'srv-101-ops'].includes(name)) add('git', 'repository inspection or Git operations');
+  if ([...delivery, 'git-cleanup', 'find-next-plan', 'rust-crate-release'].includes(name)) {
+    add('gh', 'GitHub backend PR, check or release operations only');
+    if (name !== 'rust-crate-release') add('tea', 'Gitea backend operations only');
+  }
+  if (name === 'rust-crate-release') { add('cargo', 'crate validation or publication'); add('rustup', 'toolchain inspection or explicitly authorized changes'); }
+  if (name === 'srv-101-ops') add('ssh', 'authorized remote machine inspection');
+  if (['storybook-stories', 'storybook-screenshots'].includes(name)) add('bun', 'original Storybook project build scripts when the selected project uses Bun');
+  if (['storybook-screenshots', 'ui-visual-evidence', 'gui-escalation-gate', 'cn-ecommerce-data-collection', 'kaisoumail-deployment-inventory'].includes(name)) add('ego-browser', 'browser operations after reading the external ego-browser Skill');
+  if (name === 'multi-task-flow') add('launchctl', 'macOS installed viewer only; not required by the POSIX ledger or foreground HTTP');
+  return result;
+};
+const hostRequirements = name => {
+  const map = {
+    'fresh-thread-dispatch': [{ capability: 'mcp__codex_app__create_thread', condition: 'ordinary fresh user-owned task dispatch; active Multi-task Flow uses its separate conversation-create contract' }],
+    'multi-task-flow': [{ capability: 'codex.app_server_control', condition: 'real thread creation, observation and notification through the selected Codex control socket' }],
+    'git-worktree': [{ capability: 'mcp__codex_app__create_worktree', condition: 'Codex-managed task worktrees only' }],
+    'git-cleanup': [{ capability: 'mcp__codex_app__archive_worktree', condition: 'cleanup of a Codex-managed worktree only' }],
+    'hardware-doc-ingest': [{ capability: 'mcp__mineru__parse_documents', condition: 'PDF conversion through the original MinerU tool' }],
+    'gui-escalation-gate': [{ capability: 'computer_use', condition: 'explicitly authorized escalation only, never an automatic fallback' }],
+  };
+  return (map[name] ?? []).map(item => ({ ...item, strength: 'required-when-applicable' }));
+};
+const entries = manifest.skills.map(name => {
+  const resources = files.filter(file => file.path.startsWith(`skills/${name}/`));
+  const text = resources.filter(file => file.path.endsWith('.md')).map(file => readFileSync(file.path, 'utf8')).join('\n');
+  const referenced = [...new Set([...text.matchAll(/\$([a-z][a-z0-9]*(?:-[a-z0-9]+)+)/g)].map(match => match[1]))];
+  return { name, entry: `skills/${name}/SKILL.md`, files: resources.length,
+    internalSkills: referenced.filter(ref => manifest.skills.includes(ref) && ref !== name).sort(),
+    externalSkills: referenced.filter(ref => dependencyConditions[ref]).sort().map(skill => ({ skill, strength: 'required-when-applicable', condition: dependencyConditions[skill] })),
+    externalCommands: cliRequirements(name),
+    hostCapabilities: hostRequirements(name),
+    platform: name === 'multi-task-flow' ? 'macOS launchd for installed viewer; POSIX ledger/HTTP on macOS/Linux' : 'POSIX; specialty tools and host capabilities as declared by the original Skill',
+    scripts: resources.filter(file => /\/scripts\/.+/.test(file.path)).map(file => file.path),
+  };
+});
+writeFileSync('skills/catalog.json', JSON.stringify({ schemaVersion: 1, sourceCommit: manifest.commit, entries }, null, 2) + '\n');

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env -S bun --no-install
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+const root = resolve(import.meta.dirname, '../../..');
+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 findings = [];
+const gitRoot = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd:root, encoding:'utf8' });
+if (gitRoot.status === 0 && gitRoot.stdout.trim() === root) {
+  const tracked = spawnSync('git', ['ls-files', '-z', '--', 'skills/', 'clients/typescript/'], { cwd:root, encoding:'utf8' });
+  if (tracked.status !== 0) throw new Error('Cannot verify tracked resource coverage');
+  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/') && !covered.has(file) && !['skills/source-manifest.json','skills/catalog.json'].includes(file)) findings.push('unlisted:'+file);
+  }
+}
+
+for (const excluded of manifest.exclusions ?? []) {
+  const installed = excluded.sourcePrefix.startsWith('docs/') ? `skills/docs/vendor/dot-codex/${excluded.sourcePrefix.slice(5)}` : `skills/${excluded.sourcePrefix}`;
+  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 stat = lstatSync(target);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) { findings.push(`unsafe:${file.path}`); continue; }
+  const digest = hash(readFileSync(target));
+  if (refresh) {
+    file.installedSha256 = digest;
+    if (file.sourceSha256) file.adaptation = digest === file.sourceSha256 ? 'unchanged' : 'loomhelm-runtime-path-or-contract-adaptation';
+  } else if (digest !== file.installedSha256) findings.push(`digest:${file.path}`);
+}
+if (manifest.skills.length !== 29 || new Set(manifest.skills).size !== 29) findings.push('skill-count');
+for (const name of manifest.skills) if (!manifest.files.some(file => file.path === `skills/${name}/SKILL.md`)) findings.push(`skill:${name}`);
+if (findings.length) { console.error(JSON.stringify({ ok: false, findings })); process.exit(1); }
+if (refresh) writeFileSync(path, JSON.stringify(manifest, null, 2) + '\n');
+console.log(JSON.stringify({ ok: true, skills: manifest.skills.length, sourceFiles: manifest.files.length, adapted: manifest.files.filter(file => file.adaptation !== 'unchanged').length, additions: manifest.additions?.length ?? 0, source: manifest.commit }));

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

@@ -0,0 +1,84 @@
+#!/usr/bin/env -S bun --no-install
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, realpathSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+// Source/vendor layouts share the migration inventory. Discovery of SKILL.md
+// alone does not establish that its executable dependency closure was installed.
+export function checkSkillsInstallation(root, { probe = false } = {}) {
+  root = resolve(root);
+  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 contained = path => {
+    const file = resolve(root, path);
+    if (!existsSync(file)) return false;
+    const stat = lstatSync(file);
+    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);
+  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');
+    for (const match of text.matchAll(/(?:from\s*|import\s*\(?\s*)["'](\.[^"']+)["']/g)) {
+      const target = resolve(root, dirname(file.path), match[1]);
+      if (!target.startsWith(resolve(root, 'skills') + '/')) escapedImports.push({ file: file.path, import: match[1] });
+    }
+  }
+  const sourceComplete = missing.length === 0 && modified.length === 0 && escapedImports.length === 0;
+  const runtime = { name: 'bun', required: '1.4.4', actual: typeof Bun === 'undefined' ? null : Bun.version, available: typeof Bun !== 'undefined' && Bun.version === '1.4.4' };
+  const declared = sourceComplete ? JSON.parse(readFileSync(resolve(root,'skills/package.json'),'utf8')).dependencies ?? {} : {};
+  const dependencyRoots = [resolve(root,'skills/node_modules')];
+  // The independent client declares and prepares its packaged toolkit dependencies.
+  const clientPackage = resolve(root,'../package.json');
+  try {
+    if (sourceComplete && root.endsWith('/toolkit') && existsSync(clientPackage) && JSON.parse(readFileSync(clientPackage,'utf8')).name === '@loomhelm/multi-task-flow') dependencyRoots.push(resolve(root,'../node_modules'));
+  } catch { /* Invalid parent metadata cannot authorize a dependency fallback. */ }
+  const dependencyMissing = Object.entries(declared).filter(([name,version]) => !dependencyRoots.some(directory => {
+    const file=resolve(directory,name,'package.json');
+    try { return realpathSync(file).startsWith(realpathSync(directory)+'/') && JSON.parse(readFileSync(file,'utf8')).version === version; } catch { return false; }
+  })).map(([name])=>name);
+  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','-']]]) {
+      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});
+    }
+    entrypoints.status = entrypoints.results.every(result => result.ok) ? 'passed' : 'failed';
+  }
+  return {
+    runtime, sourceComplete, dependencies, entrypoints,
+    ready: sourceComplete && runtime.available && entrypoints.status === 'passed',
+    ok: sourceComplete && (!probe || (runtime.available && entrypoints.status === 'passed')),
+    code: missing.length || modified.length || escapedImports.length ? 'SKILLS_INSTALLATION_INCOMPLETE' : probe && dependencyMissing.length ? 'SKILLS_RUNTIME_DEPENDENCY_MISSING' : 'SKILLS_SOURCE_LAYOUT_COMPLETE',
+    root, skills: manifest.skills.length, missing, modified, escapedImports,
+    // Host capabilities remain separate from these source and executable probes.
+    scope: 'source-resource-layout',
+    requiredSparsePaths: ['skills'],
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  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]');
+    process.exitCode = 2;
+  } else {
+    try {
+      const report = checkSkillsInstallation(args[1] ?? resolve(import.meta.dirname, '../..'), {probe});
+      console.log(JSON.stringify(report));
+      process.exitCode = report.ok ? 0 : 1;
+    } catch (error) {
+      console.error(String(error));
+      process.exitCode = 2;
+    }
+  }
+}