cool-workflow 0.1.89 → 0.1.90

package/docs/project-index.md

@@ -5,11 +5,11 @@ Generated from the current repository code on 2026-06-21 by `npm run sync:projec
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.1.89`
-- Source modules: `65`
+- Version: `0.1.90`
+- Source modules: `67`
 - Workflow apps: `7`
-- Docs: `52`
-- Smoke tests: `130`
+- Docs: `53`
+- Smoke tests: `136`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -83,6 +83,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [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)
@@ -102,6 +103,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [observability.ts](../src/observability.ts)
 - [onramp.ts](../src/onramp.ts)
 - [reclamation.ts](../src/reclamation.ts)
+- [remote-source.ts](../src/remote-source.ts)
 - [result-normalize.ts](../src/result-normalize.ts)
 - [run-export.ts](../src/run-export.ts)
 - [run-registry.ts](../src/run-registry.ts)
@@ -166,6 +168,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [Release And Migration Discipline](release-and-migration.7.md)
 - [Cool Workflow Release History](release-history.md)
 - [Release Tooling](release-tooling.7.md)
+- [Remote-Source Review (`--link`)](remote-source-review.7.md)
 - [Verifiable Report Bundle](report-verifiable-bundle.7.md)
 - [Routines](routines.md)
 - [Run Registry / Control Plane](run-registry-control-plane.7.md)
@@ -203,9 +206,13 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [candidate-scoring-smoke.js](../test/candidate-scoring-smoke.js)
 - [canonical-workflow-apps-smoke.js](../test/canonical-workflow-apps-smoke.js)
 - [claude-p-agent-wrapper-smoke.js](../test/claude-p-agent-wrapper-smoke.js)
+- [cli-arg-parsing-smoke.js](../test/cli-arg-parsing-smoke.js)
 - [cli-command-surface-smoke.js](../test/cli-command-surface-smoke.js)
 - [cli-jsonmode-parity-smoke.js](../test/cli-jsonmode-parity-smoke.js)
 - [cli-mcp-parity-smoke.js](../test/cli-mcp-parity-smoke.js)
+- [cli-progress-summary-smoke.js](../test/cli-progress-summary-smoke.js)
+- [cli-recoverable-errors-smoke.js](../test/cli-recoverable-errors-smoke.js)
+- [clones-gc-smoke.js](../test/clones-gc-smoke.js)
 - [codex-agent-wrapper-smoke.js](../test/codex-agent-wrapper-smoke.js)
 - [concurrency-default-smoke.js](../test/concurrency-default-smoke.js)
 - [concurrent-failure-semantics-smoke.js](../test/concurrent-failure-semantics-smoke.js)
@@ -272,6 +279,8 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [release-flow-smoke.js](../test/release-flow-smoke.js)
 - [release-gate-smoke.js](../test/release-gate-smoke.js)
 - [release-tooling-smoke.js](../test/release-tooling-smoke.js)
+- [remote-link-archive-smoke.js](../test/remote-link-archive-smoke.js)
+- [remote-link-git-smoke.js](../test/remote-link-git-smoke.js)
 - [report-bundle-smoke.js](../test/report-bundle-smoke.js)
 - [report-verify-bundle-smoke.js](../test/report-verify-bundle-smoke.js)
 - [result-normalize-smoke.js](../test/result-normalize-smoke.js)

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

@@ -173,3 +173,5 @@ _No behavioral change in v0.1.88 (the container/remote/ci delegating integration
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

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

@@ -313,3 +313,5 @@ _No behavioral change in v0.1.88 (`release:check` and the durable run-state comp
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/release-tooling.7.md

@@ -251,3 +251,5 @@ The release flow now captures the reviewer's verdict from agent stdout (`release
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/remote-source-review.7.md

@@ -0,0 +1,88 @@
+# Remote-Source Review (`--link`)
+
+CW v0.1.91 lets you point a review at **any repository on the internet** instead
+of only a local path: `cw -q "what are the risks?" --link <url>`. CW materializes
+the remote into a local checkout and runs the **existing** review pipeline against
+it — identical downstream to reviewing a folder. A URL passed to `-dir`/`--repo`
+is auto-detected, so `--link <url>` and `-dir <url>` are equivalent.
+
+```bash
+cw -q "What are the risks?" --link https://github.com/owner/repo
+cw -q "What are the risks?" --link git@gitlab.com:owner/repo.git --ref v1.2.0
+cw -q "What are the risks?" --link https://github.com/owner/repo/archive/refs/heads/main.tar.gz
+cw -q "..." --link <url> --check     # validate the URL + tooling WITHOUT fetching
+```
+
+## Sources
+
+- **Git repositories**, any host: `https://`, `http://`, `ssh://`, `git://`, the
+  scp-style `git@host:owner/repo`, and `file://`. Cloned shallow (`--depth 1
+  --single-branch`); `--ref <branch|tag>` selects a ref. `commit` is the resolved
+  `HEAD` SHA.
+- **Downloadable archives**: `.tar.gz` / `.tgz` / `.tar` / `.zip` (e.g. a GitHub
+  "Download ZIP" / codeload tarball). Fetched, extracted, and `git init`-snapshotted
+  into a local repo so the git-tracked source-context reader works unchanged.
+  `commit` is the **sha256 of the downloaded bytes** (a content address — there is
+  no git SHA).
+
+## The red line — materialize source, do not internalize execution
+
+`--link` only materializes the **source** to review. CW still **DELEGATES** worker
+execution to the operator's configured agent backend (`claude -p`, `codex exec`, an
+HTTP endpoint) exactly as a local review does; it never executes a model itself.
+Cloning is non-deterministic network I/O, so it happens in the **capability layer**
+(before `plan`), never in the replay-deterministic orchestrator core — which only
+ever sees the resulting local path.
+
+## Provenance — where the code came from, tamper-evidently
+
+The sanitized origin rides through three surfaces:
+
+- `run.inputs` → a `- Source: <url>@<commit>` line in `report.md`.
+- the `--json` result's `remote { url, commit, kind, ref, cached }`.
+- a hash-chained `source.clone` / `source.download` **trust-audit event** that
+  `cw audit verify <run-id>` re-proves — editing the recorded origin is detectable.
+
+Credentials in a URL (`https://user:token@host/…`) are stripped before the URL is
+used as a cache key, printed, persisted, or recorded; the raw URL reaches only a
+single `git` argv element. Git/download diagnostics are credential-redacted before
+they are ever surfaced.
+
+## Fail closed
+
+A bad URL, a blocked scheme, a network failure, or a credential-less private repo
+produces an **explicit error and a non-zero exit** — never a fabricated review,
+never a hang on an auth prompt (`GIT_TERMINAL_PROMPT=0`). Hardening:
+
+- **Scheme allowlist** (https/http/ssh/git/file); `ext::`/`fd::` transport helpers
+  and `-`-leading option-injection are rejected; the URL is always a separate argv
+  element (never a shell string); repo hooks are disabled (`-c core.hooksPath=`).
+- **Archive extraction** validates the entry listing for `..`/absolute traversal
+  BEFORE extracting, **rejects symlink/non-regular entries** (walked with `lstat`),
+  and bounds the decompression bomb by **declared** uncompressed size (gzip ISIZE /
+  `unzip -l`) before extracting and **actual** size (1 GiB) after.
+- **SSRF**: http(s) redirects are followed manually and each hop is re-validated
+  (http(s) scheme + no private/loopback/link-local host) before connecting — a
+  public URL cannot redirect CW into an internal service.
+
+## Cache — `cw clones`
+
+Checkouts are cached, content-addressed, under
+`~/.local/state/cool-workflow/clones/<hash>/` (honoring `CW_HOME`/`XDG_STATE_HOME`)
+and reused on the next question; `--refresh` re-fetches. Manage the cache:
+
+```bash
+cw clones list                          # origin url, kind, commit, age, bytes
+cw clones gc --older-than-days 30       # reclaim checkouts older than N days
+cw clones gc --all                      # reclaim everything
+```
+
+`cw clones gc` deletes only paths it has proven are inside the clones cache (fail
+closed). Both verbs have MCP peers (`cw_clones_list`, `cw_clones_gc`) with
+byte-identical payloads.
+
+## Determinism note
+
+The cache is keyed on the URL (+ref), not on content: if a URL's content changes
+upstream, the cached checkout is reused until `--refresh` (mirroring how a git
+clone pins its resolved `HEAD`). Use `--refresh` to re-fetch the latest.

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

@@ -434,3 +434,5 @@ Security: archive import now refuses path-traversal run ids (`..`/absolute/separ
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

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

@@ -224,3 +224,5 @@ _No behavioral change in v0.1.88 (the tiered, append-only, cryptographically-ver
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

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

@@ -302,3 +302,5 @@ _No behavioral change in v0.1.88 (the summarization/compaction layer and its fai
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/team-collaboration.7.md

@@ -238,3 +238,5 @@ _No behavioral change in v0.1.88 (the host-attested actor, append-only approvals
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

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

@@ -246,3 +246,5 @@ _No behavioral change in v0.1.88 (the five operator surfaces and the registry cr
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

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.89",
+    "version": "0.1.90",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/manifest/source-context-profiles.json

@@ -25,7 +25,7 @@
     },
     "runtime": {
       "description": "Runtime-kernel source context for state, orchestration, scheduling, execution, and shared types.",
-      "maxLines": 44000,
+      "maxLines": 48000,
       "include": [
         "plugins/cool-workflow/src/**",
         "plugins/cool-workflow/package.json",

package/package.json

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

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.89",
+      "Cool Workflow v0.1.90",
       "--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.89");
+    assert.equal(summary.version, "0.1.90");
 
     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.89");
+    assert.equal(shown.app.version, "0.1.90");
     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.89");
+    assert.equal(state.workflow.app.version, "0.1.90");
     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`);

package/scripts/dogfood-release.js

@@ -6,7 +6,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { CoolWorkflowRunner } = require("../dist/orchestrator.js");
 
-const TARGET_VERSION = "0.1.89";
+const TARGET_VERSION = "0.1.90";
 const PREVIOUS_VERSION = "0.1.31";
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");

package/scripts/golden-path.js

@@ -33,7 +33,7 @@ function main() {
     const appValidation = runJson(["app", "validate", "end-to-end-golden-path"], pluginRoot);
     assert.equal(appValidation.valid, true);
     assert.equal(appValidation.summary.id, "end-to-end-golden-path");
-    assert.equal(appValidation.summary.version, "0.1.89");
+    assert.equal(appValidation.summary.version, "0.1.90");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.1.89 end-to-end golden path."
+        "Prove the deterministic v0.1.90 end-to-end golden path."
       ],
       pluginRoot
     );
@@ -52,7 +52,7 @@ function main() {
 
     let state = readJson(plan.statePath);
     assert.equal(state.workflow.app.id, "end-to-end-golden-path");
-    assert.equal(state.workflow.app.version, "0.1.89");
+    assert.equal(state.workflow.app.version, "0.1.90");
     assert.equal(state.loopStage, "interpret");
 
     const dispatch = runJson(["dispatch", plan.runId, "--limit", "1", "--sandbox", "readonly"], tmp);
@@ -195,7 +195,7 @@ function main() {
     assert.equal(reportPath, plan.reportPath);
     assert.ok(fs.existsSync(reportPath));
     const report = fs.readFileSync(reportPath, "utf8");
-    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.89/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.90/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);