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

package/toolkit/skills/docs/vendor/dot-codex/specs/README.md

@@ -0,0 +1,110 @@
+# 规格（Spec）总览
+
+`docs/specs/**` 是 **topic-level specification catalog**：每个 spec 对应一个稳定主题、能力、接口或约束的长期契约。它回答的是“这个主题长期应该保持什么为真”，而不是“这次任务做到了第几步”。
+
+每个 spec 目录默认同时承载三层信息：
+
+- `SPEC.md`：当前有效规范 / 主题契约；`## Related ADRs` 列出当前关联 ADR，或写 `None`
+- `IMPLEMENTATION.md`：实现覆盖、当前状态、剩余缺口与 rollout 事实
+- `HISTORY.md`：主题局部生命周期、替换、兼容性与必要背景；不复制 ADR 的完整取舍理由
+
+`docs/specs/**` 的主视角仍然是工程流程与 Agent memory，不是项目级人类文档入口。若某项结论已经成为项目当前真相，应再整理到 repo-established human-facing project docs / entry docs（通常 `docs/**`，也可为根入口文档），而不是长期只留在 spec 里。
+
+> Legacy compatibility: historical repos may still contain `docs/plan/**/PLAN.md` or ID-prefixed spec directories. New entries must use `docs/specs/<topic>/SPEC.md`.
+
+## 快速新增一个规格
+
+1. 选择一个唯一且稳定的 topic slug。
+2. 新建目录：`docs/specs/<topic>/`（`<topic>` 使用简短 kebab-case）。
+3. 在该目录下创建 `SPEC.md`、`IMPLEMENTATION.md`、`HISTORY.md`：
+   - `SPEC.md` 写清主题的背景、范围、稳定 `REQ-*` 需求、`VER-*` 验证与 `## Related ADRs`；关联 ADR 按路径升序列出 Markdown 链接，无关联时写 `None`；执行状态、命令、PR/commit 关联分别写入 companion docs；
+   - `IMPLEMENTATION.md` 记录当前实现状态与覆盖进度；
+   - `HISTORY.md` 记录主题局部生命周期、替换、兼容性与相关 PR / commit / 后继 spec。
+4. 在下方 Index 表**表尾**新增一行，并把 `Lifecycle` 设为 `active`。
+
+## 目录与命名规则
+
+- 每个新规格一个目录：`docs/specs/<topic>/`。
+- `<topic>` 是短、稳定、唯一的 kebab-case slug；它是新 spec 的身份，不生成 ID。
+- 历史 ID 目录继续可读，批量规范化、冲突检查与入站链接更新由 `$docs-migrate MODE=specs-hygiene` 在明确确认后完成。
+- 人类可读标题写在 Index 的 `Topic` 列；标题变更不强制改目录名。
+- 规范正文：`docs/specs/<topic>/SPEC.md`
+- 实现状态：`docs/specs/<topic>/IMPLEMENTATION.md`
+- 演进历史：`docs/specs/<topic>/HISTORY.md`
+
+## Lifecycle 说明
+
+仅允许使用以下最小生命周期值：
+
+- `active`：当前主题 spec 仍是有效真相源。
+- `superseded`：已被 `Successor` 列指向的 topic spec 取代。
+- `archived`：仅保留历史参考，不再作为当前规范输入。
+
+## Implementation 列说明
+
+- `Implementation` 只保留**轻量摘要**，用于快速回答“这个 spec 现在实现到哪”。
+- 推荐值：
+  - `未开始`
+  - `部分完成 (x/y)`
+  - `已实现`
+  - `待刷新`
+- 详细状态、覆盖清单、rollout 事实与剩余缺口必须写在 `IMPLEMENTATION.md`，不要把 README 再膨胀回完整任务看板。
+
+## Index 顺序约定
+
+- `docs/specs/README.md` 的 Index 按创建顺序维护：最早创建的规格在前，后创建的规格在后。
+- 新增规格时把新行追加到 Index 表尾；仅更新 `Lifecycle` / `Implementation` / `Notes` 时不得重排既有行。
+- README 只保留 `Lifecycle` 与轻量 `Implementation` 摘要；详细实现状态与演进原因必须落在 spec 目录内的 companion docs，而不是只留在 workflow / PR / 提交历史里。
+
+## Index
+
+| Topic | Lifecycle | Implementation | Spec | Successor | Notes |
+| - | - | - | - | - | - |
+| PR freshness gate | active | 已实现 | `pr-freshness-gate/SPEC.md` | - | PR 阶段 stale/conflict 前置门禁 |
+| PR wait-state closeout | active | 已实现 | `pr-wait-state-closeout/SPEC.md` | - | 防止纯等待态被误当成可收尾停靠点 |
+| Local merge cleanup closeout | active | 已实现 | `local-merge-cleanup-closeout/SPEC.md` | - | 收紧 local-merge cleanup 决策树与恢复语义 |
+| Global port preview governance | active | 已实现 | `global-port-preview-governance/SPEC.md` | - | 统一本地长驻服务的端口归属检查、稳定随机分配、冲突处理与预览 URL 交付规则 |
+| Flow continue lock guard | active | 已实现 | `flow-continue-lock-guard/SPEC.md` | - | 固化锁定 flow 优先级，阻止热更新文案把旧 session 误改路由到 local-merge |
+| PR convergence batching | active | 已实现 | `pr-convergence-batching/SPEC.md` | `0016-bind-review-repairs-to-approved-scope.md`, `0017-review-readiness-and-runtime-launch.md` | CI remains SHA-bound; Review Readiness gates runtime formal launch, scoped findings form one Repair Batch, and only the final Candidate refreshes affected lanes |
+| PR post-open scope freeze | active | 已实现 | `pr-post-open-scope-freeze/SPEC.md` | - | PR 打开后默认冻结范围，允许 behind/main-sync 必要兼容修复 |
+| PR skill diagnosis thinning | superseded | 已实现 | `pr-skill-diagnosis-thinning/SPEC.md` | `agent-instruction-architecture/SPEC.md` | focused PR 规则已并入统一 instruction architecture 与共享 references |
+| Dev plan flow lock option guidance cleanup | active | 已实现 | `dev-plan-flow-lock-options/SPEC.md` | - | 移除 `flow_type` 选项完备性的硬约束，只保留完整列表建议与 local-merge 别名兼容 |
+| PR conflict auto heal | active | 已实现 | `pr-conflict-auto-heal/SPEC.md` | - | 将“Actions 缺席其实是 PR 冲突”收口到 freshness gate，并自动解冲续推；CI 缺席遵循共享四字段合同 |
+| Review proof ownership | superseded | 已实现 | `review-proof-ownership/SPEC.md` | `mandatory-local-review-proof/SPEC.md` | Historical ownership model retained only for audit |
+| Storybook skill upgrade | active | 已实现 | `storybook-skill-upgrade/SPEC.md` | - | 将 Storybook 交付升级为组件/片段优先：状态矩阵、关键 play、docs/canvas 双来源截图，整页证据默认走 `ui_demo` |
+| Review proof dedupe and wait guard | superseded | 已实现 | `review-proof-dedupe-wait-guard/SPEC.md` | `mandatory-local-review-proof/SPEC.md` | Historical replay compatibility; active proof uses direct structured evidence |
+| Review model and effort defaults | superseded | 已实现 | `review-effort-by-pr-stage/SPEC.md` | `workflow-agent-model-selection/SPEC.md` | Model selection remains separate from sub-agent proof acceptance |
+| Fast-track merge intent closeout | active | 已实现 | `fast-track-merge-intent-closeout/SPEC.md` | `0003-external-fact-delivery-gates.md`, `0008-direct-pr-merge-preflight.md`, `0021-runtime-derived-pre-merge-release-route.md`, `0024-stop-condition-driven-release-decision.md` | direct PR 通过只读 preflight 锁定 live head 并使用 `--match-head-commit`；区分普通合并与 cleanup；Step 5C 决策卡读取目标仓库策略和当前 PR 事实；预合并 route 静默派生且无发布面时不改标签；merge 后 release chain 独立 |
+| Local review necessity and proof | active | 已实现 | `mandatory-local-review-proof/SPEC.md` | `0014-direct-review-evidence.md`, `0016-bind-review-repairs-to-approved-scope.md`, `0017-review-readiness-and-runtime-launch.md`, `0032-flow-scoped-model-profile-allowlists.md` | Agent 记录 Tier 1..4 与理由；Review Readiness 后按当前 SHA 运行时创建 fresh structured review evidence，并按 exact six-profile direct-review allowlist 独立绑定 lane profile；完整 owner pair 原样交给 runtime，不进入 receipt review state machine |
+| Shared UI visual evidence gate | active | 已实现 | `shared-ui-visual-evidence-gate/SPEC.md` | `0003-task-scoped-pr-visual-evidence.md`, `0004-scope-authority-and-topic-spec-boundaries.md` | 任务级 PR 选图、受管正文、同路径基线比较与 touched-file 文档迁移已接入 |
+| Visual evidence whitespace trim | active | 已实现 | `visual-evidence-whitespace-trim/SPEC.md` | `0007-source-managed-component-evidence.md` | 页面保留 trim-only；组件证据由 Story 源管理展示面和一次 DOM 预检保证自然留白 |
+| Active long-task ownership wait guard | active | 已实现 | `active-long-task-ownership-wait-guard/SPEC.md` | - | 收紧 live 长任务的 ownership promise、停靠语义与 focused replay 守卫 |
+| Retire zellij service manager | active | 已实现 | `retire-legacy-service-manager/SPEC.md` | - | 删除已废弃服务托管 skill 与 repo 内配套辅助链，保留本机运行态残留为 out of scope |
+| Local chat image snapshots | active | 已实现 | `local-chat-image-snapshots/SPEC.md` | - | 为 owner-facing Chat 图片新增不可变快照 helper、Markdown/HTML Stop hook 与 Chat/PR URL 分离规则 |
+| PR live GitHub truth source | active | 已实现 | `pr-live-github-truth-source/SPEC.md` | - | 当前 PR blocker 从 live facts 推导；CI policy、expected checks、exact-SHA evidence 和 gate effect 分层 |
+| Global solutions docs-migrate | active | 已实现 | `global-solutions-docs-migrate/SPEC.md` | - | 收敛 docs-migrate / docs-solutions / 全局入口接线与 compatibility shim |
+| Native background preview handoff guard | active | 已实现 | `stable-preview-runtime/SPEC.md` | - | 为 owner-facing localhost handoff 收紧 native-background 契约，并补 pid-backed lease 自愈 |
+| Viewport-safe browser evidence capture | active | 已实现 | `viewport-safe-browser-evidence/SPEC.md` | - | 统一非改窗优先截图契约；未指定尺寸的移动端验收默认使用 `393x852` CSS px，resize 仅作可恢复兜底 |
+| Agent memory and project docs promotion | active | 已实现 | `agent-memory-project-docs/SPEC.md` | - | 固化 `specs + solutions` 与 human-facing project docs 分层，并新增 project-doc promotion gate / skill / docs-migrate 轨道 |
+| Topic-level spec model | active | 已实现 | `topic-spec-model/SPEC.md` | `0004-scope-authority-and-topic-spec-boundaries.md` | 让 `docs/specs/**` 回归可追溯主题级需求规格，并以 companion docs 承接实施与历史事实 |
+| Initiative delivery flow | superseded | 历史 | `initiative-flow/SPEC.md` | - | 历史协调契约，已退役 |
+| Dev plan goals-first contract rewrite | active | 已实现 | `dev-plan-goals-first/SPEC.md` | `0004-scope-authority-and-topic-spec-boundaries.md`, `0006-internal-plan-authorization-and-scope-constraints.md`, `0021-runtime-derived-pre-merge-release-route.md`, `0023-dev-plan-release-delivery-scope.md`, `0031-dev-plan-owner-review-projection.md`, `0032-dev-plan-single-finalization-gate.md` | 将显式 `dev-plan` 收敛为 canonical raw-plan 校验后生成九段 owner-facing projection 的单一最终门禁，并保留历史 JSONL 只读兼容 |
+| GUI escalation gate | active | 已实现 | `gui-escalation-gate/SPEC.md` | - | 保留 GUI 插件能力，以 `ego-browser` 作为默认浏览器入口，并把 Chrome control / DevTools 收口为显式例外、Computer Use 收口为最高升级路径 |
+| Dev plan default fast-track auto-lock | active | 已实现 | `dev-plan-default-fast-track-auto-lock/SPEC.md` | - | 未显式指定 flow 时默认锁定 `fast-track` + `merge-ready`，并把 `default_fast_track` 纳入合法 flow lock 证据 |
+| Git skill convergence | active | 已实现 | `git-skill-convergence/SPEC.md` | - | 将纯 git/local repo 操作收敛为 `git-branch`、`git-worktree`、`git-sync`、`git-cleanup`，并清退旧 prompts/skills |
+| Mainline baseline and topic branch freshness contract | active | 已实现 | `mainline-baseline-topic-branch-freshness/SPEC.md` | - | 显式 `$dev-plan` 必须声明具体开发基线，并把 shared workflow 的 topic branch 创建 / 双阶段同步收敛成统一合同 |
+| CVM imagegen fallback skill | active | 已实现 | `cvm-imagegen-skill/SPEC.md` | - | 新增显式 CLI 生图 fallback skill，固定使用 `CVM_API_KEY` 与 `https://vibe-code.ivanli.cc/v1`，不覆盖系统 `imagegen` |
+| Workflow execution receipts | active | 进行中 | `workflow-execution-receipts/SPEC.md` | - | 以非 tracked receipt 复用 validation/lifecycle 事实，并维护 review-orchestration 清退清单 |
+| Agent instruction architecture | active | 已实现 | `agent-instruction-architecture/SPEC.md` | - | 全局风险核心、深共享 Module、薄授权入口与行为回放门禁 |
+| Workflow agent model selection | active | 已实现 | `workflow-agent-model-selection/SPEC.md` | `0003-external-fact-delivery-gates.md`, `0014-direct-review-evidence.md`, `0016-bind-review-repairs-to-approved-scope.md`, `0017-review-readiness-and-runtime-launch.md`, `0032-flow-scoped-model-profile-allowlists.md` | Review Readiness gates runtime launch; review and task execution keep independent allowlists with lane/task scopes; complete owner pairs pass unchanged to runtime, which owns support and errors; no automatic fallback |
+| Shared testbox agent workspace | superseded | 历史；运行入口已退役 | shared-testbox-heavy-validation/SPEC.md | agent-vm/SPEC.md | 原共享宿主模型的历史事实 |
+| XP Infra public hostname convention | active | 已实现 | `xp-infra-public-hostname-convention/SPEC.md` | - | 固定标准公网节点的成对 hostname，并由只读 audit 检测 drift |
+| Fresh thread dispatch | active | 已实现 | `fresh-thread-dispatch/SPEC.md` | - | 显式新 Codex task 的模型、环境、紧凑 handoff 与工具边界；flow-owned lock 和完整 owner pair 原样交给 runtime，不做 flow-level fallback |
+| Parallel direct PR flow | superseded | 历史 | `parallel-pr-flow/SPEC.md` | - | 历史并行协调契约，已退役 |
+| Empirical acceptance review gate | active | 部分完成 (3/4) | `empirical-acceptance-review-gate/SPEC.md` | - | 对无法由确定性本地验证证明的外部行为，绑定 Candidate、验收合同和经验性证据，并在回归时停止普通 review/fix 收敛 |
+| Code Hosting Platform Boundary | active | 已实现 | `code-hosting-platform/SPEC.md` | - | GitHub 与自托管 Gitea 控制面、精确 SHA 安全语义及四字段 CI facts envelope |
+| Native Incus Agent VM | active | 协议 4 在线内存调整与 48 GiB 额度候选待验收；既有回收已验收 | agent-vm/SPEC.md | - | 显式租约、原生 NAT 与懒释放 |
+| Release Tracking | active | 部分完成 | `release-tracking/SPEC.md` | - | 专用角色、完整发布链、有限自动恢复与安全单次重跑；运行时验收另行核实 |
+| mcu-agentd 集成清退 | active | 已实现 | `mcu-agentd-retirement/SPEC.md` | - | 三个受维护源头均已清退；不规定或迁移各项目工具 |
+| Multi-task flow | active | 已实现 | `multi-task-flow/SPEC.md` | [0035](../adr/0035-task-orchestration-ledger.md), [0040](../adr/0040-dev-plan-standalone-typescript-finalizer.md) | 独立任务依赖、单编排账本、动态父 PR 和只读实时视图；不绑定 dev-plan |
+| Dev-plan standalone TypeScript finalizer | active | 已实现 | `dev-plan-standalone-typescript-finalizer/SPEC.md` | - | dev-plan 独立校验与投影、TypeScript 唯一实现、仅保留安全启动 launcher |

package/toolkit/skills/docs/vendor/dot-codex/specs/a4ge9-stable-preview-runtime/HISTORY.md

@@ -0,0 +1,24 @@
+# Native background preview handoff guard 演进历史（#a4ge9）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `ae26703` fix(workflow): tighten native preview handoff guard
+- `b39a914` docs(specs): adopt topic-level spec model
+- Dashboard wrapper lease lifecycle and host-native session responsibility are now explicit in the topic contract.
+- Heartbeat ownership now separates first PID binding from expected-owner validation, preserving compatibility while protecting replacement leases.
+- Startup registration now claims the inspected lease state under the registry lock before updating PID/session metadata.
+- The wrapper completes that claim before binding its HTTP listener, so a rejected claim never briefly occupies the preview port.
+- The wrapper now holds the registry lock through listener binding, records PID only after confirmation, and rejects duplicate startup without replacing the active owner.
+- Startup cleanup now captures the listener handle before post-bind verification or lease persistence, so failed claims stop the newly bound service.
+
+## Legacy Change Log
+
+- No legacy change-log section was recorded for this spec.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#a4ge9`.

package/toolkit/skills/docs/vendor/dot-codex/specs/a4ge9-stable-preview-runtime/IMPLEMENTATION.md

@@ -0,0 +1,66 @@
+# Native background preview handoff guard 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 为 owner-facing localhost handoff 收紧 native-background 契约，并补 pid-backed lease 自愈
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-04-13
+- Legacy last-tracked: 2026-04-13
+- Current lifecycle: active
+- Catalog note: 为 owner-facing localhost handoff 收紧 native-background 契约，并补 pid-backed lease 自愈
+
+## Delivery Milestones
+
+- [x] M1: 建立 spec 与 canonical solution 骨架
+- [x] M2: 为 stable lease 增加即时 stale cleanup 与单测
+- [x] M3: 收紧 AGENTS / skills handoff 契约并完成本地验证
+- [x] M4: 确认方案保持为 Codex 原生后台能力，不新增 repo 内 detached runtime
+- [x] M5: 让 dashboard wrapper 自理 PID/租约生命周期，并明确宿主 Agent 负责 native background session
+- [x] M6: 分离 heartbeat 的 PID 补登记与 expected-pid 所有权校验，锁内 claim 启动租约，并补齐替代 lease 回归测试
+- [x] M7: 在绑定 dashboard listener 前完成 guarded lease claim
+- [x] M8: 在同一 registry 锁内完成 listener bind 与 PID 登记，并拒绝重复启动
+- [x] M9: 在 claim 提交失败时复用已绑定 listener 的清理句柄
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `AGENTS.md`
+- `skills/global-port-manager/SKILL.md`
+- `skills/storybook-stories/SKILL.md`
+- `docs/solutions/workflow-issues/stable-preview-handoff-runtime.md`
+- `skills/multi-task-flow/scripts/serve.ts`
+- `skills/multi-task-flow/tests/serve.test.ts`
+- `bin/modules/workspace/port_registry.ts`
+- `bin/modules/workspace/port_registry_cli.ts`
+- `bin/tests/workspace/workspace.test.ts`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `ae26703` fix(workflow): tighten native preview handoff guard
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/a4ge9-stable-preview-runtime/SPEC.md

@@ -0,0 +1,175 @@
+# Native background preview handoff guard
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## Context and Scope
+
+This topic governs owner-facing localhost preview handoff, the dashboard service wrapper's own lease lifecycle, and the boundary between repository Skills and Codex host-native background sessions. It does not add a repository-local detached service manager or change Codex host capabilities.
+
+## Requirements
+
+### REQ-PREVIEW-001
+
+- An owner-facing localhost URL MUST have a matching active port lease and a still-retained Codex native background session owned by the current workspace.
+
+### REQ-PREVIEW-002
+
+- The dashboard wrapper MUST validate and claim the inspected lease before binding, record its own PID, heartbeat its service lease while running and release only that service lease during shutdown; claim, heartbeat and release MUST verify the inspected port and expected PID state so a replaced lease is left untouched. The registry MUST distinguish the PID being recorded from an expected owner PID so a first binding may require an empty PID without weakening replacement protection.
+
+### REQ-PREVIEW-003
+
+- The Agent/host MUST create and retain the native background session. The Skill MUST NOT create, infer or substitute a visible terminal or foreground exec session; without a supported host route, handoff MUST be blocked.
+
+## Verification
+
+### VER-PREVIEW-001
+
+- Method: Lease and service-wrapper integration tests.
+- covers: REQ-PREVIEW-001, REQ-PREVIEW-002
+- Pass condition: A running dashboard is bound to the matching lease, records its PID/session metadata, executes a guarded heartbeat and releases only its own service lease on signal; registry tests cover first PID binding and same-port PID replacement rejection.
+
+### VER-PREVIEW-002
+
+- Method: Skill and Agent contract review.
+- covers: REQ-PREVIEW-003
+- Pass condition: The documented host/Agent boundary rejects visible-terminal or foreground-exec substitution and reports missing host background support as a handoff blocker.
+
+## Related ADRs
+
+None
+
+## 背景 / 问题陈述
+
+- `docs/specs/retire-legacy-service-manager/SPEC.md` 退役 `devctl/zellij` 之后，当前全局契约已经明确回到 Codex native background terminals，但 owner-facing localhost handoff 这条语义仍然不够收紧。
+- session `019d8091-9ee8-7882-b386-17304fca9830` 暴露出反例：agent 把 `session_id=19097` 持有的预览 `http://localhost:30060` 交给主人，随后又显式 `Ctrl-C` 停掉该会话，导致交付地址立即失效。
+- 当前 `leases.tsv` 还能保留大量 `pid/agent_session` 为空且端口已不再监听的租约，说明端口治理仍需要更快的 stale 自愈；但这不等于应该在 repo 内重新引入新的服务托管层。
+- 当前仓库能够负责 dashboard/service wrapper 自身的 PID 与租约生命周期，但不能替 Codex host 创建或证明 native background session；没有宿主支持时不得把可见终端或前台 exec 当成隐藏后台会话。
+
+## 目标 / 非目标
+
+### Goals
+
+- 明确区分 `live exec preview`（仅当前 turn/browser 验证）与 `native background handoff preview`（允许给主人交付 URL）。
+- 保持 owner-facing localhost handoff 继续依赖 Codex 原生后台能力，而不是新增 repo 内 detached runtime。
+- 让 `$global-port-manager` 对带 `pid` 的 lease 支持即时自愈，不再只依赖 24h TTL。
+- 让 `AGENTS.md`、`$global-port-manager`、`$storybook-stories` 使用一致契约。
+- 补自动化回归，覆盖 stale lease 自愈与错误 handoff 语义。
+
+### Non-goals
+
+- 不恢复 `devctl`、zellij、launchd 或其它旧服务托管栈。
+- 不新增 `stable_service.py` 之类的 repo 内 detached service manager。
+- 不调整 `config.toml` 的模型/provider/MCP 选择。
+- 不一次性接管所有后台 daemon；本次只治理 owner-facing 本地预览 handoff 语义与租约自愈。
+
+## 范围（Scope）
+
+### In scope
+
+- 使用 `skills/global-port-manager/scripts/port_registry.ts` 提供带 `pid` lease 的即时 stale cleanup。
+- 更新 `AGENTS.md`、`skills/global-port-manager/SKILL.md`、`skills/storybook-stories/SKILL.md`。
+- 新增一篇 canonical solution，沉淀 native-background preview handoff 的复用规则。
+- 更新 `docs/specs/README.md` 并登记本规格。
+- 保持 `port_registry.ts` 的单测，并覆盖 dashboard wrapper 的 PID/session 登记、心跳和退出释放。
+
+### Out of scope
+
+- repo 外已有 launchd/job/log/state 的宿主机清理。
+- 新建或恢复任何 repo 内服务托管脚本。
+- 远端 PR / push / merge。
+
+## 需求（Requirements）
+
+### MUST
+
+- owner-facing localhost URL 不得再依赖 repo 内自管 detached runtime；必须继续依赖 Codex 原生后台会话。
+- `live exec preview` 仍可用于当前 turn 内浏览器复现，但不得再作为最终 handoff URL。
+- owner-facing localhost handoff 必须满足：当前端口租约归属匹配，并且该服务仍由当前工作区的 Codex 原生后台会话持有；若运行时可得，lease 中还应记录对应 `agent_session`。
+- `port_registry.ts` 在 `inspect/register/allocate/heartbeat/gc` 路径上，遇到带 `pid` 的 lease 进程已死或端口已不监听时，必须即时清理。
+- dashboard wrapper 必须在 registry 锁内原子 claim 预分配 lease，拒绝已有 PID 或已监听端口的重复启动，持锁绑定 listener，并只在 listener 确认后登记自身 PID；不得用独立的 inspect/register 覆盖活跃 owner。
+- Agent/host 负责创建和保留 native background session；Skill 只登记宿主实际提供的 `agent_session`，不创建、推断或替代该会话。没有受支持的宿主后台路径时，owner-facing handoff 必须阻塞。
+- 相关 skills/AGENTS 文本必须显式区分 live preview 与 native-background handoff preview。
+
+### SHOULD
+
+- 文本契约应说明：交付给主人后的同一路径不得在同 run 内被 agent 自己 `Ctrl-C` / release。
+- 对没有 `pid` 的历史租约，继续保留旧 TTL 规则，而不是激进回收。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- `live exec preview`
+  - 当前 turn 为了浏览器验证可以使用前台 exec 或短生命周期会话。
+  - 这种地址只能用于本回合内部验证，不得作为最终 handoff URL。
+- `native background handoff preview`
+  - 服务必须由当前工作区的 Codex 原生后台会话持有。
+  - Agent 必须从 Codex host 获取并保留该会话；Skill 不得用可见终端、前台 exec 或服务 PID 猜测它。
+  - 交付给主人前，agent 必须确认端口属于当前 lease，并保留该后台会话，不得在同一路径上立刻 `Ctrl-C`。
+  - 若运行时能提供 `agent_session`，应把它注册到 lease，作为 provenance 补强证据。
+- `port_registry.ts`
+  - 对带 `pid` 的 lease 做即时 stale cleanup：`pid` 已死或端口已不监听时，立刻移除。
+  - 对没有 `pid` 的旧 row 维持 `24h + port-not-listening` 的 TTL 规则。
+  - heartbeat 将待记录的 `pid` 与 `expected-pid` 所有权 guard 分离：空 PID 可首次绑定，已有 PID 不匹配时拒绝更新。
+  - wrapper 的 startup claim 与 listener bind 在同一 registry 锁内完成，避免 PID 写入早于 listener 或重复启动覆盖 owner。
+
+### Edge cases / errors
+
+- 若只有前台 live exec 持有预览，即便当前端口租约正确，也不能把它当成 owner-facing handoff。
+- 若 owner-facing handoff 后，agent 又主动停止对应的原生后台会话，这属于明确违约。
+- 若 runtime 提供不了 `agent_session`，仍至少要满足“当前 lease 归属 + 当前工作区启动 + 原生后台会话仍存活”三项事实。
+- 若 Codex host 没有可供 Agent 保留的 native background route，不能通过打开可见终端或维持前台 exec 来满足 handoff；该 URL 只能用于当前回合验证。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+- `skills/global-port-manager/scripts/port_registry.ts`
+
+### 契约文档（按 Kind 拆分）
+
+- owner-facing localhost handoff 前置条件：当前 lease 归属匹配 + 当前工作区的 Codex 原生后台会话仍持有该服务。
+- `live exec preview` 与 `native background handoff preview` 的行为差异，由 `AGENTS.md` + skills 文本共同定义；不靠口头约定。
+
+## 验收标准（Acceptance Criteria）
+
+- Given 只有 live exec session 维持的本地预览 When agent 准备把该 URL 作为最终 handoff 交给主人 Then 契约必须判定为不合规，需要改用 Codex 原生后台会话持有该服务。
+
+- Given 一个通过当前工作区 Codex 原生后台会话持有的本地 HTTP 服务，且端口租约归当前 scope/service When agent 准备把该 URL 交给主人 Then 该 URL 可以被视为合法 handoff 来源，但 agent 不得在同 run 内主动停止该后台会话。
+
+- Given 一个最近刚写入、但 `pid` 已死亡且端口不再监听的 lease When 对该 scope/service 执行 `inspect` 或 `register` Then stale row 会被即时清理，不必等 24h TTL。
+
+- Given session `019d8091` 的等价路径 When 先拉起 live exec preview，再结束该 exec Then 旧 URL 不再被视为可交付；只有改由 Codex 原生后台会话持有后才允许 handoff。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `bun test skills/global-port-manager/scripts/test_port_registry.ts`
+- `bun test skills/multi-task-flow/tests/serve.test.ts`
+- `git diff --check`
+
+### Quality checks
+
+- spot-check `AGENTS.md`、`skills/global-port-manager/SKILL.md`、`skills/storybook-stories/SKILL.md` 的 live/native-background 语义是否一致。
+- 确认 repo 中不存在新的 detached preview runtime 脚本。
+
+## 方案概述（Approach, high-level）
+
+- 不回滚到旧 zellij 栈，也不在 repo 内新建 detached service manager。
+- 继续把 Codex native background terminals 作为 owner-facing localhost handoff 的唯一后台能力来源。
+- 端口租约继续是归属真相源；`pid` 仅用于 registry 自愈，dashboard wrapper 只管理自身 service lease，不作为引入新运行时的理由。
+- 文本契约负责明确“什么时候必须升级成 native background handoff”；真正的后台生命周期仍由 Codex 原生能力负责。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：当前 repo 只能收紧契约、维护自身 service lease 并验证宿主传入的事实，无法直接替 Codex runtime 增加新的后台观测接口。
+- 风险：仍有历史 lease 缺少 `pid` / `agent_session`，本次不会立刻把它们全部清走。
+- 假设：Codex 原生后台能力会继续存在，并且 owner-facing handoff 可以依赖它而不是 repo 内守护进程。
+
+## 参考（References）
+
+- `docs/specs/retire-legacy-service-manager/SPEC.md`
+- `docs/specs/global-port-preview-governance/SPEC.md`
+- `docs/solutions/workflow-issues/stable-preview-handoff-runtime.md`
+- `sessions/2026/04/12/rollout-2026-04-12T15-22-00-019d8091-9ee8-7882-b386-17304fca9830.jsonl`

package/toolkit/skills/docs/vendor/dot-codex/specs/active-long-task-ownership-wait-guard/HISTORY.md

@@ -0,0 +1,20 @@
+# 长任务 ownership 与等待语义守卫 演进历史（#zmp5f）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- 长任务 ownership 增加 execution receipt 预算：输出截断不触发重跑，相同输入只允许一次有状态证据的 transient retry。
+
+- `61bac95` fix(workflow): guard active long-task ownership waits
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- No legacy change-log section was recorded for this spec.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#zmp5f`.

package/toolkit/skills/docs/vendor/dot-codex/specs/active-long-task-ownership-wait-guard/IMPLEMENTATION.md

@@ -0,0 +1,64 @@
+# 长任务 ownership 与等待语义守卫 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 收紧 live 长任务的 ownership promise、停靠语义与 focused replay 守卫
+- Receipt budget coverage: 本地命令默认 1800 秒、一次 transient retry、内层预算继承已进入 shared contract。
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-04-08
+- Legacy last-tracked: 2026-04-08
+- Current lifecycle: active
+- Catalog note: 收紧 live 长任务的 ownership promise、停靠语义与 focused replay 守卫
+
+## Delivery Milestones
+
+- [x] M1: 建立规格、shared long-task contract 与索引登记
+- [x] M2: 收紧 `AGENTS.md`、`$flow-continue`、shared workflow、`$codex-review-loop` 与共享摘要口径
+- [x] M3: 新增 focused replay checker 与最小化 replay fixtures
+- [x] M4: 跑本地检查并收口到可继续 local-merge handoff
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `docs/specs/active-long-task-ownership-wait-guard/SPEC.md`
+- `AGENTS.md`
+- `skills/README.md`
+- `skills/project-engineering-workflow/references/active-long-task-short-contract.md`
+- `skills/project-engineering-workflow/references/pr-diagnosis-short-contract.md`
+- `skills/project-engineering-workflow/references/review-proof-short-contract.md`
+- `skills/flow-continue/SKILL.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/codex-review-loop/SKILL.md`
+- `bin/active_long_task_replay_check.py`
+- `docs/specs/active-long-task-ownership-wait-guard/replay/*`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `61bac95` fix(workflow): guard active long-task ownership waits
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/active-long-task-ownership-wait-guard/SPEC.md

@@ -0,0 +1,154 @@
+# 长任务 ownership 与等待语义守卫
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- session `019d686e-a52e-7f30-8efa-d88fd784f327` 与 `019d681b-85d0-7541-bf8e-ccc81816cdaf` 暴露出同一类编排缺口：assistant 已明确承诺“继续盯着 / 继续 relay-poll”，但 live 长任务仍未终态时却提前结束回合，迫使主人再补“继续 / 盯着 / 你自己处理”这类无信息消息。
+- 现有 `docs/specs/pr-wait-state-closeout/SPEC.md`、`docs/specs/review-proof-ownership/SPEC.md`、`docs/specs/review-proof-dedupe-wait-guard/SPEC.md`、`docs/specs/fast-track-merge-intent-closeout/SPEC.md` 已经把 PR `外部门禁等待态` 与 `active review proof` 的专用等待语义收紧了，但缺少一个更高层、可复用的 generic 长任务 ownership 契约，无法覆盖普通 exec/browser/test/job 场景，也没有把“口头承诺继续、实际提前停下”统一定义成不合格行为。
+- 当前相关口径分散在 `AGENTS.md`、`$flow-continue`、shared workflow、`$codex-review-loop` 与已有短规约之间。partial-read 场景下，agent 仍可能只抓到局部规则，把“下一步很明确、只是继续等”错误当成合法停靠点。
+
+## 目标 / 非目标
+
+### Goals
+
+- 明确 generic `active long task` 的共享契约：定义、`ownership promise`、合法停靠原因、默认轮询节奏，以及 generic continuation 的恢复语义。
+- 规定：只要 live 长任务的下一步仍然只是 poll / relay / wait / 同路径重试，且不需要主人新的决定或授权，就必须在同一 turn 内继续推进。
+- 让 `AGENTS.md`、`$flow-continue`、`$project-engineering-workflow`、`$codex-review-loop` 统一引用同一套口径，而不是各自散写一段“继续盯着”的语义。
+- 新增 focused replay checker，直接覆盖这两条 cited sessions 对应的两种事故：`active review proof` 提前停靠、普通 live exec/task 提前停靠。
+
+### Non-goals
+
+- 不修改 Codex runtime / Desktop 的底层 turn 管理或通知逻辑。
+- 不扩到更广的浏览器 consumer 面。
+- 不把所有历史 session 全量变成通用大回放框架；本次只做 focused replay guard。
+
+## 范围（Scope）
+
+### In scope
+
+- 更新 `docs/specs/README.md` 与本规格。
+- 新增 shared `active long task` 短规约。
+- 更新 `AGENTS.md`、`skills/README.md`、`$flow-continue`、`$project-engineering-workflow`、`$codex-review-loop`，并在需要时补 shared contract 交叉引用。
+- 新增 focused replay checker 与最小化 replay fixtures / cases。
+
+### Out of scope
+
+- 修改 `config.toml` 或其他与本问题无关的本地配置。
+- 修改 `gh CLI` 远端控制面或 browser MCP 行为。
+- 为所有 skill 入口重新发明一套独立等待预算系统。
+
+## 需求（Requirements）
+
+### MUST
+
+- shared contract 必须定义 `active long task`，至少覆盖 exec session、浏览器自动化、测试/构建、远端 job 与 `active review proof`。
+- shared contract 必须定义 `ownership promise`：只要 assistant 已表达“我继续盯着 / 正在跑 / 我等它收口 / 我继续 relay-poll / 我不切走”或等价语义，就视为已接管该 live task。
+- 若当前 live task 的唯一下一动作仍是继续 poll / relay / wait / 同路径重试，且不存在终态、新 blocker、主人决策/授权，或对应短规约允许的 `等待预算耗尽`，则不得结束当前 turn。
+- 主人不得被迫通过“继续 / 盯着 / 别停 / 你自己处理”这类无信息消息来恢复本应自动继续的 live task。
+- `等待预算耗尽` 只能在对应短规约允许的等待态里作为合法停靠原因；`active review proof` 达到 `startup_success` 后不得借此伪装停靠。
+- `$flow-continue` 必须把 `ownership promise` 绑定的 live task 纳入恢复优先级；generic `继续` 只能先续接该 live task，不得重开新路径或改路由。
+- focused replay checker 至少支持 finding：`LONG_TASK_OWNERSHIP_LEAK`。
+- focused replay checker 必须至少覆盖两类负例：
+  - `019d681b` 型：`active review proof` 仍 live，assistant 说“继续 relay/poll”，但仍提前停下；
+  - `019d686e` 型：普通 live exec/task 仍 live，assistant 说“继续盯着 / 等它收口”，但仍提前停下。
+- 本地命令默认硬预算为 30 分钟；只有仓库显式声明的 known-long 命令可以覆盖。相同 effective inputs 只允许一次由可观察状态变化证明的 transient retry，output truncation 或 compaction 不构成 retry 依据。
+- 内层 skill 必须继承外层剩余预算，不得重新开始计时；预算耗尽必须记录终态并报告 blocker，不得通过同路径重启伪装继续。
+
+### SHOULD
+
+- 关键 consumer 文件的前 120-150 行就能看到 shared contract 引用和 stop prohibition。
+- focused replay fixtures 应以 cited sessions 的最小化提炼片段为主，而不是依赖超大原始 session 文件。
+
+## 功能与行为规格（Functional / Behavior Spec）
+
+### Shared active-long-task contract
+
+- 新 contract 统一承担六类判断：
+  - `active long task` 定义
+  - `ownership promise` 识别
+  - generic stop prohibition
+  - 合法停靠原因
+  - 默认轮询节奏
+  - generic continuation 的恢复语义
+- PR `外部门禁等待态` 与 `active review proof` 继续沿用各自专用 contract / budget；shared long-task contract 只做上层 ownership guard，不推翻专用生命周期规则。
+- execution receipt 保存命令 identity、effective-input fingerprint、退出码、日志路径、预算与 retry 计数；是否需要重跑由 receipt classification 决定，而不是由终端是否仍保留完整输出决定。
+
+### Consumer integration
+
+- `AGENTS.md`
+  - 前置 repo 级硬规则，禁止把“继续等待同一 live task”的责任泄给主人。
+- `skills/README.md`
+  - 顶部共享摘要增加一条 generic guardrail，避免 partial-read 只读到 Step 5 旧语义。
+- `$project-engineering-workflow`
+  - 新增 shared long-task contract 引用，并在流程恢复语义与 `外部门禁等待态` 章节明确：generic live-task ownership 与 PR 专用 wait-state/budget 是分层关系。
+- `$flow-continue`
+  - 恢复顺序显式覆盖 `ownership promise` 绑定的 live task。
+  - generic `继续 / 盯着 / 你自己处理` 若只是在补一个 no-op 恢复，不得被解释成新的路由或新的授权。
+- `$codex-review-loop`
+  - live proof 进入 relay/poll 后，不能再用“我继续盯着”当成合法收口语句；只能继续轮询，或按 shared / proof contract 命中合法停靠原因。
+
+### Focused replay checker
+
+- checker 读取最小化 replay JSONL，至少提取：
+  - assistant / user message 文本
+  - `Process running with session ID <n>` 这类 live exec 证据
+  - `Process exited with code` / `Unknown process id` / `stdin closed` 等 terminal evidence
+  - assistant 是否输出 `ownership promise`
+  - user 是否发出 generic `继续 / 盯着 / 你自己处理`
+- 负例判定：若 assistant 已形成 `ownership promise`，live task 仍未终态，且没有新 blocker / 主人决策 / `等待预算耗尽`，随后却需要 user 的 generic continue 才恢复，则报 `LONG_TASK_OWNERSHIP_LEAK`。
+- 正例判定：若在 user generic continue 之前，task 已终态，或 assistant 已明确按契约说明 `等待预算耗尽` / 需要主人决策，则不得误报。
+
+## 验收标准（Acceptance Criteria）
+
+- Given 最小化 replay `negative-019d681b-active-proof-owner-leak.jsonl` When 跑 focused replay checker Then 必须报出 `LONG_TASK_OWNERSHIP_LEAK`。
+
+- Given 最小化 replay `negative-019d686e-live-exec-owner-leak.jsonl` When 跑 focused replay checker Then 必须报出 `LONG_TASK_OWNERSHIP_LEAK`。
+
+- Given assistant 只说“正在跑”这类 contract 已列明的 ownership promise When 随后仍需要 user 发 generic continue 才恢复 Then 也必须报出 `LONG_TASK_OWNERSHIP_LEAK`。
+
+- Given assistant 在多 live session 下对“当前焦点 session”作出继续承诺 When 那个焦点 session 仍 live 且随后需要 user generic continue 才恢复 Then checker 也必须报出 `LONG_TASK_OWNERSHIP_LEAK`。
+
+- Given 最小化 replay `positive-terminal-before-user-nudge.jsonl` When 跑 focused replay checker Then 不得误报 `LONG_TASK_OWNERSHIP_LEAK`。
+
+- Given promise 绑定的原 live session 已终态，但另一个无关 session 仍在运行 When user 发送 generic continue Then 不得误报 `LONG_TASK_OWNERSHIP_LEAK`。
+
+- Given user 的后续消息包含新的授权或改路由输入，而不只是 no-op 续推 When 跑 focused replay checker Then 不得把这条消息误判成泄漏触发器。
+
+- Given user 的后续消息虽然含有“继续”，但同时追加了新的具体请求 When 跑 focused replay checker Then 不得把它误判成 generic no-op nudge。
+
+- Given assistant 承诺继续的是 review proof，而另一条无关 exec session 同时 live When 该 proof 已终态、只剩无关 session 仍在运行 Then checker 不得把无关 session 误绑定到原 promise 上。
+
+- Given assistant 承诺继续的是当前焦点 proof，且另一个 proof 同时 live When 当前焦点 proof 已终态、只剩另一条 proof 仍在运行 Then checker 不得把 promise 漂移到另一条 proof 上。
+
+- Given `AGENTS.md`、`$flow-continue`、`$project-engineering-workflow`、`$codex-review-loop` 的顶部片段 When 只读前 120-150 行 Then 应能看到 shared long-task contract 引用或等价硬规则，并明确禁止“口头承诺继续、实际提前停下”。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `python3 -m py_compile bin/active_long_task_replay_check.py`
+- `python3 bin/active_long_task_replay_check.py --cases docs/specs/active-long-task-ownership-wait-guard/replay/cases.txt`
+- `python3 bin/review_proof_replay_check.py --cases docs/specs/review-proof-dedupe-wait-guard/replay/cases.txt`
+- `python3 bin/flow_continue_replay_check.py --cases docs/specs/flow-continue-lock-guard/replay/cases.txt`
+- `git diff --check`
+
+### Quality checks
+
+- 目标 consumer 的前 120-150 行人工 spot-check
+- grep 交叉检查：`ownership promise`、`等待预算耗尽`、`active long task` 的口径一致
+
+## 风险 / 假设
+
+- 风险：focused checker 依赖 replay 中可观测的 message / exec-session 证据，因此它是 focused guard，不是 runtime 全量真相源。
+- 风险：未来若新增新的长任务 consumer 但不引用 shared contract，partial-read 漂移仍可能复发。
+- 假设：本次最值得防回归的是“ownership promise 泄漏 + 需要主人补 no-op 继续”，因此 focused replay 只覆盖这两条 cited sessions 对应的事故族即可。
+
+## 参考（References）
+
+- Session `019d686e-a52e-7f30-8efa-d88fd784f327`
+- Session `019d681b-85d0-7541-bf8e-ccc81816cdaf`
+- `docs/specs/pr-wait-state-closeout/SPEC.md`
+- `docs/specs/review-proof-ownership/SPEC.md`
+- `docs/specs/review-proof-dedupe-wait-guard/SPEC.md`
+- `docs/specs/fast-track-merge-intent-closeout/SPEC.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/active-long-task-ownership-wait-guard/replay/cases.txt

@@ -0,0 +1,11 @@
+# status path expected_code
+fail negative-019d681b-active-proof-owner-leak.jsonl LONG_TASK_OWNERSHIP_LEAK
+fail negative-019d686e-live-exec-owner-leak.jsonl LONG_TASK_OWNERSHIP_LEAK
+fail negative-running-status-alone-owner-leak.jsonl LONG_TASK_OWNERSHIP_LEAK
+fail negative-focused-session-still-live-owner-leak.jsonl LONG_TASK_OWNERSHIP_LEAK
+pass positive-terminal-before-user-nudge.jsonl -
+pass positive-promised-session-exited-before-user-nudge.jsonl -
+pass positive-continue-with-new-owner-input.jsonl -
+pass positive-review-promise-does-not-bind-unrelated-live-session.jsonl -
+pass positive-focused-proof-exits-before-user-nudge.jsonl -
+pass positive-continue-with-extra-request.jsonl -