@cleocode/core 2026.4.98 → 2026.4.99

package/dist/sentient/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @cleocode/core/sentient — Tier-1/Tier-2 sentient daemon public API.
+ *
+ * Provides the autonomous loop logic: tick execution, Tier-2 proposal
+ * generation, state management, rate limiting, and ingesters.
+ *
+ * @see ADR-054 — Sentient Loop Tier-1
+ * @package @cleocode/core
+ */
+export * from './daemon.js';
+export * from './ingesters/brain-ingester.js';
+export * from './ingesters/nexus-ingester.js';
+export * from './ingesters/test-ingester.js';
+export * from './proposal-rate-limiter.js';
+export * from './propose-tick.js';
+export * from './state.js';
+export * from './tick.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sentient/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sentient/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}

package/dist/sentient/ingesters/brain-ingester.d.ts

@@ -0,0 +1,44 @@
+/**
+ * BRAIN Ingester — Tier-2 proposal candidate source.
+ *
+ * Queries brain.db for recurring-pain observations (citation_count >= 3,
+ * last 7 days, quality_score >= 0.5) and returns ranked ProposalCandidate[].
+ *
+ * Design principles:
+ * - NO LLM calls. All data comes from structured SQL queries.
+ * - Title is template-generated: `[T2-BRAIN] Recurring issue: {title}`.
+ *   This is the prompt-injection defence from T1008 §3.6.
+ * - Failures are swallowed: returns empty array + logs warning.
+ *   Brain.db absence must never crash the propose tick.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ProposalCandidate } from '@cleocode/contracts';
+/** Maximum candidates returned from a single brain ingester pass. */
+export declare const BRAIN_INGESTER_LIMIT = 10;
+/** Minimum citation count for a brain entry to be considered. */
+export declare const BRAIN_MIN_CITATION_COUNT = 3;
+/** Minimum quality score for a brain entry to be considered. */
+export declare const BRAIN_MIN_QUALITY_SCORE = 0.5;
+/** Lookback window in days for brain observations. */
+export declare const BRAIN_LOOKBACK_DAYS = 7;
+/**
+ * Compute candidate weight from citation_count and quality_score.
+ * Formula: `(citation_count / 10) * quality_score` capped at 1.0.
+ */
+export declare function computeBrainWeight(citationCount: number, qualityScore: number): number;
+/**
+ * Run the BRAIN ingester against the provided DatabaseSync handle.
+ *
+ * Returns at most {@link BRAIN_INGESTER_LIMIT} candidates, sorted by weight
+ * descending. Returns an empty array if the database has no matching entries
+ * or if any error occurs (errors are swallowed to never crash the tick).
+ *
+ * @param nativeDb - Open DatabaseSync handle to brain.db. May be null if
+ *   brain.db has not been initialised; this is treated as zero candidates.
+ * @returns Ranked ProposalCandidate array (may be empty).
+ */
+export declare function runBrainIngester(nativeDb: DatabaseSync | null): ProposalCandidate[];
+//# sourceMappingURL=brain-ingester.d.ts.map

package/dist/sentient/ingesters/brain-ingester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-ingester.d.ts","sourceRoot":"","sources":["../../../src/sentient/ingesters/brain-ingester.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAkB7D,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAMrC;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtF;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,iBAAiB,EAAE,CA8CnF"}

package/dist/sentient/ingesters/nexus-ingester.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Nexus Ingester — Tier-2 proposal candidate source.
+ *
+ * Queries nexus.db for structural anomalies and returns ranked
+ * ProposalCandidate[]. Two query patterns:
+ *
+ *   A. Orphaned callees: functions that have many callers but make no calls
+ *      themselves (zero-import, high-in-degree). Suggests dead-end sinks
+ *      that may be candidates for abstraction or documentation.
+ *
+ *   B. Over-coupled nodes: symbols with total degree (in + out edges) > 20,
+ *      suggesting high coupling that should be refactored.
+ *
+ * Design principles:
+ * - NO LLM calls. All data comes from structured SQL queries.
+ * - Title is template-generated: `[T2-NEXUS] ...`. Prompt-injection defence.
+ * - Failures are swallowed: returns empty array + logs warning.
+ *   Nexus.db absence must never crash the propose tick.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ProposalCandidate } from '@cleocode/contracts';
+/** Base weight for all nexus candidates (structural signals, lower priority than brain). */
+export declare const NEXUS_BASE_WEIGHT = 0.3;
+/** Minimum caller count for orphaned-callee detection. */
+export declare const NEXUS_MIN_CALLER_COUNT = 5;
+/** Minimum total degree for over-coupling detection. */
+export declare const NEXUS_MIN_DEGREE = 20;
+/** Maximum results per query. */
+export declare const NEXUS_QUERY_LIMIT = 5;
+/**
+ * Run the Nexus ingester against the provided DatabaseSync handle.
+ *
+ * Returns candidates from both orphaned-callee (Query A) and high-degree
+ * (Query B) detection, merged without duplication. Returns an empty array
+ * if the database has no matching entries or if any error occurs.
+ *
+ * @param nativeDb - Open DatabaseSync handle to nexus.db. May be null if
+ *   nexus.db has not been initialised; this is treated as zero candidates.
+ * @returns Ranked ProposalCandidate array (may be empty).
+ */
+export declare function runNexusIngester(nativeDb: DatabaseSync | null): ProposalCandidate[];
+//# sourceMappingURL=nexus-ingester.d.ts.map

package/dist/sentient/ingesters/nexus-ingester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-ingester.d.ts","sourceRoot":"","sources":["../../../src/sentient/ingesters/nexus-ingester.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAwB7D,4FAA4F;AAC5F,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,0DAA0D;AAC1D,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,iCAAiC;AACjC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAmBnC;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,iBAAiB,EAAE,CAkFnF"}

package/dist/sentient/ingesters/test-ingester.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Test Ingester — Tier-2 proposal candidate source.
+ *
+ * Reads two data sources:
+ *
+ *   Source A — `.cleo/audit/gates.jsonl`: CLEO evidence gate failure records.
+ *     Each line is a JSONL record. Lines where `failCount > 0` produce a
+ *     proposal suggesting a flaky-test guard be added for the failing task.
+ *
+ *   Source B — `.cleo/coverage-summary.json`: vitest coverage JSON summary.
+ *     Written by `vitest --coverage --reporter json-summary`. Lines where
+ *     `lines.pct < 80` produce a proposal suggesting coverage improvement.
+ *     If the file is absent, Source B returns zero candidates (no error).
+ *
+ * Design principles:
+ * - NO LLM calls. All data comes from structured file reads.
+ * - Title is template-generated. Prompt-injection defence (T1008 §3.6).
+ * - Failures are swallowed: returns empty array + logs warning.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+import type { ProposalCandidate } from '@cleocode/contracts';
+/** Relative path from project root to gates.jsonl. */
+export declare const GATES_JSONL_PATH: ".cleo/audit/gates.jsonl";
+/** Relative path from project root to the coverage summary. */
+export declare const COVERAGE_SUMMARY_PATH: ".cleo/coverage-summary.json";
+/** Coverage line percentage below which a proposal is emitted. */
+export declare const MIN_LINE_COVERAGE_PCT = 80;
+/** Base weight for all test ingester candidates. */
+export declare const TEST_BASE_WEIGHT = 0.5;
+/**
+ * Run the test ingester against both data sources.
+ *
+ * Merges Source A (gates.jsonl) and Source B (coverage-summary.json) without
+ * duplication. Returns an empty array if both sources yield nothing or if
+ * errors occur (errors are swallowed).
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @returns Combined ProposalCandidate array (may be empty).
+ */
+export declare function runTestIngester(projectRoot: string): ProposalCandidate[];
+//# sourceMappingURL=test-ingester.d.ts.map

package/dist/sentient/ingesters/test-ingester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-ingester.d.ts","sourceRoot":"","sources":["../../../src/sentient/ingesters/test-ingester.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA6B7D,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,EAAG,yBAAkC,CAAC;AAEnE,+DAA+D;AAC/D,eAAO,MAAM,qBAAqB,EAAG,6BAAsC,CAAC;AAE5E,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,MAAM,CAAC;AA6GpC;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAqBxE"}

package/dist/sentient/proposal-rate-limiter.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Proposal Rate Limiter — Transactional DB-enforced daily cap.
+ *
+ * Enforces a maximum of N proposals per day per source tag, using a
+ * BEGIN IMMEDIATE transaction with COUNT + conditional INSERT pattern.
+ *
+ * Design rationale (T1008 §3.2):
+ * - In-process counters do not survive daemon restart, and two daemon
+ *   instances could both allow N/day if enforcement is not in the DB.
+ * - The `sentient.lock` advisory lock (daemon.ts) prevents two daemons
+ *   from running concurrently, but the transactional count check provides
+ *   belt-and-suspenders protection against TOCTOU races.
+ * - SQLite partial unique indexes cannot enforce count > 1, so the
+ *   BEGIN IMMEDIATE + COUNT + INSERT pattern is used instead.
+ *
+ * The "day" boundary is determined by SQLite's `date('now')` (UTC).
+ * Proposals counted include ALL non-terminal statuses (proposed, pending,
+ * active, done) — an accepted proposal still consumes a daily slot.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite';
+/**
+ * The meta proposedBy tag written to `tasks.metadata_json` by the Tier-2
+ * proposer. This tag is the query key for rate-limit counting.
+ */
+export declare const SENTIENT_TIER2_TAG: "sentient-tier2";
+/**
+ * Default maximum number of Tier-2 proposals per UTC day.
+ * Can be overridden by callers.
+ */
+export declare const DEFAULT_DAILY_PROPOSAL_LIMIT = 3;
+/**
+ * Count the number of Tier-2 proposals created today (UTC).
+ *
+ * Counts tasks where:
+ *   - `labels_json` contains `'sentient-tier2'` (the Tier-2 marker label)
+ *   - `date(created_at) = date('now')`
+ *   - `status IN ('proposed', 'pending', 'active', 'done')` — terminal
+ *     states that were proposed today still count toward the daily cap so
+ *     that accepted proposals don't free a slot for another proposal.
+ *
+ * The `LIKE` pattern is intentional: labels_json is a JSON array stored as
+ * text, and `'sentient-tier2'` is always a complete JSON string value within
+ * that array, making substring matching safe here.
+ *
+ * @param nativeDb - Open DatabaseSync handle to tasks.db.
+ * @returns Number of proposals created today. Returns 0 if DB is null.
+ */
+export declare function countTodayProposals(nativeDb: DatabaseSync | null): number;
+/**
+ * Check whether the daily rate limit has been reached.
+ *
+ * @param nativeDb - Open DatabaseSync handle to tasks.db.
+ * @param limit - Daily cap (defaults to {@link DEFAULT_DAILY_PROPOSAL_LIMIT}).
+ * @returns `true` if the limit is reached or exceeded; `false` if capacity remains.
+ */
+export declare function isRateLimitExceeded(nativeDb: DatabaseSync | null, limit?: number): boolean;
+/** Result of a transactional insert attempt. */
+export interface TransactionalInsertResult {
+    /** Whether the INSERT was committed. */
+    inserted: boolean;
+    /**
+     * The count read at the start of the transaction. Used for diagnostics
+     * and tests — lets callers verify the guard saw the expected count.
+     */
+    countBeforeInsert: number;
+    /**
+     * If `inserted = false` and this is set, the limit was the reason.
+     */
+    reason?: 'rate-limit' | 'busy';
+}
+/**
+ * Attempt to insert a pre-built task row inside a BEGIN IMMEDIATE transaction
+ * with a count check.
+ *
+ * Steps:
+ *   1. BEGIN IMMEDIATE (exclusive write lock on tasks.db)
+ *   2. COUNT proposals created today
+ *   3. If count >= limit: ROLLBACK, return `{ inserted: false, reason: 'rate-limit' }`
+ *   4. Otherwise: INSERT the row, COMMIT, return `{ inserted: true }`
+ *
+ * On SQLITE_BUSY: ROLLBACK + return `{ inserted: false, reason: 'busy' }`.
+ *
+ * @param nativeDb - Open DatabaseSync handle to tasks.db.
+ * @param insertSql - Parameterized INSERT SQL string.
+ * @param insertParams - Named parameters for the INSERT statement.
+ * @param limit - Daily cap.
+ * @returns Insert result.
+ */
+export declare function transactionalInsertProposal(nativeDb: DatabaseSync, insertSql: string, insertParams: Record<string, SQLInputValue>, limit?: number): TransactionalInsertResult;
+//# sourceMappingURL=proposal-rate-limiter.d.ts.map

package/dist/sentient/proposal-rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-rate-limiter.d.ts","sourceRoot":"","sources":["../../src/sentient/proposal-rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAM/D;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAG,gBAAyB,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAY9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM,CAazE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GAAG,IAAI,EAC7B,KAAK,SAA+B,GACnC,OAAO,CAET;AAMD,gDAAgD;AAChD,MAAM,WAAW,yBAAyB;IACxC,wCAAwC;IACxC,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3C,KAAK,SAA+B,GACnC,yBAAyB,CAgC3B"}

package/dist/sentient/propose-tick.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Sentient Loop Propose Tick — Single-pass Tier-2 proposal generator.
+ *
+ * Runs inside the daemon cron (every 2 hours) or standalone via
+ * `cleo sentient propose run`. Orchestrates the three ingesters,
+ * deduplicates candidates by fingerprint, applies the DB-enforced
+ * rate limit, and writes accepted candidates as tasks with
+ * `status='proposed'` and labels including `'sentient-tier2'`.
+ *
+ * Scoped IN:
+ *   - Ingest from brain.db, nexus.db, and .cleo/audit/gates.jsonl
+ *   - Transactional rate-limit check (BEGIN IMMEDIATE + COUNT + INSERT)
+ *   - Kill-switch re-check at each checkpoint (Round 2 audit §9)
+ *   - tier2Enabled guard (default false — owner opt-in)
+ *
+ * Scoped OUT:
+ *   - LLM calls (NONE — all proposal titles are structured templates)
+ *   - Tier-3 sandbox/merge (blocked on T992+T993+T995)
+ *
+ * Title format enforcement:
+ *   All proposal titles MUST match `/^\[T2-(BRAIN|NEXUS|TEST)\]/`.
+ *   This is the prompt-injection defence from T1008 §3.6 — no freeform
+ *   LLM text can enter the task title column from the Tier-2 proposer.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+/**
+ * Regex that ALL proposal titles MUST match.
+ * Enforces structured-template-only output (no freeform LLM text).
+ */
+export declare const PROPOSAL_TITLE_PATTERN: RegExp;
+/**
+ * Label applied to every Tier-2 proposal task.
+ * Used by the rate limiter to identify proposals.
+ */
+export declare const TIER2_LABEL = "sentient-tier2";
+/** Discriminant for the propose-tick outcome. */
+export type ProposalTickOutcomeKind = 'killed' | 'disabled' | 'rate-limited' | 'no-candidates' | 'wrote' | 'error';
+/** Structured outcome of a single propose-tick pass. */
+export interface ProposeTickOutcome {
+    /** Discriminant describing how the tick ended. */
+    kind: ProposalTickOutcomeKind;
+    /** Number of proposals written in this pass. */
+    written: number;
+    /** Current daily proposal count at the end of the pass. */
+    count: number;
+    /** Human-readable detail (one line). */
+    detail: string;
+}
+/** Options for {@link runProposeTick}. */
+export interface ProposeTickOptions {
+    /** Absolute path to the project root (contains `.cleo/`). */
+    projectRoot: string;
+    /** Absolute path to sentient-state.json. */
+    statePath: string;
+    /**
+     * Override for the brain DB handle. Injected by tests to avoid
+     * opening a real brain.db. When omitted the real getBrainNativeDb() is used.
+     */
+    brainDb?: import('node:sqlite').DatabaseSync | null;
+    /**
+     * Override for the nexus DB handle. Injected by tests.
+     * When omitted the real getNexusNativeDb() is used.
+     */
+    nexusDb?: import('node:sqlite').DatabaseSync | null;
+    /**
+     * Override for the tasks DB handle (used by rate limiter + INSERT).
+     * Injected by tests. When omitted the real getNativeTasksDb() is used.
+     */
+    tasksDb?: import('node:sqlite').DatabaseSync | null;
+    /**
+     * Override the task ID allocator. Injected by tests.
+     * When omitted the real allocateNextTaskId() is used.
+     */
+    allocateTaskId?: () => Promise<string>;
+}
+/**
+ * Run a single Tier-2 propose pass.
+ *
+ * Steps:
+ *   1. Check killSwitch → abort if true
+ *   2. Check tier2Enabled → abort if false
+ *   3. Run all three ingesters in parallel
+ *   4. Check killSwitch again (post-ingest checkpoint)
+ *   5. Merge + deduplicate candidates by fingerprint
+ *   6. Validate title format (must match PROPOSAL_TITLE_PATTERN)
+ *   7. Score + take top-N candidates (N = limit - countTodayProposals)
+ *   8. Check killSwitch again (pre-write checkpoint)
+ *   9. For each candidate: transactional INSERT into tasks.db
+ *  10. Update tier2Stats in state
+ *
+ * @param options - Propose tick options (see {@link ProposeTickOptions})
+ * @returns Structured outcome describing how the pass ended.
+ */
+export declare function runProposeTick(options: ProposeTickOptions): Promise<ProposeTickOutcome>;
+/**
+ * Safe wrapper for {@link runProposeTick} — swallows unexpected exceptions.
+ * Used by the daemon cron handler.
+ *
+ * @param options - Propose tick options
+ * @returns The propose tick outcome, or an error outcome if the tick threw.
+ */
+export declare function safeRunProposeTick(options: ProposeTickOptions): Promise<ProposeTickOutcome>;
+//# sourceMappingURL=propose-tick.d.ts.map

package/dist/sentient/propose-tick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propose-tick.d.ts","sourceRoot":"","sources":["../../src/sentient/propose-tick.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAiBH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAA+B,CAAC;AAEnE;;;GAGG;AACH,eAAO,MAAM,WAAW,mBAAmB,CAAC;AAM5C,iDAAiD;AACjD,MAAM,MAAM,uBAAuB,GAC/B,QAAQ,GACR,UAAU,GACV,cAAc,GACd,eAAe,GACf,OAAO,GACP,OAAO,CAAC;AAEZ,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,IAAI,EAAE,uBAAuB,CAAC;IAC9B,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACpD;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACpD;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACpD;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACxC;AA0BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+O7F;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAYjG"}

package/dist/sentient/state.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Sentient Loop State — Persistent state for the Tier-1 autonomous daemon.
+ *
+ * Stored in `.cleo/sentient-state.json` (plain JSON, not SQLite) to avoid
+ * SQLite WAL conflicts between the long-running daemon process and the
+ * main CLEO CLI process. Human-readable for debugging.
+ *
+ * The file is gitignored (see .gitignore §.cleo/ section) and survives
+ * restarts. Only `killSwitch`, `pid`, and `stats` fields are load-bearing
+ * across process boundaries.
+ *
+ * @see ADR-054 — Sentient Loop Tier-1 (autonomous task execution)
+ * @task T946
+ */
+import type { Tier2Stats } from '@cleocode/contracts';
+/** Schema version for sentient-state.json. Bump on breaking field changes. */
+export declare const SENTIENT_STATE_SCHEMA_VERSION: "1.0";
+/**
+ * Per-task failure/backoff tracking for stuck detection.
+ * Keyed by task id in {@link SentientState.stuckTasks}.
+ */
+export interface StuckTaskRecord {
+    /** Number of consecutive failed spawn attempts for this task. */
+    attempts: number;
+    /** ISO-8601 timestamp of the most recent failure. */
+    lastFailureAt: string;
+    /** Unix epoch ms when the next retry becomes eligible. */
+    nextRetryAt: number;
+    /** Last captured failure reason (truncated to 500 chars). */
+    lastReason: string;
+}
+/**
+ * Rolling counters persisted across daemon restarts.
+ */
+export interface SentientStats {
+    /** Total tasks picked by the loop since creation. */
+    tasksPicked: number;
+    /** Total tasks that completed successfully. */
+    tasksCompleted: number;
+    /** Total tasks whose spawn exited non-zero. */
+    tasksFailed: number;
+    /** Total ticks executed (including no-op ticks). */
+    ticksExecuted: number;
+    /** Total ticks aborted early because kill switch was active. */
+    ticksKilled: number;
+}
+/**
+ * Persistent sentient daemon state.
+ *
+ * Design principles:
+ * - `killSwitch` is the single load-bearing kill signal — the daemon re-checks
+ *   it between every step of a tick, not just at tick start (Round 2 audit).
+ * - `stuckTasks` keys are task ids; values encode backoff + failure counts.
+ * - `stuckTimestamps` is a rolling 1-hour window used for the self-pause rule
+ *   (5 stucks in 1 hour → killSwitch=true).
+ * - `stats` fields are monotonic counters that only ever increase.
+ */
+export interface SentientState {
+    /** JSON schema version for forward-compatibility checks. */
+    schemaVersion: typeof SENTIENT_STATE_SCHEMA_VERSION;
+    /** PID of the currently running daemon process. null = daemon not running. */
+    pid: number | null;
+    /** ISO-8601 timestamp when the daemon was last started. */
+    startedAt: string | null;
+    /** ISO-8601 timestamp of the last completed tick (any outcome). */
+    lastTickAt: string | null;
+    /**
+     * Kill-switch flag. When true, the daemon re-checks at every step of a tick
+     * and exits cleanly without picking or spawning a task.
+     */
+    killSwitch: boolean;
+    /** Reason supplied when killSwitch was last set (diagnostic only). */
+    killSwitchReason: string | null;
+    /** Rolling counters; see {@link SentientStats}. */
+    stats: SentientStats;
+    /** Per-task backoff + failure metadata for retry/stuck detection. */
+    stuckTasks: Record<string, StuckTaskRecord>;
+    /**
+     * Unix-epoch-ms timestamps of `stuck` events within the last hour.
+     * When length ≥ 5 the daemon self-pauses (killSwitch=true).
+     */
+    stuckTimestamps: number[];
+    /**
+     * Currently-active task id (set while a spawn is in-flight, cleared afterward).
+     * Enables `status` to show the in-progress task during a long-running tick.
+     */
+    activeTaskId: string | null;
+    /**
+     * Tier-2 proposal queue enabled flag.
+     *
+     * Default: `false` — Tier 2 is OFF by default to prevent surprise proposal
+     * floods on first daemon start. Owner enables via `cleo sentient propose enable`
+     * (patches this flag). See ADR-054 §Tier-2.
+     *
+     * @task T1008
+     */
+    tier2Enabled: boolean;
+    /**
+     * Rolling counters for Tier-2 proposal activity.
+     *
+     * @task T1008
+     */
+    tier2Stats: Tier2Stats;
+}
+/** Default (empty) sentient state for fresh initialisation. */
+export declare const DEFAULT_SENTIENT_STATE: SentientState;
+/**
+ * Read the sentient state from disk.
+ *
+ * Returns the default state if the file does not exist or is malformed.
+ * Never throws — absence is not an error.
+ *
+ * @param statePath - Absolute path to sentient-state.json
+ */
+export declare function readSentientState(statePath: string): Promise<SentientState>;
+/**
+ * Write the sentient state to disk atomically via tmp-then-rename.
+ *
+ * Atomic write prevents partial reads if the daemon crashes mid-write.
+ *
+ * @param statePath - Absolute path to sentient-state.json
+ * @param state - State to persist
+ */
+export declare function writeSentientState(statePath: string, state: SentientState): Promise<void>;
+/**
+ * Patch a subset of fields in the sentient state file.
+ *
+ * Reads current state, merges patch, writes back. Nested `stats` merges
+ * with existing stats (never clobbered wholesale).
+ *
+ * @param statePath - Absolute path to sentient-state.json
+ * @param patch - Partial state to merge over the existing state
+ * @returns The merged state that was written to disk.
+ */
+export declare function patchSentientState(statePath: string, patch: Partial<SentientState>): Promise<SentientState>;
+/**
+ * Increment stats counters atomically.
+ *
+ * @param statePath - Absolute path to sentient-state.json
+ * @param delta - Partial stats to add to current counters
+ */
+export declare function incrementStats(statePath: string, delta: Partial<SentientStats>): Promise<SentientState>;
+//# sourceMappingURL=state.d.ts.map

package/dist/sentient/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/sentient/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,6BAA6B,EAAG,KAAc,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,aAAa,EAAE,OAAO,6BAA6B,CAAC;IACpD,8EAA8E;IAC9E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,sEAAsE;IACtE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mDAAmD;IACnD,KAAK,EAAE,aAAa,CAAC;IACrB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC5C;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;;;OAQG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,EAAE,aAuBpC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgBjF;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAS/F;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,aAAa,CAAC,CASxB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,aAAa,CAAC,CAYxB"}