@cleocode/core 2026.4.98 → 2026.4.100

package/dist/sentient/daemon-entry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sentient Daemon Entry Point — spawned by `spawnSentientDaemon()`.
+ *
+ * Runs as a detached background process. Receives the project root as
+ * argv[2]. Does NOT import the CLI shim — only the sentient/ subtree.
+ *
+ * @see sentient/daemon.ts for spawn logic
+ * @task T946
+ */
+export {};
+//# sourceMappingURL=daemon-entry.d.ts.map

package/dist/sentient/daemon-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-entry.d.ts","sourceRoot":"","sources":["../../src/sentient/daemon-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/sentient/daemon.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Sentient Daemon — Tier-1 autonomous loop sidecar.
+ *
+ * Runs as a detached Node.js process and executes `runTick()` every 5
+ * minutes. Mirrors the gc/daemon.ts sidecar pattern (ADR-047) and honours
+ * the worktree protocol — all state lives under the project's `.cleo/`.
+ *
+ * Scoped IN (this module):
+ *   - Tier-1 execution of unblocked tasks via `cleo orchestrate spawn`
+ *   - Kill-switch with re-check at every tick checkpoint
+ *   - Advisory locking via an OS-level lockfile (two daemons cannot coexist)
+ *   - Stuck detection + self-pause on stuck-rate threshold
+ *   - fs.watch-based fast kill propagation
+ *
+ * Scoped OUT (separate epics):
+ *   - Tier-2 proposal queue (`cleo propose` / status='proposed' generation)
+ *   - Tier-3 sandbox auto-merge (requires agent-in-container infra)
+ *   - Ed25519 signing of receipts (handled by Agent B2 llmtxt/identity wiring)
+ *
+ * @see ADR-054 — Sentient Loop Tier-1
+ * @task T946
+ */
+import { type FileHandle } from 'node:fs/promises';
+import { type SentientState } from './state.js';
+/** Relative subpath under a project root where sentient state lives. */
+export declare const SENTIENT_STATE_FILE: ".cleo/sentient-state.json";
+/** Relative subpath for the daemon lockfile. */
+export declare const SENTIENT_LOCK_FILE: ".cleo/sentient.lock";
+/** Cron expression: every 5 minutes (Tier-1 tick). */
+export declare const SENTIENT_CRON_EXPR = "*/5 * * * *";
+/**
+ * Cron expression: every 2 hours (Tier-2 propose tick).
+ *
+ * Separate from the Tier-1 cron to avoid proposal flooding.
+ * Only fires when `tier2Enabled = true` in sentient-state.json.
+ *
+ * @task T1008
+ */
+export declare const SENTIENT_PROPOSE_CRON_EXPR = "0 */2 * * *";
+/** Subdirectory for daemon logs. */
+export declare const SENTIENT_LOG_DIR: ".cleo/logs";
+/** Log filename (stdout). */
+export declare const SENTIENT_LOG: "sentient.log";
+/** Log filename (stderr). */
+export declare const SENTIENT_ERR: "sentient.err";
+/** Handle to an active advisory lock. */
+export interface LockHandle {
+    /** Absolute path to the lockfile. */
+    path: string;
+    /** Underlying file handle held exclusively by this process. */
+    handle: FileHandle;
+}
+/**
+ * Acquire an exclusive advisory lock on the sentient lockfile.
+ *
+ * Uses `fs.open` with `O_CREAT | O_EXCL` semantics — if the file already
+ * exists AND its recorded pid is alive, acquisition fails. Stale lockfiles
+ * (pid dead) are reclaimed automatically.
+ *
+ * @param lockPath - Absolute path to `.cleo/sentient.lock`
+ * @returns Lock handle, or null if lock is held by a live process
+ */
+export declare function acquireLock(lockPath: string): Promise<LockHandle | null>;
+/**
+ * Release an advisory lock acquired via {@link acquireLock}.
+ * Does NOT remove the lockfile — the pid inside is a useful diagnostic.
+ */
+export declare function releaseLock(lock: LockHandle): Promise<void>;
+/**
+ * Bootstrap the sentient daemon process.
+ *
+ * Steps:
+ *   1. Acquire advisory lock (fail fast if another daemon is running)
+ *   2. Persist our pid + startedAt to state.json
+ *   3. Watch state.json for killSwitch changes (fast propagation)
+ *   4. Register a SIGTERM handler for graceful shutdown
+ *   5. Schedule cron with noOverlap so long ticks don't stack
+ *
+ * @param projectRoot - Absolute path to the project (contains `.cleo/`)
+ */
+export declare function bootstrapDaemon(projectRoot: string): Promise<void>;
+/** Outcome of {@link spawnSentientDaemon}. */
+export interface SpawnDaemonResult {
+    /** PID of the spawned daemon. */
+    pid: number;
+    /** Absolute path to the .cleo/sentient-state.json file. */
+    statePath: string;
+    /** Absolute path to the log file. */
+    logPath: string;
+}
+/**
+ * Spawn the sentient daemon as a detached background process.
+ *
+ * All three T751 §2.2 requirements:
+ *   1. `detached: true` — process-group leader survives parent exit
+ *   2. File-based stdio — no TTY inheritance
+ *   3. `child.unref()` — parent CLI returns immediately
+ *
+ * @param projectRoot - Absolute path to the project root (contains `.cleo/`)
+ * @returns PID + log paths
+ */
+export declare function spawnSentientDaemon(projectRoot: string): Promise<SpawnDaemonResult>;
+/** Outcome of {@link stopSentientDaemon}. */
+export interface StopDaemonResult {
+    /** Whether the stop signal was delivered. */
+    stopped: boolean;
+    /** Last known pid; null if no pid was recorded. */
+    pid: number | null;
+    /** Human-readable reason. */
+    reason: string;
+}
+/**
+ * Stop the sentient daemon.
+ *
+ * Flips killSwitch=true FIRST (so an in-flight tick notices on its next
+ * checkpoint re-read), then sends SIGTERM. This gives the daemon a fast,
+ * graceful shutdown path even during a long-running spawn.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param reason - Optional reason stored on state file for diagnostics
+ * @returns Stop result
+ */
+export declare function stopSentientDaemon(projectRoot: string, reason?: string): Promise<StopDaemonResult>;
+/**
+ * Clear the kill switch so the cron schedule resumes executing ticks.
+ *
+ * Does NOT restart the daemon process — that is the caller's responsibility
+ * via `cleo sentient start` if the process itself exited.
+ *
+ * @param projectRoot - Absolute path to the project root
+ */
+export declare function resumeSentientDaemon(projectRoot: string): Promise<SentientState>;
+/** Status snapshot returned by {@link getSentientDaemonStatus}. */
+export interface SentientStatus {
+    /** Whether the pid on file is currently alive. */
+    running: boolean;
+    /** Recorded pid (null when never started or cleared on stop). */
+    pid: number | null;
+    /** ISO-8601 timestamp of last start. */
+    startedAt: string | null;
+    /** ISO-8601 timestamp of the last completed tick. */
+    lastTickAt: string | null;
+    /** Kill-switch state. */
+    killSwitch: boolean;
+    /** Reason supplied with the last kill. */
+    killSwitchReason: string | null;
+    /** Rolling stats. */
+    stats: SentientState['stats'];
+    /** Number of currently-stuck tasks. */
+    stuckCount: number;
+    /** Currently active task id (set mid-tick). */
+    activeTaskId: string | null;
+}
+/**
+ * Return a diagnostic snapshot for `cleo sentient status`.
+ *
+ * @param projectRoot - Absolute path to the project root
+ */
+export declare function getSentientDaemonStatus(projectRoot: string): Promise<SentientStatus>;
+//# sourceMappingURL=daemon.d.ts.map

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

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