@cleocode/core 2026.9.23 → 2026.9.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -421,6 +421,16 @@
       "import": "./dist/git-shim-export.js",
       "require": "./dist/git-shim-export.js"
     },
+    "./cloud/*": {
+      "types": "./dist/cloud/*.d.ts",
+      "import": "./dist/cloud/*.js",
+      "require": "./dist/cloud/*.js"
+    },
+    "./cloud/*.js": {
+      "types": "./dist/cloud/*.d.ts",
+      "import": "./dist/cloud/*.js",
+      "require": "./dist/cloud/*.js"
+    },
     "./decide/*": {
       "types": "./dist/decide/*.d.ts",
       "import": "./dist/decide/*.js",
@@ -481,16 +491,16 @@
     "write-file-atomic": "^7.0.1",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@cleocode/agents": "2026.9.23",
-    "@cleocode/adapters": "2026.9.23",
-    "@cleocode/caamp": "2026.9.23",
-    "@cleocode/contracts": "2026.9.23",
-    "@cleocode/git-shim": "2026.9.23",
-    "@cleocode/lafs": "2026.9.23",
-    "@cleocode/paths": "2026.9.23",
-    "@cleocode/skills": "2026.9.23",
-    "@cleocode/nexus": "2026.9.23",
-    "@cleocode/worktree": "2026.9.23"
+    "@cleocode/agents": "2026.9.25",
+    "@cleocode/caamp": "2026.9.25",
+    "@cleocode/adapters": "2026.9.25",
+    "@cleocode/contracts": "2026.9.25",
+    "@cleocode/git-shim": "2026.9.25",
+    "@cleocode/lafs": "2026.9.25",
+    "@cleocode/paths": "2026.9.25",
+    "@cleocode/skills": "2026.9.25",
+    "@cleocode/nexus": "2026.9.25",
+    "@cleocode/worktree": "2026.9.25"
   },
   "engines": {
     "node": ">=24.16.0"
@@ -516,7 +526,7 @@
     "@types/proper-lockfile": "^4.1.4",
     "@types/tar": "^6.1.13",
     "@types/write-file-atomic": "^4.0.3",
-    "@cleocode/utils": "2026.9.23"
+    "@cleocode/utils": "2026.9.25"
   },
   "repository": {
     "type": "git",
@@ -525,7 +535,7 @@
   },
   "optionalDependencies": {
     "llmtxt": "^2026.5.15",
-    "@cleocode/studio": "^2026.9.23"
+    "@cleocode/studio": "^2026.9.25"
   },
   "scripts": {
     "build": "tsc && node scripts/copy-selfimprove-fixtures.mjs && node scripts/write-build-provenance.mjs",

package/schemas/project-info.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://cleo-dev.com/schemas/v1/project-info.schema.json",
   "schemaVersion": "1.0.0",
   "title": "CLEO Project Info Schema",
-  "description": "Per-project manifest file (.cleo/project-info.json). Contains project identity, origin provenance, and schema version tracking. Acts as the portable descriptor for the .cleo/ container — when .cleo/ is shared between systems, this file carries the project's identity and origin.",
+  "description": "Device-local project metadata (.cleo/project-info.json, untracked per ADR-013 §9). The committed identity lives in .cleo/project.json {schemaVersion, id, name} (T12716; legacy mirror .cleo/project-id); here projectId is only a cache of that id, and name is a frozen legacy value. Also carries origin provenance, the per-checkout nonce and schema version tracking.",
   "type": "object",
   "required": ["schemaVersion", "projectHash", "projectId", "schemas"],
   "additionalProperties": false,
@@ -21,7 +21,7 @@
     "projectId": {
       "type": "string",
       "minLength": 1,
-      "description": "Portable project-local identity (UUIDv4). Survives .cleo/ moves between filesystems. Used as the stable brain key for cross-system project sharing."
+      "description": "Cache of the tracked portable id in .cleo/project.json (T12716; legacy .cleo/project-id). The tracked id always wins; a cache that disagrees is re-keyed only by `cleo doctor project-identity --resolve`. Used alone only by a project with no tracked id yet."
     },
     "checkoutNonce": {
       "type": "string",
@@ -31,7 +31,7 @@
     "projectHash": {
       "type": "string",
       "pattern": "^[a-f0-9]{12}$",
-      "description": "Write-once 12-character hex identity key (SHA-256 prefix of the real main-checkout path at init). Keys release ids, audit rows and idempotency. Never re-computed: not on project move, relocation, restore or `cleo upgrade` (T12557)."
+      "description": "Write-once 12-character hex identity key. Keys release ids, audit rows and idempotency. A new key is SHA-256('project-id:' + id) prefix, identical on every clone (T12716); keys written before T12716 are the SHA-256 prefix of the real main-checkout path. Never re-computed: not on project move, relocation, restore or `cleo upgrade` (T12557)."
     },
     "previousProjectIds": {
       "type": "array",
@@ -55,11 +55,17 @@
         }
       }
     },
+    "displayName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120,
+      "description": "Display name of a legacy project (no .cleo/project.json yet), written by `cleo project rename` / `cleo upgrade --name` (T12716). Kept apart from `name` so a rename never moves the path-fingerprint alias key. `cleo doctor project-identity --resolve` carries it into project.json."
+    },
     "name": {
       "type": "string",
       "minLength": 1,
       "maxLength": 128,
-      "description": "Human-readable project name. Defaults to the directory basename. Used by canonicalProjectId for nexus identity computation and by project rename operations."
+      "description": "Legacy name, written once (the directory basename at init). Kept only as the input to the path-fingerprint alias key older builds recorded. The display name lives in .cleo/project.json (T12716); it is read from here (after `displayName`) only for a legacy project not yet migrated by `cleo doctor project-identity --resolve`. Nothing rewrites it after init."
     },
     "description": {
       "type": "string",

package/templates/CLEO-INJECTION.md

@@ -1,6 +1,6 @@
 # CLEO Protocol
 
-Version: 2.23.0 | CLI-only dispatch | `cleo <command> [args]`
+Version: 2.24.1 | CLI-only dispatch | `cleo <command> [args]`
 
 <!-- CLEO-INJECTION:section=session-start -->
 ## Universal protocol

package/templates/CLEO-REFERENCE.md

@@ -1,6 +1,6 @@
 # CLEO Protocol — on-demand reference
 
-Version: 2.23.0 | Companion to the always-loaded `CLEO-INJECTION.md` core
+Version: 2.24.1 | Companion to the always-loaded `CLEO-INJECTION.md` core
 
 Not injected into agent context. Print one section with `cleo briefing inject --section <name>`; tier-2 spawn prompts embed this whole file. Section names are the `CLEO-INJECTION:section` markers below.
 
@@ -13,7 +13,7 @@ Not injected into agent context. Print one section with `cleo briefing inject --
 <!-- CLEO-INJECTION:section=projection -->
 ## Projections, budgets and mutation receipts
 
-Projection markers include omitted empty/null fields and survive repeated projection. `_withheld` maps omitted fields to UTF-8 content bytes (JSON bytes for structured values). A record without `_withheld` is complete. Budgeting preserves coverage, diagnostic failures, authority corrections and pending repair facts before examples. A read budget too small for mandatory facts fails explicitly; request narrower scope or more budget. Never treat this failure as clean coverage.
+Projection markers include omitted empty/null fields and survive repeated projection. `_withheld` maps omitted fields to UTF-8 content bytes (JSON bytes for structured values). A `list/*/field` key (e.g. `acRows/*/id` on `cleo show`) names a field omitted from every element of that list, with the summed size. A record without `_withheld` is complete. Budgeting preserves coverage, diagnostic failures, authority corrections and pending repair facts before examples. A read budget too small for mandatory facts fails explicitly; request narrower scope or more budget. Never treat this failure as clean coverage.
 
 An impossible internal mutation budget rejects before execution. If a successful mutation's actual receipt exceeds a viable budget, its success and complete receipt remain available with `_budgetEnforcement.withinBudget: false`; overflow does not mean rollback. Inspect the receipt before retrying a mutation.
 
@@ -189,7 +189,7 @@ Small legacy DBs beside large snapshots do not prove corruption. `cleo doctor su
 **FIRST CALL IS `cleo nexus status`.** Check `nodeCount`, `lastIndexedAt`, `staleFileCount`/`fileCount`. Queries report `_nexus.freshness` and auto-refresh ≤25 stale files; beyond that they warn `W_NEXUS_INDEX_STALE`. `analyze` is incremental (`--full` rebuilds). For stale coverage, refresh or inspect source with `git grep` and disclose that basis. Impact/context `E_NOT_FOUND` includes index size, median age and a repair command; inspect these first.
 
 **Project resolution**: `--project-id` > `--path` > `cwd`.
-Identity is the portable `project_id` (`.cleo/project-id`); a path is a per-device hint.
+Identity is the portable `project_id` (`.cleo/project.json`, legacy `.cleo/project-id`); a path is a per-device hint.
 
 **Rule**: BEFORE editing any symbol, run `cleo nexus impact <symbol>`.
 HIGH/CRITICAL requires reviewing affected callers before editing. For stale, partial, missing, or failed coverage, inspect source and report the remaining uncertainty. An empty footprint alone never establishes `NONE`.
@@ -303,5 +303,9 @@ All overrides append a line to `.cleo/audit/force-bypass.jsonl`. Use sparingly.
 
 A task PR merged into an integration branch is a component: `pr:<component>@<integration>` (and `ci:<component>@<integration>`) takes the merge commit and CI from the integration PR that landed it, and the task linkage and changed files from the component PR — only its files that survive the integration merge, never the whole integration diff (T12671). `cleo done` derives this from either PR number. A file a later change also edited still counts while the component's own hunks apply to the landed version. A component that only deleted files implements with `pr:<component>@<integration>;note:<deleted paths>`, because a deletion has no bytes for `files:`.
 
+### `ci:<number>` merge-commit CI atom (D11149 · T12742)
+
+With `evidence.ciSatisfies: true`, `ci:<number>` attests `testsPassed`/`qaPassed` from the required checks (`evidence.ciChecks`) green on the merged PR's merge commit, or on a final PR head whose tree equals it. When a concurrency group CANCELLED (or skipped) the merge commit's own push run, a later default-branch commit's green `push` run may stand in (T12742). That run proves the DESCENDANT's tree, not the merge tree, so it counts only when all of these hold: no merge-commit run or job failed; the PR's final head has a green latest `pull_request` run for every stood-in check; the commit descends from the merge commit and is one of the first 10 first-parent commits within 7 days; NO commit between them, merge commits included, touched the PR's changed files, a pinned workflow file or `.github/actions`; and it is the first candidate with a decisive verdict. A red first decisive candidate refuses, and a pending one refuses with "wait for <sha>"; only cancelled, skipped or never-started runs move on. The atom records `descendantSha`, `descendantRange` and `descendantPrHeadSha`, and `cleo complete` re-fetches both runs' latest attempts, because a re-run can turn a completed check red.
+
 Required checks: explicit configuration or target repository protection. `release.prRequiredWorkflows: []` requires no checks; it proves neither testing nor review. `.cleo/cache/evidence/pr-<num>.json` retains provenance and changed files; obsolete versions reject. Use `tool:test` or `test-run:<json>` plus appropriate QA tools, linking each result to verified criteria.
 <!-- /CLEO-INJECTION:section=evidence -->

package/templates/cleo-gitignore

@@ -24,6 +24,11 @@
 #   the write-once portable project identity. CLEO creates it once and never
 #   rewrites it, so git has nothing to overwrite — unlike the four mutable
 #   files above, whose hazard was git replacing live state CLEO rewrites.
+#
+# T12716 (ADR-096, amends ADR-094): `project.json` IS tracked. It holds
+#   {schemaVersion, id, name}: the same write-once id, plus the display name,
+#   which only `cleo project rename` changes. `project-id` stays tracked as the
+#   legacy id-only mirror for older builds.
 # =============================================================================
 
 # Step 1: Ignore everything in .cleo/
@@ -40,6 +45,8 @@
 # (detected project facts and bootstrap scripts — not runtime state).
 !project-context.json
 # T12325: write-once portable project identity (ADR-094, amends ADR-013 §9).
+# T12716: project.json is the canonical {id, name}; project-id its legacy mirror.
+!project.json
 !project-id
 !setup-otel.sh
 !DATA-SAFETY-IMPLEMENTATION-SUMMARY.md
@@ -75,6 +82,10 @@
 config.json
 project-info.json
 
+# Cleo Nexus project link (T12712): machine-local binding of this project to
+# a Nexus account's organization. Each clone links itself; NEVER track.
+nexus-link.json
+
 # Logs — NEVER track (append-only runtime data)
 log.json
 tasks-log.jsonl

package/templates/workflows/release-prepare.yml.tmpl

@@ -55,10 +55,23 @@ on:
           - alpha
           - rc
       skip-tests:
-        description: 'Skip the full test suite in Preflight (use when main CI is already green — avoids the 10min+ timeout). Lint and typecheck still run.'
+        description: 'Skip the Linux test shards in Preflight (use when main CI is already green for this commit — `cleo release open` sets it after checking). Lint, typecheck and build still run.'
         type: boolean
         required: false
         default: false
+      skip-macos-tests:
+        description: 'Skip the macOS test shards in Preflight (set by `cleo release open` only when the nightly macOS run for this exact commit is green).'
+        type: boolean
+        required: false
+        default: false
+      verified-sha:
+        description: 'Commit the skip-tests / skip-macos-tests decisions were verified against. REQUIRED for any skip: when empty, or when the run checks out a different commit (main moved after the check), every skip is ignored and all tests run.'
+        type: string
+        required: false
+      skip-reason:
+        description: 'Why the caller skipped test suites; recorded in the run summary.'
+        type: string
+        required: false
 
 # R-202: contents:write (commit + branch), pull-requests:write (gh pr create),
 # id-token:write (signed tags only). MUST NOT request packages:write — npm
@@ -94,7 +107,7 @@ jobs:
   # time out the preflight. Two mitigations:
   #   (a) `skip-tests` input (default false) — when the caller knows main CI
   #       is already green, tests can be skipped to avoid the redundant run.
-  #   (b) The test step is sharded across 2 parallel matrix workers, keeping
+  #   (b) The test step is sharded across 4 parallel matrix workers, keeping
   #       each shard under 10 min even without skipping.
   # T12309: a dispatch that CANNOT succeed must not cost a full preflight.
   #
@@ -113,8 +126,59 @@ jobs:
     name: Dispatch preconditions
     runs-on: ubuntu-latest
     timeout-minutes: 3
+    outputs:
+      run-linux-tests: ${{ steps.tests.outputs.linux }}
+      run-macos-tests: ${{ steps.tests.outputs.macos }}
     steps:
       - uses: actions/checkout@v4
+      # The ONE place that decides which preflight test suites run, so the
+      # test jobs and the run summary can never disagree. A skip is honoured
+      # only for the commit it was verified against: `cleo release open`
+      # checks CI for main's HEAD, and if main moves between that check and
+      # this checkout, the green result belongs to a different tree.
+      - name: Decide which preflight test suites run
+        id: tests
+        env:
+          SKIP_TESTS: ${{ inputs.skip-tests }}
+          SKIP_MACOS_TESTS: ${{ inputs.skip-macos-tests }}
+          VERIFIED_SHA: ${{ inputs.verified-sha }}
+          SKIP_REASON: ${{ inputs.skip-reason }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          linux=true
+          macos=true
+          note=""
+          skip_requested=false
+          if [ "$SKIP_TESTS" = "true" ] || [ "$SKIP_MACOS_TESTS" = "true" ]; then skip_requested=true; fi
+          if [ "$skip_requested" = "true" ] && [ -z "$VERIFIED_SHA" ]; then
+            # A skip is a claim that CI already tested THIS tree. Without the
+            # commit it was verified against, nothing ties the claim to what
+            # this run checked out, so it is refused rather than trusted.
+            note="A test skip was requested without verified-sha, so it cannot be tied to the commit this run checked out ($HEAD_SHA). Ignoring it: every suite runs."
+          elif [ -n "$VERIFIED_SHA" ] && [ "$VERIFIED_SHA" != "$HEAD_SHA" ]; then
+            note="Skips were verified against $VERIFIED_SHA, but this run checked out $HEAD_SHA (main moved after the check). Ignoring them: every suite runs."
+          else
+            if [ "$SKIP_TESTS" = "true" ]; then linux=false; fi
+            if [ "$SKIP_MACOS_TESTS" = "true" ]; then macos=false; fi
+          fi
+          echo "linux=$linux" >> "$GITHUB_OUTPUT"
+          echo "macos=$macos" >> "$GITHUB_OUTPUT"
+          describe() { if [ "$1" = "true" ]; then echo "runs"; else echo "skipped"; fi; }
+          {
+            echo "## Preflight test decision"
+            echo ""
+            echo "| suite | decision |"
+            echo "|---|---|"
+            echo "| Linux test shards | $(describe "$linux") |"
+            echo "| macOS test shards | $(describe "$macos") |"
+            echo ""
+            echo "Commit: \`$HEAD_SHA\`"
+            if [ -n "$VERIFIED_SHA" ]; then echo "Skips verified against: \`$VERIFIED_SHA\`"; fi
+            if [ -n "$SKIP_REASON" ]; then echo ""; echo "Reason: $SKIP_REASON"; fi
+            if [ -n "$note" ]; then echo ""; echo "**$note**"; fi
+          } >> "$GITHUB_STEP_SUMMARY"
+          echo "linux tests: $(describe "$linux"); macOS tests: $(describe "$macos")"
+          if [ -n "$note" ]; then echo "::warning::$note"; fi
       - name: A scoped dispatch needs a committed plan
         run: |
           if [ -n "${{ inputs.plan-blob-sha256 }}" ]; then
@@ -169,10 +233,11 @@ jobs:
         timeout-minutes: 5
 
   # T11490 — DHQ-042: test shards run in parallel to stay under 10 min.
-  # Skipped when skip-tests=true (e.g. dispatched after a green main CI).
+  # Skipped when skip-tests=true (e.g. dispatched after a green main CI for
+  # this exact commit) — see "Decide which preflight test suites run".
   preflight-test:
-    name: Preflight (test shard ${{ matrix.shard }}/2)
-    if: ${{ inputs.skip-tests != true }}
+    name: Preflight (test shard ${{ matrix.shard }}/4)
+    if: ${{ needs.dispatch-preconditions.outputs.run-linux-tests == 'true' }}
     needs: [dispatch-preconditions]
     runs-on: ubuntu-latest
     # T12309: the job ceiling has to clear the step ceiling it contains. The
@@ -182,7 +247,8 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        shard: [1, 2]
+        # 4 shards, matching ci.yml's ubuntu sweep (#1716).
+        shard: [1, 2, 3, 4]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -257,14 +323,84 @@ jobs:
         run: pnpm --filter @cleocode/studio exec svelte-kit sync
         timeout-minutes: 2
 
-      - name: Test (shard ${{ matrix.shard }}/2)
-        run: pnpm exec vitest run --shard=${{ matrix.shard }}/2
+      - name: Test (shard ${{ matrix.shard }}/4)
+        run: pnpm exec vitest run --shard=${{ matrix.shard }}/4
         # T12309: was 20, against a sweep that does not fit in it. ci.yml gives
         # the same suite 55 minutes and a shard measured 17m04s there; this step
         # timed out at 20:00 on a tree whose CI was fully green, so a release
         # could not be prepared from a release-ready commit.
         timeout-minutes: 55
 
+  # macOS runs on nightly + release instead of on every push to main, so the
+  # release is where a macOS regression must be caught before it ships. Runs
+  # even when the Linux shards are skipped, unless the nightly macOS run for
+  # this exact commit is already green (skip-macos-tests, set and verified by
+  # `cleo release open`). macOS runners are ~2x slower than Linux, hence 4
+  # shards and a generous ceiling; retry=2 matches ci.yml's macOS shards.
+  preflight-test-macos:
+    name: Preflight (macOS test shard ${{ matrix.shard }}/4)
+    if: ${{ needs.dispatch-preconditions.outputs.run-macos-tests == 'true' }}
+    needs: [dispatch-preconditions]
+    runs-on: macos-latest
+    timeout-minutes: 90
+    strategy:
+      fail-fast: true
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+        timeout-minutes: 5
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        timeout-minutes: 2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '{{NODE_VERSION}}'
+        timeout-minutes: 3
+
+      - name: Build worktree-napi native addon BEFORE pnpm install (T9982)
+        # Same reason as the Linux shards: the file: link to crates/worktree-napi
+        # only copies .node artifacts that exist at install time.
+        shell: bash
+        run: |
+          cargo build --release -p worktree-napi
+          triple="darwin-x64"
+          if [[ "$(uname -m)" == "arm64" ]]; then
+            triple="darwin-arm64"
+          fi
+          cp target/release/libworktree_napi.dylib "crates/worktree-napi/worktree-napi.${triple}.node"
+        timeout-minutes: 20
+
+      - name: Install dependencies
+        run: {{INSTALL_CMD}}
+        timeout-minutes: 10
+
+      - name: Install ripgrep (required for T1605 callsite-coverage validator)
+        uses: ./.github/actions/install-ripgrep
+
+      - name: Build cant-napi native addon for CANT tests (T12382)
+        shell: bash
+        run: pnpm --filter @cleocode/cant run build:napi
+        timeout-minutes: 20
+
+      - name: Build packages (required for cross-package imports)
+        run: {{BUILD_CMD}}
+        timeout-minutes: 15
+
+      - name: Generate SvelteKit type stubs (required for studio tests)
+        run: pnpm --filter @cleocode/studio exec svelte-kit sync
+        timeout-minutes: 2
+
+      - name: Test macOS (shard ${{ matrix.shard }}/4)
+        run: pnpm exec vitest run --shard=${{ matrix.shard }}/4 --retry=2
+        timeout-minutes: 75
+
   preflight-build:
     name: Preflight (build)
     runs-on: ubuntu-latest
@@ -303,15 +439,24 @@ jobs:
   # R-205: plan resolution → version bump → CHANGELOG → commit → push → bump-PR.
   # T11490: needs both lint/typecheck and build to pass; test shards are
   # independent (always() used so prepare can run even when tests are skipped).
+  # A skipped suite is accepted only because dispatch-preconditions decided to
+  # skip it; a failed or cancelled one blocks the bump-PR.
   prepare:
     name: Prepare bump-PR
     runs-on: ubuntu-latest
-    needs: [preflight-lint-typecheck, preflight-test, preflight-build]
+    needs:
+      - dispatch-preconditions
+      - preflight-lint-typecheck
+      - preflight-test
+      - preflight-test-macos
+      - preflight-build
     if: |
       always() &&
+      needs.dispatch-preconditions.result == 'success' &&
       needs.preflight-lint-typecheck.result == 'success' &&
       needs.preflight-build.result == 'success' &&
-      (needs.preflight-test.result == 'success' || needs.preflight-test.result == 'skipped')
+      (needs.preflight-test.result == 'success' || needs.preflight-test.result == 'skipped') &&
+      (needs.preflight-test-macos.result == 'success' || needs.preflight-test-macos.result == 'skipped')
     timeout-minutes: 20
     outputs:
       branch: ${{ steps.branch.outputs.name }}
@@ -614,6 +759,7 @@ jobs:
     needs:
       - preflight-lint-typecheck
       - preflight-test
+      - preflight-test-macos
       - preflight-build
       - prepare
     if: failure()