@cleocode/core 2026.8.8 → 2026.9.1

package/dist/doctor/index.js

@@ -26,6 +26,8 @@ export { auditInvariantRegistry } from './invariant-audit.js';
 // Epic T10327 E-INVARIANT-REGISTRY-SSOT / R6)
 export { renderInvariantAuditLines } from './invariant-audit-render.js';
 export { classifyLegacyBackup, DEFAULT_HARD_RETENTION_DAYS, DEFAULT_SOFT_RETENTION_DAYS, isLegacyBackupFilename, legacyBackupSearchRoots, pruneLegacyBackups, recommendForBackup, scanLegacyBackups, } from './legacy-backups.js';
+export { buildRecommendation, isUnitDangerous, scanLegacyReaper } from './legacy-reaper.js';
+export { scanMalformedTaskIds } from './malformed-task-ids.js';
 export { loadPragmaSsot, normalisePragmaValue, PRAGMA_VALUE_NORMALISERS, } from './pragma-ssot.js';
 export { auditSagaHierarchy } from './saga-audit.js';
 export { LIVE_STORE_FILENAME, scanSupersededStores } from './superseded-store.js';

package/dist/doctor/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/doctor/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kFAAkF;AAClF,kFAAkF;AAClF,kEAAkE;AAClE,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,yBAAyB,EACzB,2BAA2B,EAC3B,8BAA8B,EAC9B,aAAa,EACb,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,+EAA+E;AAC/E,8CAA8C;AAC9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAGxE,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGrD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElF,OAAO,EACL,iCAAiC,EACjC,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/doctor/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kFAAkF;AAClF,kFAAkF;AAClF,kEAAkE;AAClE,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,yBAAyB,EACzB,2BAA2B,EAC3B,8BAA8B,EAC9B,aAAa,EACb,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,+EAA+E;AAC/E,8CAA8C;AAC9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAGxE,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGrD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElF,OAAO,EACL,iCAAiC,EACjC,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/doctor/legacy-reaper.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Detect the legacy `cleo-mcp-reaper` host artifacts (gh#1187).
+ *
+ * ## What this looks for, and why it is dangerous
+ *
+ * During a 2026-07-01 OOM investigation a helper script and systemd user timer
+ * were applied by hand to reap leaked MCP server processes. They were never
+ * package-owned and appear nowhere in CLEO's git history, so no upgrade path
+ * has ever removed them — they simply keep running on every host that got them.
+ *
+ * The helper selects victims by `/proc/PID/comm === 'MainThread'` plus an age
+ * threshold. That is a **generic Node launcher comm**, not an MCP signature.
+ * The npm-distributed Codex CLI has a legitimate resident launcher with exactly
+ * that comm, and it deliberately forwards SIGTERM to its native child — so the
+ * reaper terminates a live Codex session cleanly, with no crash and no
+ * coredump, which is why it was first misdiagnosed as a Codex bug. Journal
+ * correlation on 2026-08-11 paired eight Codex exits with reaper kills to the
+ * second.
+ *
+ * No process-title hardening upstream can make `pgrep -x MainThread` safe: the
+ * discriminator is wrong in principle, because comm identifies a runtime, not
+ * an owner.
+ *
+ * CLEO's own {@link ../gc/janitor.ts | janitor} already does this correctly —
+ * scope/pgid as the primary discriminator, signature plus age only for
+ * unregistered processes whose stdio peers are all dead, and scope reaping
+ * restricted to `cleo-*` units inside `cleo.slice`. The canonical replacement
+ * exists; the problem is purely that the unsafe predecessor is still installed.
+ *
+ * Detection only, unless `--fix`. The helper and its journal are evidence of a
+ * real incident, so the repair **disables and masks** the units rather than
+ * deleting anything.
+ *
+ * @module
+ * @task T12131
+ */
+/**
+ * Whether a unit in this state can still fire.
+ *
+ * `masked` cannot start at all; `disabled` cannot be triggered by its own
+ * timer. Anything else that exists is still capable of killing a live session.
+ *
+ * @param fileState - systemd `UnitFileState`.
+ * @returns `true` when the unit remains dangerous.
+ */
+export declare function isUnitDangerous(fileState: string): boolean;
+/** State of one legacy systemd unit. */
+export interface LegacyUnitState {
+    /** Unit name, e.g. `cleo-mcp-reaper.timer`. */
+    readonly unit: string;
+    /** `UnitFileState` — `enabled`, `disabled`, `masked`, or `absent`. */
+    readonly fileState: string;
+    /** `ActiveState` — `active`, `inactive`, or `absent`. */
+    readonly activeState: string;
+    /** `true` when this unit can still fire. */
+    readonly dangerous: boolean;
+}
+/** Outcome of a {@link scanLegacyReaper} run. */
+export interface LegacyReaperReport {
+    /** Legacy systemd units found on this host. */
+    readonly units: readonly LegacyUnitState[];
+    /** Absolute paths of legacy helper scripts still on disk. */
+    readonly scripts: readonly string[];
+    /** `true` when at least one unit can still fire and kill a live session. */
+    readonly armed: boolean;
+    /** `true` when `--fix` ran and the units were disabled + masked. */
+    readonly remediated: boolean;
+    /** Operator-facing next step. */
+    readonly recommendation: string;
+}
+/**
+ * Scan the host for legacy `cleo-mcp-reaper` artifacts.
+ *
+ * @param opts - `fix: true` disables and masks any unit that can still fire.
+ * @returns what was found, whether it is armed, and what to do next.
+ *
+ * @example
+ * ```ts
+ * const report = scanLegacyReaper();
+ * if (report.armed) console.error('a live Codex session can be killed at any time');
+ * ```
+ *
+ * @task T12131
+ */
+export declare function scanLegacyReaper(opts?: {
+    fix?: boolean;
+}): LegacyReaperReport;
+/**
+ * Compose the operator-facing next step for a scan result.
+ *
+ * Exported so the decision logic — which distinguishes "armed", "inert" and
+ * "clean" — is testable without a systemd host. That distinction is the whole
+ * value of the check: failing on inert leftovers would train operators to
+ * ignore it, and passing on an armed timer would leave live sessions killable.
+ *
+ * @param r - the classified scan result.
+ * @returns the operator-facing next step.
+ */
+export declare function buildRecommendation(r: {
+    armed: boolean;
+    remediated: boolean;
+    units: readonly LegacyUnitState[];
+    scripts: readonly string[];
+}): string;
+//# sourceMappingURL=legacy-reaper.d.ts.map

package/dist/doctor/legacy-reaper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-reaper.d.ts","sourceRoot":"","sources":["../../src/doctor/legacy-reaper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAaH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,kBAAkB,CA+CjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GAAG,MAAM,CAsBT"}

package/dist/doctor/legacy-reaper.js

@@ -0,0 +1,151 @@
+/**
+ * Detect the legacy `cleo-mcp-reaper` host artifacts (gh#1187).
+ *
+ * ## What this looks for, and why it is dangerous
+ *
+ * During a 2026-07-01 OOM investigation a helper script and systemd user timer
+ * were applied by hand to reap leaked MCP server processes. They were never
+ * package-owned and appear nowhere in CLEO's git history, so no upgrade path
+ * has ever removed them — they simply keep running on every host that got them.
+ *
+ * The helper selects victims by `/proc/PID/comm === 'MainThread'` plus an age
+ * threshold. That is a **generic Node launcher comm**, not an MCP signature.
+ * The npm-distributed Codex CLI has a legitimate resident launcher with exactly
+ * that comm, and it deliberately forwards SIGTERM to its native child — so the
+ * reaper terminates a live Codex session cleanly, with no crash and no
+ * coredump, which is why it was first misdiagnosed as a Codex bug. Journal
+ * correlation on 2026-08-11 paired eight Codex exits with reaper kills to the
+ * second.
+ *
+ * No process-title hardening upstream can make `pgrep -x MainThread` safe: the
+ * discriminator is wrong in principle, because comm identifies a runtime, not
+ * an owner.
+ *
+ * CLEO's own {@link ../gc/janitor.ts | janitor} already does this correctly —
+ * scope/pgid as the primary discriminator, signature plus age only for
+ * unregistered processes whose stdio peers are all dead, and scope reaping
+ * restricted to `cleo-*` units inside `cleo.slice`. The canonical replacement
+ * exists; the problem is purely that the unsafe predecessor is still installed.
+ *
+ * Detection only, unless `--fix`. The helper and its journal are evidence of a
+ * real incident, so the repair **disables and masks** the units rather than
+ * deleting anything.
+ *
+ * @module
+ * @task T12131
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Systemd user units the legacy fix installed. */
+const LEGACY_UNITS = ['cleo-mcp-reaper.timer', 'cleo-mcp-reaper.service'];
+/** Helper scripts the legacy fix installed, relative to `$HOME`. */
+const LEGACY_SCRIPTS = ['.local/bin/cleo-mcp-reaper.sh', '.local/bin/cleo-mcp-reaper'];
+/**
+ * Whether a unit in this state can still fire.
+ *
+ * `masked` cannot start at all; `disabled` cannot be triggered by its own
+ * timer. Anything else that exists is still capable of killing a live session.
+ *
+ * @param fileState - systemd `UnitFileState`.
+ * @returns `true` when the unit remains dangerous.
+ */
+export function isUnitDangerous(fileState) {
+    return fileState !== 'absent' && fileState !== 'masked' && fileState !== 'disabled';
+}
+/** Read one systemd user-unit property, or `absent`. */
+function unitProperty(unit, property) {
+    const r = spawnSync('systemctl', ['--user', 'show', unit, '-p', property, '--value'], {
+        encoding: 'utf-8',
+        timeout: 5_000,
+    });
+    const value = (r.stdout ?? '').trim();
+    return value.length > 0 ? value : 'absent';
+}
+/**
+ * Scan the host for legacy `cleo-mcp-reaper` artifacts.
+ *
+ * @param opts - `fix: true` disables and masks any unit that can still fire.
+ * @returns what was found, whether it is armed, and what to do next.
+ *
+ * @example
+ * ```ts
+ * const report = scanLegacyReaper();
+ * if (report.armed) console.error('a live Codex session can be killed at any time');
+ * ```
+ *
+ * @task T12131
+ */
+export function scanLegacyReaper(opts = {}) {
+    if (process.platform !== 'linux') {
+        return {
+            units: [],
+            scripts: [],
+            armed: false,
+            remediated: false,
+            recommendation: 'Not applicable — the legacy artifact is a systemd user timer (Linux only).',
+        };
+    }
+    const home = homedir();
+    const scripts = LEGACY_SCRIPTS.map((p) => join(home, p)).filter((p) => existsSync(p));
+    const units = LEGACY_UNITS.map((unit) => {
+        const fileState = unitProperty(unit, 'UnitFileState');
+        const activeState = unitProperty(unit, 'ActiveState');
+        // Masked cannot start; disabled cannot be triggered by its own timer.
+        // Anything else that exists is still capable of firing.
+        const dangerous = fileState !== 'absent' && fileState !== 'masked' && fileState !== 'disabled';
+        return { unit, fileState, activeState, dangerous };
+    }).filter((u) => u.fileState !== 'absent');
+    // Presence is decided by UnitFileState ALONE. `systemctl show` reports
+    // `ActiveState=inactive` for a unit that does not exist at all, while
+    // `UnitFileState` comes back empty — so keying presence off ActiveState makes
+    // every clean host report two "present but inert" units and cry wolf.
+    // Verified against systemd 258: a nonexistent unit yields
+    // `UnitFileState=` and `ActiveState=inactive`.
+    const armed = units.some((u) => u.dangerous);
+    let remediated = false;
+    if (opts.fix && armed) {
+        for (const u of units.filter((x) => x.dangerous)) {
+            spawnSync('systemctl', ['--user', 'disable', '--now', u.unit], { timeout: 15_000 });
+            spawnSync('systemctl', ['--user', 'mask', u.unit], { timeout: 15_000 });
+        }
+        remediated = true;
+    }
+    return {
+        units,
+        scripts,
+        armed,
+        remediated,
+        recommendation: buildRecommendation({ armed, remediated, units, scripts }),
+    };
+}
+/**
+ * Compose the operator-facing next step for a scan result.
+ *
+ * Exported so the decision logic — which distinguishes "armed", "inert" and
+ * "clean" — is testable without a systemd host. That distinction is the whole
+ * value of the check: failing on inert leftovers would train operators to
+ * ignore it, and passing on an armed timer would leave live sessions killable.
+ *
+ * @param r - the classified scan result.
+ * @returns the operator-facing next step.
+ */
+export function buildRecommendation(r) {
+    if (r.units.length === 0 && r.scripts.length === 0) {
+        return 'Clean — no legacy cleo-mcp-reaper artifacts on this host.';
+    }
+    if (r.remediated) {
+        return ('Disabled and masked. Use `cleo janitor run` instead — it discriminates by CLEO-owned ' +
+            'scope/pgid, not by process comm. The helper script was left in place as evidence; ' +
+            'remove it by hand once you no longer need it.');
+    }
+    if (r.armed) {
+        return ('ARMED — this timer can terminate any Node process whose comm is `MainThread`, including ' +
+            'a live Codex CLI session. Run `cleo doctor legacy-reaper --fix`, or ' +
+            '`systemctl --user disable --now cleo-mcp-reaper.timer`. Use `cleo janitor run` instead.');
+    }
+    return ('Inert — the units are present but disabled or masked, so they cannot fire. No action ' +
+        'required. `cleo janitor run` is the supported replacement.');
+}
+//# sourceMappingURL=legacy-reaper.js.map

package/dist/doctor/legacy-reaper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-reaper.js","sourceRoot":"","sources":["../../src/doctor/legacy-reaper.ts"],"names":[],"mappings":"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"}

package/dist/doctor/malformed-task-ids.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `cleo doctor malformed-ids` — find and remove task rows the CLI cannot address.
+ *
+ * ## Why a doctor command rather than a normal delete
+ *
+ * A task id was written that no read path accepts. Found in a live store:
+ *
+ *     id    = '/mnt/projects/cleocode'
+ *     title = 'Task /mnt/projects/cleocode'
+ *     type  = null
+ *
+ * The row is **immortal**. `cleo list` enumerates it, but `cleo show`,
+ * `cleo update` and `cleo delete` all reject the id as malformed *before* they
+ * reach the store, so the ordinary way to remove a bad row cannot be used on
+ * precisely the rows that need removing. The validators that should have
+ * prevented the write are what make the result unfixable.
+ *
+ * T12128 closed the write path, so no new such row can be created. This closes
+ * the other half: the ones already there.
+ *
+ * ## Why deletion is the right repair
+ *
+ * A row whose id is not an id has no identity — nothing can reference it,
+ * `depends` cannot name it, and no evidence atom can cite it. Re-iding would
+ * invent an identity the row never had and silently change what any existing
+ * reference means. Deletion is honest, and the report prints the full row
+ * first so the operator sees exactly what is being discarded.
+ *
+ * Read-only by default. `--fix` is required to delete anything.
+ *
+ * @module
+ * @task T12128
+ */
+/** Rows in one table that reference a malformed id. */
+export interface DependentRows {
+    /** Table holding the references. */
+    readonly table: string;
+    /** Column holding them. */
+    readonly column: string;
+    /** How many rows reference the malformed id. */
+    readonly count: number;
+}
+/** A task row whose id does not match the canonical shape. */
+export interface MalformedTaskRow {
+    /** The malformed id, verbatim. */
+    readonly id: string;
+    /** The row's title, for operator recognition. */
+    readonly title: string | null;
+    /** The row's status. */
+    readonly status: string | null;
+    /** The row's type, frequently `null` on these rows. */
+    readonly type: string | null;
+    /** Rows in `tasks_task_dependencies` that name this id on either side. */
+    readonly dependencyRows: number;
+    /**
+     * Every reference to this id anywhere in the store, per table and column.
+     *
+     * The repair refuses while this is non-empty — see {@link scanMalformedTaskIds}.
+     */
+    readonly dependents: readonly DependentRows[];
+}
+/** Outcome of a {@link scanMalformedTaskIds} run. */
+export interface MalformedTaskIdReport {
+    /** Every row whose id fails {@link isStorableTaskId}. */
+    readonly rows: readonly MalformedTaskRow[];
+    /** `true` when `--fix` ran and rows were deleted. */
+    readonly deleted: boolean;
+    /**
+     * Ids `--fix` REFUSED to delete because other tables reference them.
+     *
+     * Deleting a malformed row while leaving its references behind manufactures
+     * exactly the violation `cleo doctor fk-check` exists to detect — one doctor
+     * creating work for another. Found on real data: the single malformed row in
+     * this repository's own store has a dependent row in
+     * `tasks_lifecycle_pipelines`, a table with no declared foreign key.
+     *
+     * A blanket cascade is not the answer either: 18 tables hold a task id, and
+     * they include `tasks_audit_log` and `tasks_task_work_history`, which are
+     * evidence. Deleting the audit trail of a bad row destroys the record of how
+     * it got there. Which references are safe to remove is an operator judgement,
+     * so the repair reports them and stops.
+     */
+    readonly refused: readonly string[];
+}
+/**
+ * Find task rows whose id could not be an identifier at all.
+ *
+ * Uses {@link isStorableTaskId}, NOT the canonical {@link isTaskId}. That
+ * distinction is load-bearing: CLEO deliberately mints structured ids such as
+ * `T-RECONCILE-FOLLOWUP-v2026.5.63-6` (see `archive-reason-invariant.ts`) which
+ * the canonical pattern rejects. Reporting those here would be wrong, and
+ * `--fix` would DELETE working release follow-up tasks.
+ *
+ * @param cwd - project root.
+ * @param opts - `fix: true` deletes rows that nothing references; default is
+ *               read-only. Rows WITH references are never deleted — see
+ *               {@link MalformedTaskIdReport.refused}.
+ * @returns the rows found, their references, and what was deleted or refused.
+ *
+ * @example
+ * ```ts
+ * const report = await scanMalformedTaskIds(projectRoot);
+ * if (report.rows.length > 0) console.error('unaddressable rows present');
+ * ```
+ *
+ * @task T12128
+ */
+export declare function scanMalformedTaskIds(cwd: string, opts?: {
+    fix?: boolean;
+}): Promise<MalformedTaskIdReport>;
+//# sourceMappingURL=malformed-task-ids.d.ts.map

package/dist/doctor/malformed-task-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"malformed-task-ids.d.ts","sourceRoot":"","sources":["../../src/doctor/malformed-task-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAwBH,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;CAC/C;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC3C,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3B,OAAO,CAAC,qBAAqB,CAAC,CA+EhC"}

package/dist/doctor/malformed-task-ids.js

@@ -0,0 +1,139 @@
+/**
+ * `cleo doctor malformed-ids` — find and remove task rows the CLI cannot address.
+ *
+ * ## Why a doctor command rather than a normal delete
+ *
+ * A task id was written that no read path accepts. Found in a live store:
+ *
+ *     id    = '/mnt/projects/cleocode'
+ *     title = 'Task /mnt/projects/cleocode'
+ *     type  = null
+ *
+ * The row is **immortal**. `cleo list` enumerates it, but `cleo show`,
+ * `cleo update` and `cleo delete` all reject the id as malformed *before* they
+ * reach the store, so the ordinary way to remove a bad row cannot be used on
+ * precisely the rows that need removing. The validators that should have
+ * prevented the write are what make the result unfixable.
+ *
+ * T12128 closed the write path, so no new such row can be created. This closes
+ * the other half: the ones already there.
+ *
+ * ## Why deletion is the right repair
+ *
+ * A row whose id is not an id has no identity — nothing can reference it,
+ * `depends` cannot name it, and no evidence atom can cite it. Re-iding would
+ * invent an identity the row never had and silently change what any existing
+ * reference means. Deletion is honest, and the report prints the full row
+ * first so the operator sees exactly what is being discarded.
+ *
+ * Read-only by default. `--fix` is required to delete anything.
+ *
+ * @module
+ * @task T12128
+ */
+import { isStorableTaskId } from '@cleocode/contracts';
+import { sql } from 'drizzle-orm';
+import { openDualScopeDb } from '../store/dual-scope-db.js';
+/**
+ * Columns that hold a task id, by convention across the prefixed schema.
+ *
+ * Discovery is deliberately convention-based rather than FK-based. Only 11 of
+ * the 18 referencing tables declare a foreign key to `tasks_tasks` — and
+ * `tasks_lifecycle_pipelines`, which holds the dependent of the one malformed
+ * row actually present in this repository's store, is **not** one of them. A
+ * FK-only sweep would have reported "no dependents" for the live case.
+ */
+const TASK_ID_COLUMNS = [
+    'task_id',
+    'depends_on',
+    'related_to',
+    'target_task_id',
+    'parent_id',
+    'current_task',
+];
+/**
+ * Find task rows whose id could not be an identifier at all.
+ *
+ * Uses {@link isStorableTaskId}, NOT the canonical {@link isTaskId}. That
+ * distinction is load-bearing: CLEO deliberately mints structured ids such as
+ * `T-RECONCILE-FOLLOWUP-v2026.5.63-6` (see `archive-reason-invariant.ts`) which
+ * the canonical pattern rejects. Reporting those here would be wrong, and
+ * `--fix` would DELETE working release follow-up tasks.
+ *
+ * @param cwd - project root.
+ * @param opts - `fix: true` deletes rows that nothing references; default is
+ *               read-only. Rows WITH references are never deleted — see
+ *               {@link MalformedTaskIdReport.refused}.
+ * @returns the rows found, their references, and what was deleted or refused.
+ *
+ * @example
+ * ```ts
+ * const report = await scanMalformedTaskIds(projectRoot);
+ * if (report.rows.length > 0) console.error('unaddressable rows present');
+ * ```
+ *
+ * @task T12128
+ */
+export async function scanMalformedTaskIds(cwd, opts = {}) {
+    const { db } = await openDualScopeDb('project', cwd);
+    // Every prefixed table holding a task-id-shaped column. Discovered from the
+    // live schema rather than hardcoded, so a table added later is covered
+    // automatically — the failure mode of a stale list here is a silent partial
+    // repair, which is the very thing this command exists to avoid.
+    const schemaRows = (await db.all(sql `SELECT m.name AS tbl, i.name AS col
+        FROM sqlite_master AS m
+        JOIN pragma_table_info(m.name) AS i
+        WHERE m.type = 'table' AND m.name LIKE 'tasks_%'`));
+    const refs = schemaRows
+        .map((r) => ({ table: String(r.tbl), column: String(r.col) }))
+        .filter((r) => TASK_ID_COLUMNS.includes(r.column));
+    const all = (await db.all(sql `SELECT id, title, status, type FROM tasks_tasks`));
+    const rows = [];
+    for (const raw of all) {
+        if (isStorableTaskId(raw.id))
+            continue;
+        const id = String(raw.id);
+        const dependents = [];
+        for (const { table, column } of refs) {
+            // `tasks_tasks.id` is the row itself, not a reference to it.
+            if (table === 'tasks_tasks' && column !== 'parent_id')
+                continue;
+            const hit = (await db.all(sql `SELECT COUNT(*) AS c FROM ${sql.identifier(table)}
+            WHERE ${sql.identifier(column)} = ${id}`));
+            const count = hit[0]?.c ?? 0;
+            if (count > 0)
+                dependents.push({ table, column, count });
+        }
+        rows.push({
+            id,
+            title: raw.title == null ? null : String(raw.title),
+            status: raw.status == null ? null : String(raw.status),
+            type: raw.type == null ? null : String(raw.type),
+            dependencyRows: dependents
+                .filter((d) => d.table === 'tasks_task_dependencies')
+                .reduce((n, d) => n + d.count, 0),
+            dependents,
+        });
+    }
+    let deleted = false;
+    const refused = rows.filter((r) => r.dependents.length > 0);
+    if (opts.fix && rows.length > 0 && refused.length === 0) {
+        // One transaction: a partially-repaired store is worse than an unrepaired
+        // one, because the operator would then have to re-derive which rows were
+        // left behind — and these are the rows no query can name.
+        await db.run(sql `BEGIN`);
+        try {
+            for (const row of rows) {
+                await db.run(sql `DELETE FROM tasks_tasks WHERE id = ${row.id}`);
+            }
+            await db.run(sql `COMMIT`);
+            deleted = true;
+        }
+        catch (err) {
+            await db.run(sql `ROLLBACK`);
+            throw err;
+        }
+    }
+    return { rows, deleted, refused: refused.map((r) => r.id) };
+}
+//# sourceMappingURL=malformed-task-ids.js.map

package/dist/doctor/malformed-task-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"malformed-task-ids.js","sourceRoot":"","sources":["../../src/doctor/malformed-task-ids.ts"],"names":[],"mappings":"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"}

package/dist/doctor/nexus-schema-residency.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Assert the schema-residency invariant that nexus silently depends on.
+ *
+ * ## The invariant nobody wrote down (gh#1298 · gh#1283)
+ *
+ * `ensureGlobalRegistryAttached()` ATTACHes the global `cleo.db` onto the
+ * PROJECT handle as `nexus_global`, so that nexus registry tables resolve by
+ * their BARE names through SQLite's fall-through. Its own comment states the
+ * split:
+ *
+ *   > graph tables resolve to the project `main`; registry/identity tables fall
+ *   > through to the attach.
+ *
+ * That split is correct **only while each bare name exists in exactly one of the
+ * two schemas.** SQLite resolves an unqualified name by searching `temp`, then
+ * `main`, then attached schemas in attach order — so a table present in BOTH is
+ * answered by `main` with no error and no cue. Nexus is therefore correct today
+ * **by resolution order, not by the invariant it documents**, and nothing fails
+ * if that stops being true.
+ *
+ * ## It is already half-false
+ *
+ * ADR-090 / T11538 moved the four code-graph tables (`nexus_nodes`,
+ * `nexus_relations`, `nexus_contracts`, `nexus_code_index`) into the project
+ * scope, and T11539 removed them from the global schema source. **No migration
+ * drops them from a database that already has them** — removing a table from a
+ * schema module does not remove it from disk. So a global `cleo.db` created
+ * before that change still carries all four, at 0 rows, shadowing the populated
+ * project copies.
+ *
+ * Measured 2026-09-12: project `nexus_nodes` = 26,964 and `nexus_relations` =
+ * 75,500; the global copies are present and empty. Today the right side wins
+ * because `main` is the project. If anything ever reads them from a handle
+ * whose `main` is the GLOBAL store, it gets **0 rows — an empty graph,
+ * indistinguishable from "nothing has been indexed yet"**, which is precisely
+ * the symptom this project has already lost a session to.
+ *
+ * ## Why this reports rather than repairs
+ *
+ * A blind `DROP TABLE` would be wrong. This install's global copies are empty,
+ * but an install that used nexus BEFORE the residency move wrote its graph
+ * rows to the global store, and no migration relocated them. There, the four
+ * tables may hold the only copy. Dropping on the strength of one machine's
+ * measurement is the same error as inferring a rule from the rows it is then
+ * used to exempt.
+ *
+ * So this scan reports `safeToDrop` per table, and only ever for an EMPTY one.
+ * A populated orphan is a data-migration question for the owner, not a cleanup.
+ *
+ * @task T12158
+ * @see ADR-090 §2.1 — nexus graph residency
+ * @see ADR-092 — failure geometries
+ */
+/**
+ * Tables nexus resolves by BARE name through the `nexus_global` attach.
+ *
+ * Each MUST exist in exactly one of the two schemas. Sourced from
+ * `schema/cleo-global/nexus.ts`, which is their only declaration.
+ */
+export declare const NEXUS_FALLTHROUGH_TABLES: readonly ["nexus_audit_log", "nexus_project_id_aliases", "nexus_project_registry", "nexus_sigils", "nexus_user_profile"];
+/**
+ * Code-graph tables that moved to the project scope under ADR-090 / T11538.
+ *
+ * They must NOT be present in the global store. Any that are, are orphans left
+ * by a schema removal that never became a migration.
+ */
+export declare const NEXUS_PROJECT_GRAPH_TABLES: readonly ["nexus_code_index", "nexus_contracts", "nexus_nodes", "nexus_relations"];
+/** One table that is resident where it should not be. */
+export interface NexusResidencyFinding {
+    /** The table name. */
+    readonly table: string;
+    /** What is wrong with where it lives. */
+    readonly kind: 'orphaned-in-global' | 'ambiguous-fallthrough';
+    /** Rows in the offending copy. */
+    readonly rows: number;
+    /**
+     * Whether removing the offending copy is provably lossless.
+     *
+     * Only ever `true` for an empty table. A populated orphan may hold the only
+     * copy on an install that predates the residency move, so it is a migration
+     * question rather than a cleanup.
+     */
+    readonly safeToDrop: boolean;
+}
+/** The result of a residency audit. */
+export interface NexusResidencyScanResult {
+    /** Absolute path of the project store. */
+    readonly projectStorePath: string;
+    /** Absolute path of the global store. */
+    readonly globalStorePath: string;
+    /** `false` when either store is missing; findings are then empty. */
+    readonly bothStoresExist: boolean;
+    /** Tables resident where they should not be. */
+    readonly findings: readonly NexusResidencyFinding[];
+    /** Findings whose removal is provably lossless. */
+    readonly safeToDropCount: number;
+    /**
+     * Findings that are NOT safe to drop — a populated orphan, or a bare name
+     * that resolves in two schemas. These need a decision, not a cleanup.
+     */
+    readonly needsDecisionCount: number;
+}
+/**
+ * Audit where the nexus tables actually live, against where they must live.
+ *
+ * Read-only — opens both stores as snapshots and writes nothing.
+ *
+ * @param projectRoot - absolute path to the project root.
+ * @param cleoHome - absolute path to the global cleo home.
+ * @returns the audit; `findings` is empty when residency is correct.
+ *
+ * @task T12158
+ */
+export declare function scanNexusSchemaResidency(projectRoot: string, cleoHome: string): NexusResidencyScanResult;
+//# sourceMappingURL=nexus-schema-residency.d.ts.map