cueline 0.2.1 → 0.3.0

package/docs/1.0/ideas/machine-output-contracts.md

@@ -0,0 +1,47 @@
+# Machine-output contracts experiment
+
+## Hypothesis and user value
+
+Automation that consumes CueLine health output needs versioned, executable
+contracts so a release cannot silently change field names, types, redaction or
+nested structure.
+
+## Change boundary
+
+- Adds explicit schema identifiers to `doctor --json` and `routing --json`;
+  preserves the existing `routing explain --json` identifier.
+- Publishes strict JSON Schema 2020-12 contracts for those three outputs.
+- Adds a real CLI contract validator to CI and a development-only Ajv
+  dependency; CueLine runtime dependencies remain empty.
+- Does not change human output, routing decisions, browser behavior, provider
+  calls or durable state.
+
+## Acceptance and adversarial cases
+
+1. Real doctor, routing and routing-explain JSON validate against their schemas.
+2. Every public object uses `additionalProperties: false`.
+3. A secret-like top-level field is rejected.
+4. A runner `argv` field is rejected.
+5. Missing required fields and wrong schema versions are rejected.
+6. Valid and invalid routing configuration variants retain parseable output.
+
+## Verified evidence
+
+- Targeted contract and CLI tests: 67 passed, 0 failed, including all three
+  degraded invalid-config variants.
+- Contract validation command: 3 passed, 0 failed.
+- Full test suite: 494 passed, 0 failed after updating four authoritative
+  machine-output snapshots for the new schema identifiers.
+- TypeScript build: passed.
+- Plugin validation: passed.
+- `npm pack --dry-run`: passed; all three schema files and the validator are in
+  the package, while Ajv remains development-only.
+
+## Rollback
+
+Revert this branch's commit. It owns the three schemas, validator, tests, Ajv
+development dependency, CI step, schema identifiers and updated snapshots.
+
+This experiment remains isolated on `codex/idea-machine-output-contract`. It
+must not be merged into `main`; Vincent decides whether it is selected or
+integrated.

package/docs/1.0/ideas/node26-contract.md

@@ -0,0 +1,50 @@
+# Node 26 support contract experiment
+
+## Hypothesis and user value
+
+CueLine should preserve Node 22 as its minimum while proving current even-LTS
+compatibility through one synchronized engines, CI and documentation contract.
+
+## Change boundary
+
+- Expands the existing Ubuntu/macOS CI matrix from Node 22/24 to 22/24/26.
+- Keeps `engines.node` at `>=22`.
+- Synchronizes all five README development sections and the compatibility
+  matrix.
+- Adds a read-only contract validator; it does not install, download or switch
+  Node versions.
+- Does not change runtime behavior, browser control, routing, state or provider
+  access.
+
+## Acceptance and adversarial cases
+
+1. Engine requirement is exactly `>=22`.
+2. CI Node majors are exactly 22, 24 and 26 on Ubuntu and macOS.
+3. All localized README files and compatibility docs name the tested majors.
+4. Removing Node 26, leaving one README stale or changing engines makes the
+   validator fail.
+5. The current Node 26 runtime passes the complete local release-facing checks.
+
+## Verified evidence
+
+- Node support validator: passed on Node 26.3.0.
+- Targeted contract tests: 4 passed, 0 failed.
+- Full test suite on Node 26.3.0: 494 passed, 0 failed.
+- Fake smoke on Node 26.3.0: 6 passed, 0 failed.
+- Shell install/reinstall/uninstall/foreign-file preservation: passed.
+- npm tarball global install, skill install, doctor and uninstall: passed.
+- TypeScript build, plugin validation and `npm pack --dry-run`: passed.
+
+## Remaining external verification
+
+The workflow now requests Node 26 on both Ubuntu and macOS, but this isolated
+branch has not been pushed. Therefore GitHub-hosted Node 26 results remain
+unverified until Vincent selects and explicitly authorizes remote integration.
+
+## Rollback
+
+Revert this branch's commit. It owns the CI matrix addition, support validator,
+tests, documentation synchronization and this experiment record.
+
+This experiment remains isolated on `codex/idea-node26-contract`. It must not be
+merged into `main`; Vincent decides whether it is selected or integrated.

package/docs/1.0/ideas/offline-self-test.md

@@ -0,0 +1,52 @@
+# Offline self-test experiment
+
+## Hypothesis and user value
+
+An installed CueLine package should be able to prove that its controller loop,
+process routing, durable state, final delivery, and run verifier work together
+without opening a browser, contacting a provider, or touching the user's real
+CueLine state.
+
+## Change boundary
+
+- Adds `cueline self-test [--json]`.
+- Uses an in-memory deterministic controller and the current Node executable.
+- Creates two private temporary directories for run state and workspace, then
+  removes only those exact directories before returning.
+- Does not read or write the configured `CUELINE_HOME` or `CUELINE_CONFIG`.
+- Does not open a browser, use credentials, contact a provider, or make a
+  network request.
+- Does not relax production controller provenance checks. The in-memory
+  adapter supplies fixed synthetic Pro-shaped evidence solely to exercise the
+  existing verifier; the report is explicitly marked `offline: true`.
+
+## Acceptance and adversarial cases
+
+1. The isolated controller completes exactly two rounds.
+2. One required local process job completes.
+3. The expected final delivery is recorded.
+4. `verifyCueLineRun` returns `verified` for the temporary run.
+5. A pre-existing `CUELINE_DEPTH` fails closed with
+   `NESTED_ROUTING_REJECTED` before temporary state is created.
+6. Unknown CLI arguments return exit code 2.
+7. JSON output contains neither temporary paths nor worker task content.
+8. Temporary-directory counts are unchanged across a real CLI invocation.
+
+## Verified evidence
+
+- Targeted integration tests: 4 passed, 0 failed.
+- Full test suite: 494 passed, 0 failed.
+- TypeScript build: passed.
+- Plugin validation: passed.
+- Real `./bin/cueline self-test --json`: status `ok`; two controller rounds,
+  one completed job, final delivery true, durable verification true.
+- Temporary cleanup check: 0 matching directories before and after.
+
+## Rollback
+
+Revert this branch's commit. The feature owns only
+`src/diagnostics/offline-self-test.ts`, its integration test and documentation,
+plus the focused command/help additions in `src/cli/main.ts`.
+
+This experiment remains isolated on `codex/idea-offline-self-test`. It must not
+be merged into `main`; Vincent decides whether it is selected or integrated.

package/docs/1.0/ideas/upgrade-preflight.md

@@ -0,0 +1,46 @@
+# Upgrade preflight experiment
+
+## Hypothesis and user value
+
+Before replacing an installed CueLine version, operators need one read-only
+command that proves the target is a valid forward upgrade and that local
+configuration and durable state are safe to carry forward.
+
+## Change boundary
+
+- Adds `cueline upgrade preflight --to <version> [--json]`.
+- Reads the current Node version, active routing configuration, state-home file
+  type and permissions, and sanitized persisted run summaries.
+- Never creates a state home, follows a state-home symlink, changes permissions,
+  migrates files, cancels runs, launches a browser, or contacts a provider.
+- Accepts stable semantic target versions only; it does not authorize downgrade
+  or prerelease migration policy.
+
+## Blocking conditions
+
+- Invalid or older target version.
+- Node older than 22.
+- Routing configuration unreadable by the installed version.
+- State home is a symlink, non-directory, unreadable, or grants group/other
+  permissions.
+- Any run is non-terminal or has unreadable durable evidence.
+
+## Verified evidence
+
+- Targeted integration tests: 5 passed, 0 failed.
+- Full test suite: 495 passed, 0 failed.
+- TypeScript build: passed.
+- Plugin validation: passed.
+- Real `./bin/cueline upgrade preflight --to 1.0.0 --json`: status `ready`
+  with a missing isolated state home.
+- The real CLI check verified that the missing state home remained absent.
+- A persisted non-terminal run retained the exact event-log size and mtime
+  across preflight.
+
+## Rollback
+
+Revert this branch's commit. It owns the preflight diagnostic, its tests and
+documentation, plus focused health-command and help entries.
+
+This experiment remains isolated on `codex/idea-upgrade-preflight`. It must not
+be merged into `main`; Vincent decides whether it is selected or integrated.

package/docs/compatibility.md

@@ -2,9 +2,9 @@
 
 ## Runtime matrix
 
-| Surface | v0.1 status | Notes |
+| Surface | Current status | Notes |
 |---|---|---|
-| Node.js 22+ ESM | Supported | Core protocol, state, router, runners, fake browser tests |
+| Node.js 22+ ESM | Supported | CI: 22, 24, 26 on Ubuntu and macOS; core protocol, state, router, runners, fake browser tests |
 | Codex Node REPL + built-in Browser (IAB) | Required for live control | Provides the imported API with the authenticated ChatGPT tab/browser client |
 | Current Codex caller | Default local executor | Performs caller `advise`; caller `work` requires durable claim/start/heartbeat/result proof |
 | `codex` CLI | Required only by bundled process route | Double authorization plus `--ignore-user-config`; auth remains under `CODEX_HOME`, user MCP config is not loaded |
@@ -19,9 +19,9 @@ The npm package has no runtime dependencies. Development requires TypeScript and
 
 CueLine is designed for a conversation already authenticated by the user at `chatgpt.com`. CueLine neither handles credentials nor verifies plan entitlement. Before each controller turn it may switch the composer to `Pro`; that is its only automatic model switch. It also requires Pro evidence on the completed response.
 
-The v0.1 adapter relies on accessible textbox/button roles, attachment chips, and assistant-message markup in the current ChatGPT web UI. ChatGPT's automatic conversion of a long filled prompt into an attachment is supported. Deliberate file upload is not. UI changes can cause explicit `COMPOSER_MISSING`, `SEND_BUTTON_MISSING`, or response-timeout errors. A fake adapter test cannot prove that the current live page still matches.
+The browser adapter relies on accessible textbox/button roles, attachment chips, and assistant-message markup in the current ChatGPT web UI. ChatGPT's automatic conversion of a long filled prompt into an attachment is supported. Deliberate file upload is not. UI changes can cause explicit `COMPOSER_MISSING`, `SEND_BUTTON_MISSING`, or response-timeout errors. A fake adapter test cannot prove that the current live page still matches.
 
-## Supported in v0.1
+## Supported contract
 
 - one ChatGPT conversation per run
 - text controller observations and commands
@@ -40,7 +40,7 @@ The v0.1 adapter relies on accessible textbox/button roles, attachment chips, an
 - process status with resolved runner, PID, phase, last progress, and safely observed model/provider
 - injected fake browser/runner for offline tests
 
-## Not supported in v0.1
+## Not supported
 
 - model switching other than CueLine selecting `Pro`
 - images, screenshots as controller input, audio, or binary payloads

package/docs/runner-contract.md

@@ -65,7 +65,7 @@ interface RunnerSpec {
 - Empty output is explicitly recorded instead of being replaced with invented content.
 - Results are never marked retryable by the process runner.
 
-Advise workers must return focused evidence, not whole-file dumps: absolute paths, relevant line references, exact code or error identifiers, and short excerpts sufficient for the decision. When total unserved evidence exceeds the remaining rounds multiplied by the 12,000-character per-round budget, CueLine warns the controller to decide from available summaries or dispatch a summarization task instead of paging every omitted tail. The controller may decide as soon as evidence is sufficient and is never required to read every omitted tail.
+Advise workers must return focused evidence, not whole-file dumps: absolute paths, relevant line references, exact code or error identifiers, and short excerpts sufficient for the decision. Capacity arithmetic uses only unserved characters in the capped representations that the controller can actually page through. When that servable total exceeds the remaining rounds multiplied by the 12,000-character per-round budget, CueLine warns the controller to decide from available summaries or dispatch a summarization task instead of paging every omitted tail. True source totals beyond the durable per-job caps are deliberately outside this cursor coordinate system and produce a separate durable-cap notice instead of inflating the capacity warning with forever-unservable characters. The controller may decide as soon as evidence is sufficient and is never required to read every omitted tail.
 
 For an unsuccessful process `work` job, `ambiguousSideEffects` is true because CueLine cannot prove how much mutation occurred before failure. That flag is preserved in the job result. For caller work, every non-success result after durable start is normalized to terminal `ambiguous`, so the controller cannot mistake `failed`, `timed_out`, or `cancelled` for proof of no side effects. Such work must be inspected and explicitly decided by the web controller; it must not be auto-retried.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueline",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A ChatGPT web conversation directs; CueLine validates each command and hands durable advice or explicitly claimed work to the current Codex.",
   "keywords": [
     "chatgpt",
@@ -66,10 +66,20 @@
     "test:unit": "npm run build && node --test dist/test/unit/*.test.js",
     "test:integration": "npm run build && node --test dist/test/integration/*.test.js",
     "smoke:fake": "npm run build && node --test dist/test/smoke/fake-smoke.test.js",
-    "validate:plugin": "node scripts/validate-plugin.mjs"
+    "validate:node-support": "node scripts/validate-node-support.mjs --json",
+    "validate:cli-contracts": "npm run build && node scripts/validate-cli-contracts.mjs",
+    "validate:plugin": "node scripts/validate-plugin.mjs",
+    "validate:docs": "node scripts/validate-doc-versions.mjs",
+    "test:docs": "node --test test/release/doc-version-guard.test.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "test:release-check": "node --test test/release/release-check.test.mjs",
+    "artifact:build": "node scripts/artifact-integrity.mjs build",
+    "artifact:verify": "node scripts/artifact-integrity.mjs verify",
+    "test:artifact": "node --test test/release/artifact-integrity.test.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
+    "ajv": "^8.20.0",
     "typescript": "^7.0.2"
   }
 }

package/schemas/cli-doctor.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/cli-doctor.schema.json",
+  "title": "CueLine doctor machine output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "version", "status", "node", "config", "home", "caller", "process", "findings"],
+  "properties": {
+    "schema": { "const": "cueline-doctor/1" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "status": { "enum": ["ok", "degraded"] },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "ok", "requirement"],
+      "properties": {
+        "version": { "type": "string", "minLength": 1 },
+        "ok": { "type": "boolean" },
+        "requirement": { "const": ">=22" }
+      }
+    },
+    "config": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "valid"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "valid": { "const": true }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "valid", "errorCode"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "valid": { "const": false },
+            "errorCode": { "const": "ROUTING_CONFIG_INVALID" }
+          }
+        }
+      ]
+    },
+    "home": { "type": "string", "minLength": 1 },
+    "caller": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ready", "enabledLanes"],
+      "properties": {
+        "ready": { "type": "boolean" },
+        "enabledLanes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "process": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["availableLanes"],
+      "properties": {
+        "availableLanes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "surface", "message"],
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "surface": { "enum": ["node", "config", "caller"] },
+          "message": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/schemas/cli-routing-explain.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/cli-routing-explain.schema.json",
+  "title": "CueLine routing explanation machine output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "version", "config", "requestedLane", "availableLanes", "lanes", "findings"],
+  "properties": {
+    "schema": { "const": "cueline-routing-explain/0.1" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "config": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "valid"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "valid": { "const": true }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "valid", "errorCode"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "valid": { "const": false },
+            "errorCode": { "const": "ROUTING_CONFIG_INVALID" }
+          }
+        }
+      ]
+    },
+    "requestedLane": {
+      "anyOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }]
+    },
+    "availableLanes": { "type": "integer", "minimum": 0 },
+    "lanes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "enabled", "status", "selectedRunnerId", "candidates"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "enabled": { "type": "boolean" },
+          "status": { "enum": ["available", "unavailable", "disabled"] },
+          "selectedRunnerId": {
+            "anyOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }]
+          },
+          "errorCode": { "const": "ROUTE_NO_CANDIDATE" },
+          "candidates": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "index", "enabled", "available", "selected", "reasonCode"],
+              "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "index": { "type": "integer", "minimum": 0 },
+                "enabled": { "type": "boolean" },
+                "available": {
+                  "anyOf": [{ "type": "boolean" }, { "type": "null" }]
+                },
+                "selected": { "type": "boolean" },
+                "reasonCode": {
+                  "enum": ["LANE_DISABLED", "RUNNER_DISABLED", "RUNNER_UNAVAILABLE", "SELECTED_FIRST_AVAILABLE", "AVAILABLE_FALLBACK"]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "message"],
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "message": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/schemas/cli-routing.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/cli-routing.schema.json",
+  "title": "CueLine routing machine output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "version", "config", "availableLanes", "lanes", "findings"],
+  "properties": {
+    "schema": { "const": "cueline-routing/1" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "config": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "valid"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "valid": { "const": true }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "valid", "errorCode"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "valid": { "const": false },
+            "errorCode": { "const": "ROUTING_CONFIG_INVALID" }
+          }
+        }
+      ]
+    },
+    "availableLanes": { "type": "integer", "minimum": 0 },
+    "lanes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "enabled", "status", "selectedRunnerId"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "enabled": { "type": "boolean" },
+          "status": { "enum": ["available", "unavailable", "disabled"] },
+          "selectedRunnerId": {
+            "anyOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }]
+          },
+          "errorCode": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "message"],
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "message": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/schemas/cli-run-audit-secrets.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/cli-run-audit-secrets.schema.json",
+  "title": "cueline run audit-secrets --json output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "version",
+    "protocol",
+    "runId",
+    "scannedEvents",
+    "scannedFields",
+    "findings",
+    "clean"
+  ],
+  "allOf": [
+    {
+      "if": { "properties": { "clean": { "const": true } }, "required": ["clean"] },
+      "then": { "properties": { "findings": { "type": "array", "maxItems": 0 } } },
+      "else": { "properties": { "findings": { "type": "array", "minItems": 1 } } }
+    }
+  ],
+  "properties": {
+    "schema": { "const": "cueline-run-audit-secrets/1" },
+    "version": { "type": "string", "minLength": 1 },
+    "protocol": { "const": "cueline-secret-audit/0.1" },
+    "runId": { "type": "string", "minLength": 1 },
+    "scannedEvents": { "type": "integer", "minimum": 1 },
+    "scannedFields": { "type": "integer", "minimum": 0 },
+    "clean": { "type": "boolean" },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "kind",
+          "sequence",
+          "eventType",
+          "path",
+          "matchLength",
+          "maskedPreview"
+        ],
+        "properties": {
+          "kind": {
+            "enum": [
+              "aws_access_key_id",
+              "github_token",
+              "slack_token",
+              "anthropic_api_key",
+              "openai_api_key",
+              "google_api_key",
+              "jwt",
+              "private_key_block",
+              "bearer_token",
+              "credential_assignment"
+            ]
+          },
+          "sequence": { "type": "integer", "minimum": 1 },
+          "eventType": { "type": "string", "minLength": 1 },
+          "path": { "type": "string", "minLength": 1 },
+          "matchLength": { "type": "integer", "minimum": 1 },
+          "maskedPreview": {
+            "type": "string",
+            "pattern": "^.{1,4}…\\([0-9]+ chars\\)$"
+          }
+        }
+      }
+    }
+  }
+}