@cleocode/core 2026.9.20 → 2026.9.22

package/migrations/drizzle-cleo-global/20260928010000_t12470-location-candidates/migration.sql

@@ -0,0 +1,72 @@
+-- T12470 — a checkout that merely DECLARES an existing project id is a
+-- `candidate` location, never a live one (drizzle-cleo-global scope ONLY).
+--
+-- `.cleo/project-id` is committed to git (ADR-094), so any directory can
+-- declare any project's id. The state set gains `candidate`: a location seen
+-- but not confirmed. Only an explicit command (`cleo init`, `cleo nexus
+-- register`, `cleo doctor project-identity --resolve`) or a proven move
+-- promotes it.
+--
+-- Three nullable columns:
+--   `checkout_nonce`  — random per-checkout secret kept in the checkout's
+--                       UNTRACKED `.cleo/project-info.json`. A real move or a
+--                       restore of `.cleo/` carries it; a clone cannot. The
+--                       ONLY evidence that proves a move.
+--   `git_root_commit` — first (parentless) commit; displayed evidence only.
+--   `git_remote`      — normalised `origin` URL; displayed evidence only.
+--
+-- ## Detectability (why ADD COLUMN comes first)
+--
+-- The journal reconciler marks an un-journaled migration applied when its DDL
+-- targets already exist. A pure rebuild's only target is the final table name,
+-- which every T12469 store already has — so a rebuild-only migration would be
+-- journaled WITHOUT running. The three `ADD COLUMN` statements are the probe
+-- targets: on a T12469 store they are missing, so this migration runs. Drizzle
+-- applies a migration inside one transaction, so the columns and the rebuilt
+-- CHECK below land together or not at all.
+--
+-- SQLite cannot alter a CHECK in place, so after the columns are added the
+-- table is rebuilt (create `_new`, copy every row verbatim, drop, rename) and
+-- its index recreated.
+--
+-- Statements are separated by drizzle breakpoint marker lines (the literal
+-- token is not spelled out here; drizzle's readMigrationFiles splits on it).
+--
+-- @task T12470
+-- @adr ADR-094
+
+ALTER TABLE `nexus_project_locations` ADD COLUMN `checkout_nonce` text;
+--> statement-breakpoint
+ALTER TABLE `nexus_project_locations` ADD COLUMN `git_root_commit` text;
+--> statement-breakpoint
+ALTER TABLE `nexus_project_locations` ADD COLUMN `git_remote` text;
+--> statement-breakpoint
+CREATE TABLE `nexus_project_locations_t12470_new` (
+	`project_id` text NOT NULL,
+	`device_id` text NOT NULL,
+	`path` text NOT NULL,
+	`first_seen` text NOT NULL DEFAULT (datetime('now')),
+	`last_seen` text NOT NULL DEFAULT (datetime('now')),
+	`state` text NOT NULL DEFAULT 'live',
+	`checkout_nonce` text,
+	`git_root_commit` text,
+	`git_remote` text,
+	PRIMARY KEY (`project_id`, `device_id`, `path`),
+	CHECK ("state" IN ('live', 'missing', 'superseded', 'candidate')),
+	CHECK ("first_seen" IS NULL OR "first_seen" GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*'),
+	CHECK ("last_seen" IS NULL OR "last_seen" GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*')
+);
+--> statement-breakpoint
+INSERT INTO `nexus_project_locations_t12470_new` (
+	`project_id`, `device_id`, `path`, `first_seen`, `last_seen`, `state`,
+	`checkout_nonce`, `git_root_commit`, `git_remote`
+)
+SELECT `project_id`, `device_id`, `path`, `first_seen`, `last_seen`, `state`,
+	`checkout_nonce`, `git_root_commit`, `git_remote`
+FROM `nexus_project_locations`;
+--> statement-breakpoint
+DROP TABLE `nexus_project_locations`;
+--> statement-breakpoint
+ALTER TABLE `nexus_project_locations_t12470_new` RENAME TO `nexus_project_locations`;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `idx_nexus_project_locations_device_path` ON `nexus_project_locations` (`device_id`, `path`);

package/migrations/drizzle-cleo-global/20260928020000_t12510-nexus-devices/migration.sql

@@ -0,0 +1,34 @@
+-- T12510 — `nexus_devices`: one row per machine that runs CLEO against this
+-- global store, so `nexus_project_locations.device_id` (T12469) resolves to a
+-- hostname / OS / architecture / CLEO version and a last-heartbeat instant.
+--
+-- `device_id` is the persisted `<cleoHome>/device-id` UUID (getStableDeviceId,
+-- T9321) — the same id the location rows carry. The CLI upserts this device's
+-- row at most once per minute (nexus/devices.ts `recordDeviceHeartbeat`).
+--
+-- ## Journal probe (T12541)
+--
+-- A pure CREATE TABLE + CREATE INDEX: the migration-manager DDL probe sees the
+-- missing table on a store at main's state and lets drizzle run this file, and
+-- sees the present table (and index) on a store that already has it and marks
+-- the journal entry applied without re-running it. IF NOT EXISTS keeps a
+-- re-run harmless either way. No data is touched.
+--
+-- Timestamp is after T12470's 20260928010000 so the two never collide.
+--
+-- @task T12510
+-- @epic T12496
+
+CREATE TABLE IF NOT EXISTS `nexus_devices` (
+	`device_id` text PRIMARY KEY NOT NULL,
+	`hostname` text NOT NULL,
+	`os` text NOT NULL,
+	`arch` text NOT NULL,
+	`cleo_version` text NOT NULL,
+	`first_seen` text NOT NULL DEFAULT (datetime('now')),
+	`last_heartbeat_at` text NOT NULL DEFAULT (datetime('now')),
+	CHECK ("first_seen" IS NULL OR "first_seen" GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*'),
+	CHECK ("last_heartbeat_at" IS NULL OR "last_heartbeat_at" GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*')
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `idx_nexus_devices_last_heartbeat` ON `nexus_devices` (`last_heartbeat_at`);

package/migrations/drizzle-cleo-global/20260928030000_t12511-project-git-state/migration.sql

@@ -0,0 +1,62 @@
+-- T12511 — `nexus_project_git_state`: the last git state probe of each project
+-- location, keyed exactly like `nexus_project_locations` (T12469) —
+-- (project_id, device_id, path) — so every device sharing this store can see
+-- where a project lives, on which machine, and its local and remote git state.
+--
+-- Written by `cleo nexus projects status` (nexus/git-state.ts). A failed probe
+-- still writes its row with `probe_error_code` set. Remote columns describe the
+-- remote as of `remote_fetched_at` (FETCH_HEAD's mtime), never "now": the probe
+-- runs no `git fetch` unless `--fetch` is passed.
+--
+-- A separate table rather than columns on `nexus_project_locations`: location
+-- rows are identity/liveness facts written on every encounter, while probe rows
+-- are volatile observations rewritten wholesale by one command. Keeping them
+-- apart means a probe never races an encounter write on the same row.
+--
+-- ## Journal probe (T12541)
+--
+-- A pure CREATE TABLE + CREATE INDEX: on a store at main's state the DDL probe
+-- sees the missing table and lets drizzle run this file; on a store that has it
+-- the entry is marked applied. IF NOT EXISTS keeps a re-run harmless. No data
+-- is touched.
+--
+-- CHECK constraints are written exactly as the schema derives them (T11364
+-- parity). A NULL `probe_error_code` passes the IN check, because a CHECK
+-- rejects only FALSE.
+--
+-- Timestamp is after T12510's 20260928020000 so the two never collide.
+--
+-- @task T12511
+-- @epic T12496
+
+CREATE TABLE IF NOT EXISTS `nexus_project_git_state` (
+	`project_id` text NOT NULL,
+	`device_id` text NOT NULL,
+	`path` text NOT NULL,
+	`git_root` text,
+	`branch` text,
+	`head_sha` text,
+	`detached` integer DEFAULT false NOT NULL,
+	`shallow` integer DEFAULT false NOT NULL,
+	`dirty_count` integer,
+	`untracked_count` integer,
+	`upstream` text,
+	`ahead` integer,
+	`behind` integer,
+	`remote_name` text,
+	`remote_url` text,
+	`remote_head_sha` text,
+	`remote_fetched_at` text,
+	`probed_at` text NOT NULL,
+	`duration_ms` integer DEFAULT 0 NOT NULL,
+	`probe_error_code` text,
+	`probe_error` text,
+	PRIMARY KEY (`project_id`, `device_id`, `path`),
+	CHECK ("detached" IN (0, 1)),
+	CHECK ("shallow" IN (0, 1)),
+	CHECK ("probe_error_code" IN ('E_PATH_MISSING', 'E_PATH_ACCESS', 'E_NOT_GIT_REPO', 'E_GIT_TIMEOUT', 'E_GIT_FAILED', 'E_FETCH_FAILED')),
+	CHECK ("remote_fetched_at" IS NULL OR "remote_fetched_at" GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*'),
+	CHECK ("probed_at" IS NULL OR "probed_at" GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*')
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `idx_nexus_project_git_state_device` ON `nexus_project_git_state` (`device_id`);

package/migrations/drizzle-cleo-project/20260927000000_t12499-session-terminal-bindings/migration.sql

@@ -0,0 +1,34 @@
+-- T12499 (E-MULTI-SESSION · epic T12497) — terminal-bound session identity.
+--
+-- One row per terminal / harness identity key (CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID,
+-- TMUX_PANE, TERM_SESSION_ID, WT_SESSION, … or the ppid-chain fallback), mapping it to
+-- the CLEO session that terminal started. `cleo session start` upserts the row;
+-- session resolution reads it BEFORE the newest-active-row fallback, so an unbound
+-- short-lived `cleo` call no longer resolves another agent's session.
+--
+-- PROJECT scope only: sessions live in the project `tasks_sessions` table, so the
+-- binding lives beside it and is never mirrored into the global cleo.db (no
+-- dual-scope ambiguity for gate 21). Pure runtime infrastructure, like `schedules`
+-- (T11962) — NOT part of the exodus target shape under `schema/cleo-project/`.
+--
+-- `session_id` is an intra-DB foreign key to `tasks_sessions.id` (same project cleo.db),
+-- ON DELETE CASCADE, so deleting a session removes its bindings. Resolution still
+-- re-checks that the bound session is active before honouring a binding.
+--
+-- `IF NOT EXISTS` so a re-open over an already-migrated DB is a no-op. Statements are
+-- separated by the drizzle breakpoint marker line so node:sqlite prepare() does not
+-- truncate the multi-statement file to statement one (the marker token is not spelled
+-- out in this comment — readMigrationFiles splits on that literal substring).
+--
+-- @task T12499
+-- @epic T12497
+
+CREATE TABLE IF NOT EXISTS `session_terminal_bindings` (
+  `binding_key` TEXT PRIMARY KEY NOT NULL,
+  `key_source` TEXT NOT NULL,
+  `key_kind` TEXT NOT NULL,
+  `session_id` TEXT NOT NULL REFERENCES `tasks_sessions`(`id`) ON DELETE CASCADE,
+  `bound_at` TEXT NOT NULL DEFAULT (datetime('now'))
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `ix_session_terminal_bindings_session` ON `session_terminal_bindings` (`session_id`);

package/migrations/drizzle-cleo-project/20260928000000_t12500-binding-provider-flag/migration.sql

@@ -0,0 +1,15 @@
+-- T12500 (E-MULTI-SESSION · epic T12497) — who wrote a terminal binding.
+--
+-- `bound_by_provider` = 1 when the binding was written by an explicit session
+-- start / resume / switch from a process that carried an agent-harness identity
+-- (CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID, …). A tab- or ppid-level binding
+-- written by a HUMAN (no provider key) stays 0, and only such a binding may be
+-- adopted by an agent running in the same tab — so a tab-started session is
+-- visible from Claude Code in that tab, while two Claude instances that each
+-- started their own session stay isolated. A provider row written by that
+-- adoption is also 0 (adopted, not owned).
+--
+-- @task T12500
+-- @epic T12497
+
+ALTER TABLE `session_terminal_bindings` ADD COLUMN `bound_by_provider` INTEGER NOT NULL DEFAULT 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.9.20",
+  "version": "2026.9.22",
   "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"
     },
+    "./decide/*": {
+      "types": "./dist/decide/*.d.ts",
+      "import": "./dist/decide/*.js",
+      "require": "./dist/decide/*.js"
+    },
+    "./decide/*.js": {
+      "types": "./dist/decide/*.d.ts",
+      "import": "./dist/decide/*.js",
+      "require": "./dist/decide/*.js"
+    },
     "./resources/*": {
       "types": "./dist/resources/*.d.ts",
       "import": "./dist/resources/*.js",
@@ -471,16 +481,16 @@
     "write-file-atomic": "^7.0.1",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@cleocode/agents": "2026.9.20",
-    "@cleocode/contracts": "2026.9.20",
-    "@cleocode/adapters": "2026.9.20",
-    "@cleocode/git-shim": "2026.9.20",
-    "@cleocode/lafs": "2026.9.20",
-    "@cleocode/nexus": "2026.9.20",
-    "@cleocode/paths": "2026.9.20",
-    "@cleocode/caamp": "2026.9.20",
-    "@cleocode/skills": "2026.9.20",
-    "@cleocode/worktree": "2026.9.20"
+    "@cleocode/adapters": "2026.9.22",
+    "@cleocode/agents": "2026.9.22",
+    "@cleocode/caamp": "2026.9.22",
+    "@cleocode/contracts": "2026.9.22",
+    "@cleocode/git-shim": "2026.9.22",
+    "@cleocode/nexus": "2026.9.22",
+    "@cleocode/lafs": "2026.9.22",
+    "@cleocode/paths": "2026.9.22",
+    "@cleocode/worktree": "2026.9.22",
+    "@cleocode/skills": "2026.9.22"
   },
   "engines": {
     "node": ">=24.16.0"
@@ -506,7 +516,7 @@
     "@types/proper-lockfile": "^4.1.4",
     "@types/tar": "^6.1.13",
     "@types/write-file-atomic": "^4.0.3",
-    "@cleocode/utils": "2026.9.20"
+    "@cleocode/utils": "2026.9.22"
   },
   "repository": {
     "type": "git",
@@ -515,7 +525,7 @@
   },
   "optionalDependencies": {
     "llmtxt": "^2026.5.15",
-    "@cleocode/studio": "^2026.9.20"
+    "@cleocode/studio": "^2026.9.22"
   },
   "scripts": {
     "build": "tsc && node scripts/copy-selfimprove-fixtures.mjs",

package/schemas/config.schema.json

@@ -1181,6 +1181,60 @@
         }
       }
     },
+    "decide": {
+      "type": "object",
+      "description": "Typed 'System One' decisions (T12486). The provider itself (URL + API key) is stored by `cleo decide config` in <cleoHome>/decide-credentials.json, never here. These keys only choose how each call site uses it.",
+      "additionalProperties": false,
+      "properties": {
+        "sites": {
+          "type": "object",
+          "description": "Per call-site mode.",
+          "additionalProperties": false,
+          "properties": {
+            "duplicateDetection": {
+              "type": "string",
+              "enum": ["off", "shadow", "on"],
+              "default": "shadow",
+              "description": "`cleo add` duplicate detection (T12492). shadow = ask the provider, audit its answers next to the heuristic's in .cleo/audit/decisions.jsonl, act on the heuristic. on = act on the provider's answer. off = never ask. Always off when no provider is configured."
+            },
+            "decisionContradiction": {
+              "type": "string",
+              "enum": ["off", "shadow", "on"],
+              "default": "shadow",
+              "description": "ADR decision contradiction check on `storeDecision` writes that request model validation (T12493). One choice question per prior decision (contradicts | supersedes | refines | unrelated), top 3 by word overlap, 300 ms budget. shadow = ask, audit next to the heuristic, act on the heuristic. on = act on the answers when every confidence is >= 0.6. off = never ask. Always off when no provider is configured."
+            },
+            "observationType": {
+              "type": "string",
+              "enum": ["off", "shadow", "on"],
+              "default": "shadow",
+              "description": "Observation type when `cleo memory observe` gets no `type` (T12494). Only callers that opt in (`askTypeDecision`) ask; background writers never send content to the provider. One choice question over bugfix | refactor | feature | decision | change | discovery, 300 ms budget. shadow = ask, audit next to the whole-word keyword type, store the keyword type. on = store the decided type when its confidence is >= 0.6. off = never ask. Always off when no provider is configured."
+            },
+            "ownerDecision": {
+              "type": "string",
+              "enum": ["off", "shadow", "on"],
+              "default": "shadow",
+              "description": "Readiness grill gate (`cleo classify`, sentient auto-promote) for a task with a `blockedBy` reason and no `owner-decision` label (T12494). One noul question: does the block need a human owner's decision? 300 ms budget. shadow = ask, audit next to the `owner`/`decision` substring rule, act on the rule. on = a confident (>= 0.6) yes ADDS the flag the substring rule missed; escalate-only, it never clears a flag the rule or the label raised. It only flags: a flagged task grills and goes to the owner through the ask tool. off = never ask. Always off when no provider is configured."
+            }
+          }
+        },
+        "generativeFallback": {
+          "type": "object",
+          "description": "Opt-ins for the older generative-LLM tiers that System One replaces.",
+          "additionalProperties": false,
+          "properties": {
+            "duplicateDetection": {
+              "type": "boolean",
+              "default": false,
+              "description": "Run the T1681 generative-LLM duplicate check (up to 15 s on the `cleo add` write path). Off by default."
+            },
+            "decisionContradiction": {
+              "type": "boolean",
+              "description": "Run the T1828 generative-LLM decision contradiction check (up to 15 s on the decision write path, backend resolution included). When unset: on unless decide.sites.decisionContradiction is `on` — unconfigured, off and shadow keep the pre-T12493 behaviour; only `on` replaces it."
+            }
+          }
+        }
+      }
+    },
     "llm": {
       "type": "object",
       "description": "LLM configuration — default provider+model, per-provider API key overrides, and role-based routing. T-LLM-CRED-CENTRALIZATION Phase 4 (T9306).",

package/schemas/project-context.schema.json

@@ -55,6 +55,11 @@
           "type": "string",
           "description": "Test execution command"
         },
+        "affectedCommand": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Affected-scope test command template for tool:test-affected (D11150). {projects}, {filters} and {packages} expand per affected package, e.g. \"pnpm exec vitest run {projects}\"."
+        },
         "testFilePatterns": {
           "type": "array",
           "items": {
@@ -221,11 +226,32 @@
         "prRequiredWorkflows": {
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["name"],
+                "properties": {
+                  "name": { "type": "string", "minLength": 1 },
+                  "app": {
+                    "oneOf": [
+                      { "type": "string", "minLength": 1 },
+                      { "type": "integer", "minimum": 1 }
+                    ],
+                    "description": "GitHub App slug or id that must post this check."
+                  },
+                  "workflow": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Workflow file path that must produce this check."
+                  }
+                }
+              }
+            ]
           },
           "uniqueItems": true,
-          "description": "Required successful checks for PR evidence atoms."
+          "description": "Required successful checks for PR and CI evidence atoms. An object entry pins the check to the GitHub App (and workflow file) that must post it (T12634)."
         }
       }
     },
@@ -238,6 +264,28 @@
           "type": "string",
           "minLength": 1,
           "description": "Checkout that git/gh evidence tools run in, relative to the CLEO store root (absolute is also accepted). Needed only when the store root is not itself a git work tree and parents more than one repository."
+        },
+        "ciSatisfies": {
+          "type": "boolean",
+          "description": "Accept required CI green on a merged PR's merge commit as testsPassed/qaPassed evidence (ci:<pr>, D11149)."
+        },
+        "ciChecks": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tests": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 },
+            "qa": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 },
+            "jobs": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Job-name globs (* wildcard) that must each have run and succeeded in the pinned workflows before ci:<pr> attests a code task's gate.",
+              "properties": {
+                "tests": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 },
+                "qa": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }
+              }
+            }
+          },
+          "description": "Required checks that attest testsPassed (tests) and qaPassed (qa) for ci:<pr>; each must be a subset of the required list."
         }
       }
     }

package/schemas/project-info.schema.json

@@ -23,10 +23,37 @@
       "minLength": 1,
       "description": "Portable project-local identity (UUIDv4). Survives .cleo/ moves between filesystems. Used as the stable brain key for cross-system project sharing."
     },
+    "checkoutNonce": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$",
+      "description": "Random per-checkout secret (T12470). Lives only in this untracked file; the global registry records it on each confirmed location, so a moved or restored checkout is recognised while a clone (which cannot have it) stays an unconfirmed candidate. Never copy it between checkouts."
+    },
     "projectHash": {
       "type": "string",
       "pattern": "^[a-f0-9]{12}$",
-      "description": "Path-derived 12-character hex hash (SHA-256 prefix of absolute project path). Links to global nexus registry entry. Re-computed on project move."
+      "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)."
+    },
+    "previousProjectIds": {
+      "type": "array",
+      "maxItems": 50,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Local ids this project was re-keyed away from by `cleo doctor project-identity --resolve` (T12353). Receipt only; they stay resolvable through the registry alias table."
+    },
+    "strippedFields": {
+      "type": "array",
+      "maxItems": 50,
+      "description": "Receipt of persisted path facts removed by `cleo doctor project-identity --resolve` (T12557), newest last.",
+      "items": {
+        "type": "object",
+        "required": ["file", "field", "value", "strippedAt"],
+        "additionalProperties": false,
+        "properties": {
+          "file": { "type": "string", "enum": ["project-info.json", "project-context.json"] },
+          "field": { "type": "string", "enum": ["projectRoot"] },
+          "value": { "description": "The removed value, verbatim." },
+          "strippedAt": { "type": "string", "format": "date-time" }
+        }
+      }
     },
     "name": {
       "type": "string",