cool-workflow 0.1.97 → 0.2.0

package/docs/project-index.md

@@ -1,15 +1,15 @@
 # Cool Workflow Project Index
 
-Generated from the current repository code on 2026-06-30 by `npm run sync:project-index`.
+Generated from the current repository code on 2026-07-05 by `npm run sync:project-index`.
 
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.1.97`
-- Source modules: `68`
+- Version: `0.2.0`
+- Source modules: `129`
 - Workflow apps: `8`
-- Docs: `59`
-- Smoke tests: `164`
+- Docs: `61`
+- Smoke tests: `173`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -29,40 +29,40 @@ multi-agent host -> topology -> blackboard/coordinator
 
 | Module | Responsibility |
 | --- | --- |
-| [orchestrator.ts](../src/orchestrator.ts) | Plans runs, loads workflows, records results, writes reports, and exposes runner commands. |
-| [state.ts](../src/state.ts) | Persists run checkpoints, JSON state, run paths, and state migration entrypoints. |
-| [state-node.ts](../src/state-node.ts) | Defines explicit state nodes, pipeline transitions, evidence checks, and node persistence. |
-| [pipeline-contract.ts](../src/pipeline-contract.ts) | Builds the default pipeline contract used by run state. |
-| [pipeline-runner.ts](../src/pipeline-runner.ts) | Finds runnable stages and advances/fails pipeline nodes with retry-aware errors. |
-| [types.ts](../src/types.ts) | Owns the shared workflow, run, app, evidence, worker, candidate, audit, and topology types. |
+| [shell/orchestrator.ts](../src/shell/orchestrator.ts) | Plans runs, loads workflows, records results, writes reports, and exposes runner commands (a thin facade over the shell functions below). |
+| [shell/run-store.ts](../src/shell/run-store.ts) | Persists run checkpoints, JSON state, run paths, and state migration entrypoints. |
+| [core/state/state-node.ts](../src/core/state/state-node.ts) | Defines explicit state nodes, pipeline transitions, evidence checks, and node persistence. |
+| [core/pipeline/contract.ts](../src/core/pipeline/contract.ts) | Builds the default pipeline contract used by run state. |
+| [core/pipeline/runner.ts](../src/core/pipeline/runner.ts) | Finds runnable stages and advances/fails pipeline nodes with retry-aware errors. |
+| [core/state/types.ts](../src/core/state/types.ts) | Owns the shared run/state types: WorkflowRun and everything it carries, StateNode, and the pipeline contract shape. |
 
 ### Verification and state gates
 
 | Module | Responsibility |
 | --- | --- |
-| [verifier.ts](../src/verifier.ts) | Validates result envelopes, findings, evidence, and run gate completion. |
-| [commit.ts](../src/commit.ts) | Creates verifier-gated commits and explicit manual checkpoints. |
-| [candidate-scoring.ts](../src/candidate-scoring.ts) | Registers, scores, ranks, selects, rejects, and summarizes candidate outputs. |
-| [error-feedback.ts](../src/error-feedback.ts) | Turns failures into persisted feedback records and correction tasks. |
-| [trust-audit.ts](../src/trust-audit.ts) | Records provenance, sandbox decisions, host attestations, and acceptance rationale. |
+| [shell/verifier.ts](../src/shell/verifier.ts) | Validates result envelopes, findings, evidence, and run gate completion. |
+| [shell/commit.ts](../src/shell/commit.ts) | Creates verifier-gated commits and explicit manual checkpoints. |
+| [core/multi-agent/candidate-scoring.ts](../src/core/multi-agent/candidate-scoring.ts) | Registers, scores, ranks, selects, rejects, and summarizes candidate outputs. |
+| [core/pipeline/error-feedback.ts](../src/core/pipeline/error-feedback.ts) | Turns failures into persisted feedback records and correction tasks. |
+| [shell/trust-audit.ts](../src/shell/trust-audit.ts) | Records provenance, sandbox decisions, host attestations, and acceptance rationale. |
 
 ### Workers and policy
 
 | Module | Responsibility |
 | --- | --- |
-| [dispatch.ts](../src/dispatch.ts) | Selects runnable tasks and writes dispatch manifests. |
-| [worker-isolation.ts](../src/worker-isolation.ts) | Allocates worker scopes, writes manifests, records worker outputs, and validates boundaries. |
-| [sandbox-profile.ts](../src/sandbox-profile.ts) | Resolves named sandbox policy contracts and validates read/write/command/network boundaries. |
-| [harness.ts](../src/harness.ts) | Renders task files for dispatched work. |
+| [shell/dispatch.ts](../src/shell/dispatch.ts) | Selects runnable tasks and writes dispatch manifests. |
+| [shell/worker-isolation.ts](../src/shell/worker-isolation.ts) | Allocates worker scopes, writes manifests, records worker outputs, and validates boundaries. |
+| [shell/sandbox-profile.ts](../src/shell/sandbox-profile.ts) | Resolves named sandbox policy contracts and validates read/write/command/network boundaries. |
+| [shell/harness.ts](../src/shell/harness.ts) | Renders task files for dispatched work. |
 
 ### Multi-agent layer
 
 | Module | Responsibility |
 | --- | --- |
-| [multi-agent.ts](../src/multi-agent.ts) | Persists multi-agent runs, roles, groups, memberships, fanouts, and fanins. |
-| [coordinator.ts](../src/coordinator.ts) | Owns blackboard topics, messages, context, artifacts, snapshots, and coordinator decisions. |
-| [topology.ts](../src/topology.ts) | Defines and applies official map-reduce, debate, and judge-panel topologies. |
-| [multi-agent-host.ts](../src/multi-agent-host.ts) | Provides the preferred host loop for run, status, step, blackboard, score, and select. |
+| [core/multi-agent/runtime.ts](../src/core/multi-agent/runtime.ts) | Persists multi-agent runs, roles, groups, memberships, fanouts, and fanins. |
+| [core/multi-agent/coordinator.ts](../src/core/multi-agent/coordinator.ts) | Owns blackboard topics, messages, context, artifacts, snapshots, and coordinator decisions. |
+| [core/multi-agent/topology.ts](../src/core/multi-agent/topology.ts) | Defines and applies official map-reduce, debate, and judge-panel topologies. |
+| [shell/multi-agent-host.ts](../src/shell/multi-agent-host.ts) | Provides the preferred host loop for run, status, step, blackboard, score, and select. |
 
 ### User and host surfaces
 
@@ -70,56 +70,117 @@ multi-agent host -> topology -> blackboard/coordinator
 | --- | --- |
 | [cli.ts](../src/cli.ts) | Routes human CLI commands to runtime, app, topology, multi-agent, and operator flows. |
 | [mcp-server.ts](../src/mcp-server.ts) | Exposes JSON-RPC/MCP tool parity for agent hosts. |
-| [operator-ux.ts](../src/operator-ux.ts) | Formats status, reports, graph, worker, candidate, feedback, commit, and trust summaries. |
-| [workflow-app-framework.ts](../src/workflow-app-framework.ts) | Validates app manifests and loads app entrypoints. |
-| [workflow-api.ts](../src/workflow-api.ts) | Provides the fluent workflow, phase, task, artifact, and input API. |
-| [daemon.ts](../src/daemon.ts) | Runs scheduled tasks through the desktop scheduler daemon. |
-| [scheduler.ts](../src/scheduler.ts) | Creates, stores, computes, and runs schedules. |
-| [triggers.ts](../src/triggers.ts) | Bridges routine triggers to explicit workflow events. |
-| [version.ts](../src/version.ts) | Defines current package and state schema versions. |
+| [shell/operator-ux.ts](../src/shell/operator-ux.ts) | Formats status, reports, graph, worker, candidate, feedback, commit, and trust summaries. |
+| [shell/workflow-app-loader.ts](../src/shell/workflow-app-loader.ts) | Validates app manifests and loads app entrypoints. |
+| [core/workflow-apps/app-schema.ts](../src/core/workflow-apps/app-schema.ts) | Provides the fluent workflow, phase, task, artifact, and input API. |
+| [shell/scheduler-io.ts](../src/shell/scheduler-io.ts) | Runs wall-clock schedules, the desktop scheduler daemon tick, and routine triggers. |
+| [core/version.ts](../src/core/version.ts) | Defines current package and state schema versions. |
 
 ### Other Source Modules
 
-- [agent-config.ts](../src/agent-config.ts)
-- [capability-core.ts](../src/capability-core.ts)
-- [capability-registry.ts](../src/capability-registry.ts)
-- [clones.ts](../src/clones.ts)
-- [collaboration.ts](../src/collaboration.ts)
-- [compare.ts](../src/compare.ts)
-- [contract-migration.ts](../src/contract-migration.ts)
-- [doctor.ts](../src/doctor.ts)
-- [drive.ts](../src/drive.ts)
-- [evidence-grounding.ts](../src/evidence-grounding.ts)
-- [evidence-reasoning.ts](../src/evidence-reasoning.ts)
-- [execution-backend.ts](../src/execution-backend.ts)
-- [gates.ts](../src/gates.ts)
-- [loop-expansion.ts](../src/loop-expansion.ts)
-- [mcp-surface.ts](../src/mcp-surface.ts)
-- [multi-agent-eval.ts](../src/multi-agent-eval.ts)
-- [multi-agent-operator-ux.ts](../src/multi-agent-operator-ux.ts)
-- [multi-agent-trust.ts](../src/multi-agent-trust.ts)
-- [node-projection.ts](../src/node-projection.ts)
-- [node-snapshot.ts](../src/node-snapshot.ts)
-- [observability.ts](../src/observability.ts)
-- [onramp.ts](../src/onramp.ts)
-- [reclamation.ts](../src/reclamation.ts)
-- [remote-source.ts](../src/remote-source.ts)
-- [reporter.ts](../src/reporter.ts)
-- [result-normalize.ts](../src/result-normalize.ts)
-- [run-export.ts](../src/run-export.ts)
-- [run-registry.ts](../src/run-registry.ts)
-- [run-state-schema.ts](../src/run-state-schema.ts)
-- [scheduling.ts](../src/scheduling.ts)
-- [schema-validate.ts](../src/schema-validate.ts)
-- [state-explosion.ts](../src/state-explosion.ts)
-- [state-migrations.ts](../src/state-migrations.ts)
-- [telemetry-attestation.ts](../src/telemetry-attestation.ts)
-- [telemetry-demo.ts](../src/telemetry-demo.ts)
-- [telemetry-ledger.ts](../src/telemetry-ledger.ts)
-- [term.ts](../src/term.ts)
-- [validation.ts](../src/validation.ts)
-- [workbench-host.ts](../src/workbench-host.ts)
-- [workbench.ts](../src/workbench.ts)
+- [cli/dispatch.ts](../src/cli/dispatch.ts)
+- [cli/entry.ts](../src/cli/entry.ts)
+- [cli/io.ts](../src/cli/io.ts)
+- [cli/parseargv.ts](../src/cli/parseargv.ts)
+- [core/capability-table.ts](../src/core/capability-table.ts)
+- [core/format/help.ts](../src/core/format/help.ts)
+- [core/format/state-explosion-text.ts](../src/core/format/state-explosion-text.ts)
+- [core/hash.ts](../src/core/hash.ts)
+- [core/multi-agent/collaboration.ts](../src/core/multi-agent/collaboration.ts)
+- [core/multi-agent/eval-replay.ts](../src/core/multi-agent/eval-replay.ts)
+- [core/multi-agent/trust-policy.ts](../src/core/multi-agent/trust-policy.ts)
+- [core/pipeline/commit-gate.ts](../src/core/pipeline/commit-gate.ts)
+- [core/pipeline/dispatch.ts](../src/core/pipeline/dispatch.ts)
+- [core/pipeline/drive-decide.ts](../src/core/pipeline/drive-decide.ts)
+- [core/pipeline/loop-expansion.ts](../src/core/pipeline/loop-expansion.ts)
+- [core/pipeline/result-normalize.ts](../src/core/pipeline/result-normalize.ts)
+- [core/state/contract-migration.ts](../src/core/state/contract-migration.ts)
+- [core/state/migrations.ts](../src/core/state/migrations.ts)
+- [core/state/node-projection.ts](../src/core/state/node-projection.ts)
+- [core/state/node-snapshot.ts](../src/core/state/node-snapshot.ts)
+- [core/state/run-paths.ts](../src/core/state/run-paths.ts)
+- [core/state/schema-validate.ts](../src/core/state/schema-validate.ts)
+- [core/state/schema.ts](../src/core/state/schema.ts)
+- [core/state/state-explosion/digest.ts](../src/core/state/state-explosion/digest.ts)
+- [core/state/state-explosion/graph.ts](../src/core/state/state-explosion/graph.ts)
+- [core/state/state-explosion/helpers.ts](../src/core/state/state-explosion/helpers.ts)
+- [core/state/state-explosion/report.ts](../src/core/state/state-explosion/report.ts)
+- [core/state/state-explosion/size.ts](../src/core/state/state-explosion/size.ts)
+- [core/state/validation.ts](../src/core/state/validation.ts)
+- [core/trust/evidence-grounding.ts](../src/core/trust/evidence-grounding.ts)
+- [core/trust/ledger.ts](../src/core/trust/ledger.ts)
+- [core/trust/telemetry-attestation.ts](../src/core/trust/telemetry-attestation.ts)
+- [core/trust/telemetry-ledger.ts](../src/core/trust/telemetry-ledger.ts)
+- [core/types.ts](../src/core/types.ts)
+- [core/types/boundary.ts](../src/core/types/boundary.ts)
+- [mcp/dispatch.ts](../src/mcp/dispatch.ts)
+- [mcp/server.ts](../src/mcp/server.ts)
+- [shell/agent-config.ts](../src/shell/agent-config.ts)
+- [shell/app-run-cli.ts](../src/shell/app-run-cli.ts)
+- [shell/audit-cli.ts](../src/shell/audit-cli.ts)
+- [shell/audit-provenance.ts](../src/shell/audit-provenance.ts)
+- [shell/candidate-scoring-io.ts](../src/shell/candidate-scoring-io.ts)
+- [shell/collaboration-io.ts](../src/shell/collaboration-io.ts)
+- [shell/commit-summary.ts](../src/shell/commit-summary.ts)
+- [shell/coordinator-io.ts](../src/shell/coordinator-io.ts)
+- [shell/demo-cli.ts](../src/shell/demo-cli.ts)
+- [shell/doctor.ts](../src/shell/doctor.ts)
+- [shell/drive.ts](../src/shell/drive.ts)
+- [shell/error-feedback-io.ts](../src/shell/error-feedback-io.ts)
+- [shell/eval-io.ts](../src/shell/eval-io.ts)
+- [shell/eval-text.ts](../src/shell/eval-text.ts)
+- [shell/evidence-reasoning.ts](../src/shell/evidence-reasoning.ts)
+- [shell/exec-backend-cli.ts](../src/shell/exec-backend-cli.ts)
+- [shell/execution-backend/agent.ts](../src/shell/execution-backend/agent.ts)
+- [shell/execution-backend/ci.ts](../src/shell/execution-backend/ci.ts)
+- [shell/execution-backend/container.ts](../src/shell/execution-backend/container.ts)
+- [shell/execution-backend/envelopes.ts](../src/shell/execution-backend/envelopes.ts)
+- [shell/execution-backend/local.ts](../src/shell/execution-backend/local.ts)
+- [shell/execution-backend/probes.ts](../src/shell/execution-backend/probes.ts)
+- [shell/execution-backend/registry.ts](../src/shell/execution-backend/registry.ts)
+- [shell/execution-backend/remote.ts](../src/shell/execution-backend/remote.ts)
+- [shell/execution-backend/types.ts](../src/shell/execution-backend/types.ts)
+- [shell/feedback-cli.ts](../src/shell/feedback-cli.ts)
+- [shell/feedback-operations.ts](../src/shell/feedback-operations.ts)
+- [shell/fs-atomic.ts](../src/shell/fs-atomic.ts)
+- [shell/ledger-cli.ts](../src/shell/ledger-cli.ts)
+- [shell/ledger-io.ts](../src/shell/ledger-io.ts)
+- [shell/man-cli.ts](../src/shell/man-cli.ts)
+- [shell/metrics-cli.ts](../src/shell/metrics-cli.ts)
+- [shell/multi-agent-cli.ts](../src/shell/multi-agent-cli.ts)
+- [shell/multi-agent-io.ts](../src/shell/multi-agent-io.ts)
+- [shell/multi-agent-operator-ux.ts](../src/shell/multi-agent-operator-ux.ts)
+- [shell/node-store.ts](../src/shell/node-store.ts)
+- [shell/observability-format.ts](../src/shell/observability-format.ts)
+- [shell/observability-intake.ts](../src/shell/observability-intake.ts)
+- [shell/observability.ts](../src/shell/observability.ts)
+- [shell/onramp.ts](../src/shell/onramp.ts)
+- [shell/operator-ux-text.ts](../src/shell/operator-ux-text.ts)
+- [shell/pipeline-cli.ts](../src/shell/pipeline-cli.ts)
+- [shell/pipeline.ts](../src/shell/pipeline.ts)
+- [shell/reclamation-io.ts](../src/shell/reclamation-io.ts)
+- [shell/registry-cli.ts](../src/shell/registry-cli.ts)
+- [shell/remote-source.ts](../src/shell/remote-source.ts)
+- [shell/report-cli.ts](../src/shell/report-cli.ts)
+- [shell/report-view-cli.ts](../src/shell/report-view-cli.ts)
+- [shell/report.ts](../src/shell/report.ts)
+- [shell/reporter.ts](../src/shell/reporter.ts)
+- [shell/run-export-cli.ts](../src/shell/run-export-cli.ts)
+- [shell/run-export.ts](../src/shell/run-export.ts)
+- [shell/run-registry-io.ts](../src/shell/run-registry-io.ts)
+- [shell/scheduling-io.ts](../src/shell/scheduling-io.ts)
+- [shell/state-cli.ts](../src/shell/state-cli.ts)
+- [shell/state-explosion-cli.ts](../src/shell/state-explosion-cli.ts)
+- [shell/telemetry-cli.ts](../src/shell/telemetry-cli.ts)
+- [shell/telemetry-demo.ts](../src/shell/telemetry-demo.ts)
+- [shell/telemetry-ledger-io.ts](../src/shell/telemetry-ledger-io.ts)
+- [shell/term.ts](../src/shell/term.ts)
+- [shell/topology-io.ts](../src/shell/topology-io.ts)
+- [shell/trust-policy-io.ts](../src/shell/trust-policy-io.ts)
+- [shell/workbench-host.ts](../src/shell/workbench-host.ts)
+- [shell/workbench-text.ts](../src/shell/workbench-text.ts)
+- [shell/workbench.ts](../src/shell/workbench.ts)
+- [shell/worker-cli.ts](../src/shell/worker-cli.ts)
 
 ## Workflow Apps
 
@@ -145,6 +206,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [Contract Migration Tooling](contract-migration-tooling.7.md)
 - [Control-Plane Scheduling](control-plane-scheduling.7.md)
 - [Coordinator / Blackboard](coordinator-blackboard.7.md)
+- [Cross-Agent Handoff Ledger](cross-agent-ledger.7.md)
 - [DEMO(7)](demo.7.md)
 - [DOCTOR(7)](doctor.7.md)
 - [Dogfood One Real Repo](dogfood-one-real-repo.7.md)
@@ -155,6 +217,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [EXECUTION-BACKENDS(7)](execution-backends.7.md)
 - [FIX(7)](fix.7.md)
 - [Getting Started](getting-started.md)
+- [Handoff ledger — shared-repo setup (T2a)](handoff-setup.md)
 - [Cool Workflow Docs](index.md)
 - [INIT(7)](init.7.md)
 - [MCP App Surface](mcp-app-surface.7.md)
@@ -210,6 +273,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [artifact-integrity-smoke.js](../test/artifact-integrity-smoke.js)
 - [audit-verify-smoke.js](../test/audit-verify-smoke.js)
 - [backend-registry-smoke.js](../test/backend-registry-smoke.js)
+- [batch-output-overflow-smoke.js](../test/batch-output-overflow-smoke.js)
 - [blackboard-state-explosion-management-smoke.js](../test/blackboard-state-explosion-management-smoke.js)
 - [block-unapproved-tag-smoke.js](../test/block-unapproved-tag-smoke.js)
 - [budget-scaling-loop-smoke.js](../test/budget-scaling-loop-smoke.js)
@@ -235,6 +299,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [collaboration-ops-unit-smoke.js](../test/collaboration-ops-unit-smoke.js)
 - [concurrency-default-smoke.js](../test/concurrency-default-smoke.js)
 - [concurrent-failure-semantics-smoke.js](../test/concurrent-failure-semantics-smoke.js)
+- [concurrent-subworkflow-cache-nesting-smoke.js](../test/concurrent-subworkflow-cache-nesting-smoke.js)
 - [concurrent-workflow-dsl-smoke.js](../test/concurrent-workflow-dsl-smoke.js)
 - [contract-migration-tooling-smoke.js](../test/contract-migration-tooling-smoke.js)
 - [control-plane-scheduling-smoke.js](../test/control-plane-scheduling-smoke.js)
@@ -242,11 +307,14 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [cw-help-per-command-smoke.js](../test/cw-help-per-command-smoke.js)
 - [dead-export-removal-guard-smoke.js](../test/dead-export-removal-guard-smoke.js)
 - [deepseek-agent-wrapper-smoke.js](../test/deepseek-agent-wrapper-smoke.js)
+- [deferred-checkpoint-batching-smoke.js](../test/deferred-checkpoint-batching-smoke.js)
 - [demo-bundle-smoke.js](../test/demo-bundle-smoke.js)
 - [det-ids-b-smoke.js](../test/det-ids-b-smoke.js)
 - [doctor-smoke.js](../test/doctor-smoke.js)
 - [dogfood-architecture-review-smoke.js](../test/dogfood-architecture-review-smoke.js)
 - [dogfood-release-smoke.js](../test/dogfood-release-smoke.js)
+- [drive-concurrency-flag-smoke.js](../test/drive-concurrency-flag-smoke.js)
+- [drive-exhaustion-blocked-smoke.js](../test/drive-exhaustion-blocked-smoke.js)
 - [durable-atomic-write-smoke.js](../test/durable-atomic-write-smoke.js)
 - [end-to-end-demo-smoke.js](../test/end-to-end-demo-smoke.js)
 - [end-to-end-golden-path-smoke.js](../test/end-to-end-golden-path-smoke.js)
@@ -264,6 +332,9 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [h7-custom-profile-persist-smoke.js](../test/h7-custom-profile-persist-smoke.js)
 - [headline-commands-smoke.js](../test/headline-commands-smoke.js)
 - [incremental-resume-smoke.js](../test/incremental-resume-smoke.js)
+- [ledger-apply-smoke.js](../test/ledger-apply-smoke.js)
+- [ledger-resolution-smoke.js](../test/ledger-resolution-smoke.js)
+- [ledger-verify-smoke.js](../test/ledger-verify-smoke.js)
 - [loop-bounded-expansion-smoke.js](../test/loop-bounded-expansion-smoke.js)
 - [mcp-app-surface-smoke.js](../test/mcp-app-surface-smoke.js)
 - [mcp-surface-registry-smoke.js](../test/mcp-surface-registry-smoke.js)
@@ -287,6 +358,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [onramp-check-smoke.js](../test/onramp-check-smoke.js)
 - [opencode-agent-wrapper-smoke.js](../test/opencode-agent-wrapper-smoke.js)
 - [operator-ux-smoke.js](../test/operator-ux-smoke.js)
+- [orphan-runs-gc-smoke.js](../test/orphan-runs-gc-smoke.js)
 - [parallel-onramp-smoke.js](../test/parallel-onramp-smoke.js)
 - [parity-doc-sync-smoke.js](../test/parity-doc-sync-smoke.js)
 - [parse-guard-smoke.js](../test/parse-guard-smoke.js)

package/docs/real-execution-backends.7.md

@@ -187,3 +187,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98
+
+0.2.0

package/docs/release-and-migration.7.md

@@ -327,3 +327,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98
+
+0.2.0

package/docs/release-tooling.7.md

@@ -290,3 +290,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98
+
+0.2.0

package/docs/run-registry-control-plane.7.md

@@ -470,3 +470,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98
+
+0.2.0

package/docs/run-retention-reclamation.7.md

@@ -107,6 +107,27 @@ scratch dir) is **re-pointed** to the retained `results/<task-id>.md` copy, and
 result-node snapshot is shown to stay `valid` (not `absent`) — so no surviving
 node points to a freed path. Opt out with `--keep-scratch`.
 
+## Orphan runs — a second pure-scratch case, OUTSIDE this transaction
+
+A run directory can also be pure scratch a different way: a process killed or
+interrupted before it ever wrote a first `state.json` (the window between
+`ensureRunDirs` and the first `saveCheckpoint`). Such a directory never becomes a
+`RunRecord` at all, so `gc plan`/`gc run` can never see it, let alone reclaim it —
+`reclaimEligibility` requires a record to classify in the first place. `cw orphans
+list`/`cw orphans gc` (`src/run-registry/orphans.ts`) reclaim exactly this case,
+age-gated by default. Unlike everything else on this page, an orphan sweep
+produces **no skeleton and no tombstone** — there is no durable state to seal, so
+there is nothing to prove. It is a plain, un-audited delete of a directory the
+registry never knew existed, not a new tier of the `live -> archived -> reclaimed`
+lifecycle above.
+
+**Known gap, not covered by either mechanism:** a run stuck `running`/`queued`/
+`blocked` with a perfectly valid but stale `state.json` (its owning process died
+without ever reaching a terminal state) is reclaimed by NEITHER `gc.ts` (fail-closes
+on `non-terminal`, no age override) NOR `orphans.ts` (it has a `state.json`, so it
+is not an orphan candidate). As of this writing nothing in `cw` reclaims that
+class of run; it is left `retained` indefinitely rather than guessed at.
+
 ## CLI
 
 ```
@@ -238,3 +259,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98
+
+0.2.0

package/docs/state-explosion-management.7.md

@@ -316,3 +316,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98
+
+0.2.0

package/docs/team-collaboration.7.md

@@ -252,3 +252,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98
+
+0.2.0

package/docs/web-desktop-workbench.7.md

@@ -260,3 +260,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98
+
+0.2.0

package/manifest/plugin.manifest.json

@@ -2,7 +2,7 @@
   "_comment": "SINGLE SOURCE OF TRUTH for every vendor manifest. Edit THIS file, then run `npm run gen:manifests`. Do NOT hand-edit the generated vendor manifests (.claude-plugin/, .codex-plugin/, .agents/, .mcp.json) — `npm run gen:manifests -- --check` (run by release:check) will fail if they drift from this source.",
   "identity": {
     "name": "cool-workflow",
-    "version": "0.1.97",
+    "version": "0.2.0",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/manifest/source-context-profiles.json

@@ -47,11 +47,11 @@
       "description": "MCP and CLI surface context for capability registry, MCP server, CLI routing, and MCP launcher wrappers.",
       "maxLines": 18000,
       "include": [
-        "plugins/cool-workflow/src/capability-core.ts",
-        "plugins/cool-workflow/src/capability-registry.ts",
+        "plugins/cool-workflow/src/core/capability-table.ts",
         "plugins/cool-workflow/src/cli.ts",
+        "plugins/cool-workflow/src/cli/**",
         "plugins/cool-workflow/src/mcp-server.ts",
-        "plugins/cool-workflow/src/types/**",
+        "plugins/cool-workflow/src/mcp/**",
         "plugins/cool-workflow/scripts/cw.js",
         "plugins/cool-workflow/scripts/mcp-server.js",
         "plugins/cool-workflow/package.json",
@@ -72,11 +72,9 @@
       "maxLines": 18000,
       "include": [
         "plugins/cool-workflow/apps/**",
-        "plugins/cool-workflow/src/workflow-app-framework.ts",
-        "plugins/cool-workflow/src/orchestrator.ts",
-        "plugins/cool-workflow/src/orchestrator/**",
-        "plugins/cool-workflow/src/types/workflow-app.ts",
-        "plugins/cool-workflow/src/types/run.ts",
+        "plugins/cool-workflow/src/shell/workflow-app-loader.ts",
+        "plugins/cool-workflow/src/shell/app-run-cli.ts",
+        "plugins/cool-workflow/src/core/workflow-apps/**",
         "plugins/cool-workflow/scripts/canonical-apps.js",
         "plugins/cool-workflow/package.json",
         "plugins/cool-workflow/tsconfig.json"
@@ -121,11 +119,9 @@
       "include": [
         "plugins/cool-workflow/scripts/agents/**",
         "plugins/cool-workflow/scripts/architecture-review-fast.js",
-        "plugins/cool-workflow/src/agent-config.ts",
-        "plugins/cool-workflow/src/execution-backend.ts",
-        "plugins/cool-workflow/src/drive.ts",
-        "plugins/cool-workflow/src/types/execution-backend.ts",
-        "plugins/cool-workflow/src/types/drive.ts",
+        "plugins/cool-workflow/src/shell/agent-config.ts",
+        "plugins/cool-workflow/src/shell/execution-backend/**",
+        "plugins/cool-workflow/src/shell/drive.ts",
         "plugins/cool-workflow/package.json",
         "plugins/cool-workflow/docs/agent-delegation-drive.7.md"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.97",
+  "version": "0.2.0",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"

package/scripts/agents/codex-agent.js

@@ -21,6 +21,16 @@
 // per-run override that does NOT touch the user's interactive codex. Tune with
 // CW_CODEX_REASONING_EFFORT (default "low"); set it to "medium"/"high" to opt back
 // into more thinking.
+//
+// REVIEW MODE: the default low-effort / read-only sandbox is right for a fast
+// delegated worker or a liveness probe — but WRONG for an independent RELEASE
+// reviewer, which must actually RE-RUN the gate (build, tests, regenerate dist)
+// to earn its verdict. A read-only sandbox can't execute that gate, so the model
+// is structurally unable to verify and tends to fabricate a REJECTED. The release
+// path therefore sets CW_RELEASE_REVIEW=1 (a vendor-agnostic signal from
+// release-flow.js): on that signal this wrapper raises reasoning to "high" and
+// opens the sandbox to "workspace-write" so codex can run the gate it is judging.
+// Explicit CW_CODEX_REASONING_EFFORT / CW_CODEX_SANDBOX always win over the signal.
 
 const fs = require("node:fs");
 const os = require("node:os");
@@ -80,11 +90,31 @@ function recordJsonLine(line) {
   }
 }
 
-render.action("codex: reading the repo (read-only)…");
+// A release review (CW_RELEASE_REVIEW=1) must execute the gate it judges, so it
+// needs both stronger reasoning and a sandbox that can write inside the workspace.
+// Explicit env overrides win; otherwise the review signal lifts the fast defaults.
+const reviewMode = process.env.CW_RELEASE_REVIEW === "1";
 
 // Cap codex's reasoning effort for CW runs (speed) — overrides config.toml for
-// THIS invocation only. Default "low"; CW_CODEX_REASONING_EFFORT opts back up.
-const effort = process.env.CW_CODEX_REASONING_EFFORT || "low";
+// THIS invocation only. Default "low"; CW_CODEX_REASONING_EFFORT opts back up, and
+// a release review defaults to "high".
+const effort = process.env.CW_CODEX_REASONING_EFFORT || (reviewMode ? "high" : "low");
+
+// Sandbox: read-only is the POLA default (a worker/probe only reads). A release
+// review opens to workspace-write so codex can build/test/regenerate the gate.
+// CW_CODEX_SANDBOX overrides both; an unknown value fails closed (never silently
+// downgraded to read-only, which would re-create the can't-verify failure mode).
+const SANDBOX_MODES = new Set(["read-only", "workspace-write", "danger-full-access"]);
+const sandbox = process.env.CW_CODEX_SANDBOX || (reviewMode ? "workspace-write" : "read-only");
+if (!SANDBOX_MODES.has(sandbox)) {
+  process.stderr.write(
+    `codex-agent: invalid CW_CODEX_SANDBOX="${sandbox}" — expected one of ${[...SANDBOX_MODES].join(", ")}\n`
+  );
+  process.exit(2);
+}
+
+render.action(`codex: reading the repo (${sandbox})…`);
+
 const args = [
   "exec",
   "--json",
@@ -93,7 +123,7 @@ const args = [
   "--output-last-message",
   finalPath,
   "--sandbox",
-  "read-only",
+  sandbox,
   "--color",
   "never",
   "-"

package/scripts/agents/cw-attest-wrap.js

@@ -12,7 +12,7 @@
 //
 // It signs the EXACT same canonical payload CW verifies — {usage, runId, taskId,
 // promptDigest} — sharing the canonicalization with the verifier via
-// dist/telemetry-attestation.js, so signer and verifier can never drift.
+// dist/core/trust/telemetry-attestation.js, so signer and verifier can never drift.
 //
 // Usage (wrap any agent that prints a {model, usage} JSON report on stdout):
 //   node cw-attest-wrap.js --manifest {{manifest}} -- <agent-cmd> [agent-args...]
@@ -32,7 +32,7 @@ const crypto = require("node:crypto");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
 
-const ta = require(path.resolve(__dirname, "..", "..", "dist", "telemetry-attestation.js"));
+const ta = require(path.resolve(__dirname, "..", "..", "dist", "core", "trust", "telemetry-attestation.js"));
 
 function fail(message) {
   process.stderr.write(`cw-attest-wrap: ${message}\n`);

package/scripts/bump-version.js

@@ -89,8 +89,9 @@ function main() {
     note("server.json");
   }
 
-  // 3. src/version.ts runtime constant
-  const versionTs = path.join(pluginRoot, "src", "version.ts");
+  // 3. src/core/version.ts runtime constant (v2 moved it from the old flat
+  //    src/version.ts into the core state layer)
+  const versionTs = path.join(pluginRoot, "src", "core", "version.ts");
   const vtsText = fs.readFileSync(versionTs, "utf8");
   const vtsNext = vtsText.replace(
     /(CURRENT_COOL_WORKFLOW_VERSION\s*=\s*)"[^"]*"/,
@@ -98,7 +99,7 @@ function main() {
   );
   if (vtsNext !== vtsText) {
     fs.writeFileSync(versionTs, vtsNext);
-    note("src/version.ts");
+    note("src/core/version.ts");
   }
 
   // 4. manifest/plugin.manifest.json (identity.version) — gen:manifests then

package/scripts/canonical-apps.js

@@ -83,7 +83,7 @@ const canonicalApps = [
       "--source",
       "plugins/cool-workflow/docs/workflow-app-framework.7.md",
       "--scope",
-      "Cool Workflow v0.1.97",
+      "Cool Workflow v0.2.0",
       "--freshness",
       "as of release preparation"
     ]
@@ -117,14 +117,14 @@ function main() {
     assert.ok(summary, `${app.id} must appear in app list`);
     assert.equal(summary.sourceKind, "app-directory");
     assert.equal(summary.legacy, false);
-    assert.equal(summary.version, "0.1.97");
+    assert.equal(summary.version, "0.2.0");
 
     const validation = runJson(["app", "validate", manifestPath]);
     assert.equal(validation.valid, true, `${app.id} manifest must validate`);
 
     const shown = runJson(["app", "show", app.id]);
     assert.equal(shown.app.id, app.id);
-    assert.equal(shown.app.version, "0.1.97");
+    assert.equal(shown.app.version, "0.2.0");
     assert.ok(shown.app.metadata.canonical, `${app.id} must be marked canonical`);
     assert.ok(shown.app.sandboxProfiles.length > 0, `${app.id} must declare sandbox profiles`);
     assertTaskIdsUnique(shown);
@@ -135,7 +135,7 @@ function main() {
     const plan = runJson(["plan", app.id, ...app.args(workspace)]);
     const state = JSON.parse(fs.readFileSync(plan.statePath, "utf8"));
     assert.equal(state.workflow.app.id, app.id);
-    assert.equal(state.workflow.app.version, "0.1.97");
+    assert.equal(state.workflow.app.version, "0.2.0");
     assert.equal(state.workflow.app.metadata.canonical, true);
     assert.ok(state.tasks.some((task) => task.requiresEvidence), `${app.id} plan must include evidence gates`);
     assert.ok(state.tasks.every((task) => task.sandboxProfileId), `${app.id} plan must include sandbox hints`);