ferrycat 0.3.3 → 0.5.0

package/dist/daemon.d.ts

@@ -3,6 +3,7 @@ import { type FerryCatConfigFile, type HandlerDefinition } from './schemas.js';
 export interface DaemonOptions {
     configPath?: string;
     dbPath?: string;
+    journalPath?: string;
     targetAgent?: string;
     lockId?: string;
     leaseTtlSec?: number;
@@ -11,15 +12,86 @@ export interface DaemonOptions {
     once?: boolean;
     notify?: boolean;
 }
+export type DaemonJournalEvent = 'TASK_DISPATCHING' | 'CHILD_SPAWNED' | 'TASK_SETTLED' | 'CRASH_RECOVERED';
+export type JournalRecoveryAction = 'RELEASED_TO_QUEUE' | 'MARKED_FAILED_MAX_RELEASES' | 'MARKED_FAILED_MUTATION_UNSAFE' | 'MARKED_FAILED_MISSING_CLAIM_TOKEN' | 'QUARANTINED_ORPHAN_ALIVE' | 'ALREADY_SETTLED';
+export interface DaemonJournalEntry {
+    seq: number;
+    timestamp: number;
+    event: DaemonJournalEvent;
+    daemon_owner_token: string;
+    daemon_pid: number;
+    /** R3: wall-clock start time of the writing daemon process, used to disambiguate PID reuse. */
+    daemon_started_at?: number;
+    lock_id: string;
+    contract_id: string;
+    target_agent: string;
+    task_type?: string;
+    claim_token?: string;
+    exec_file?: string;
+    child_pid?: number | null;
+    child_started_at?: number;
+    final_status?: string;
+    previous_owner_token?: string;
+    recovery_action?: JournalRecoveryAction;
+}
+export interface JournalRecoveryItem {
+    contract_id: string;
+    target_agent: string;
+    claim_token?: string;
+    previous_owner_token: string;
+    previous_pid: number;
+    child_pid?: number | null;
+    action: JournalRecoveryAction;
+}
+/**
+ * Non-destructive OS liveness probe via `process.kill(pid, 0)`.
+ * Never sends a termination signal (respecting CK-05 PID-reuse safety), only checks whether
+ * the OS kernel still reports an active process for `pid`.
+ */
+export declare function isProcessAlive(pid?: number | null): boolean;
 export declare function loadFerryCatConfig(customConfigPath?: string): {
     config: FerryCatConfigFile;
     resolvedPath: string | null;
 };
-export declare function notifyOperator(title: string, message: string): void;
+export type NotifyLevel = 'info' | 'warn' | 'error';
+export interface NotifyOptions {
+    level?: NotifyLevel;
+    /** Stable machine-readable event name forwarded to the webhook payload. */
+    event?: string;
+    /** Explicit webhook endpoint; falls back to FERRYCAT_WEBHOOK_URL when omitted. */
+    webhookUrl?: string;
+    /** Set false to suppress the native OS toast (e.g. in CI or headless runs). */
+    native?: boolean;
+}
+export interface WebhookPayload {
+    event: string;
+    title: string;
+    message: string;
+    timestamp: string;
+    level: NotifyLevel;
+}
+export declare function setNotifyWebhook(url: string | undefined): void;
+export declare function getNotifyWebhook(): string | undefined;
+/**
+ * Resolve the platform-native notification command (FC-403).
+ * Windows uses a WinRT Toast driven by the PowerShell host's own AppId so no module install is
+ * required; macOS uses `display notification`; Linux uses libnotify's `notify-send`.
+ */
+export declare function resolveNativeCommand(title: string, message: string, platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Deliver one webhook payload. Exported so tests can await the real HTTP round-trip; production
+ * call sites use the fire-and-forget wrapper below.
+ */
+export declare function dispatchWebhook(url: string, payload: WebhookPayload, timeoutMs?: number): Promise<boolean>;
+export declare function notifyOperator(title: string, message: string, opts?: NotifyOptions): void;
 export declare class FerryCatDaemon {
     readonly engine: FerryCatEngine;
     readonly config: FerryCatConfigFile;
     readonly configPath: string | null;
+    readonly journalPath: string;
     readonly lockId: string;
     readonly leaseTtlSec: number;
     readonly heartbeatIntervalMs: number;
@@ -27,8 +99,16 @@ export declare class FerryCatDaemon {
     readonly ownerToken: string;
     readonly targetAgentFilter?: string;
     readonly notifyEnabled: boolean;
+    readonly webhookUrl?: string;
+    /** R3: wall-clock start of this daemon instance, journaled so a successor can disambiguate PID reuse. */
+    readonly daemonStartedAt: number;
+    journalDegraded: boolean;
+    lastJournalError: string | null;
     private isRunning;
     private isLeader;
+    private journalSeq;
+    private settledSinceLastCompact;
+    private journalDegradedReported;
     private heartbeatTimer;
     private pollTimer;
     private signalCleanupRegistered;
@@ -36,6 +116,62 @@ export declare class FerryCatDaemon {
     constructor(options?: DaemonOptions);
     registerSignalHandlers(): void;
     acquireLease(): boolean;
+    /**
+     * Synchronously appends a write-ahead record to `daemon-journal.jsonl` (Phase 3 Step 2).
+     * Guaranteed to flush before child spawn and after task completion so sudden SIGKILL / power loss
+     * leaves an auditable breadcrumb for the next daemon leader to self-heal.
+     */
+    appendJournalEntry(partial: Omit<DaemonJournalEntry, 'seq' | 'timestamp' | 'daemon_owner_token' | 'daemon_pid' | 'daemon_started_at' | 'lock_id'>): DaemonJournalEntry;
+    /**
+     * Reads all valid JSONL records from this daemon's journal file, tolerating partial/corrupt tail lines.
+     *
+     * R6 (upgrade compatibility): before per-lock_id journal files existed, every daemon wrote into a
+     * single shared `daemon-journal.jsonl`. When this instance is a non-`global` lock whose own file does
+     * not exist yet, fall back to that legacy file and keep only the records belonging to this lock_id,
+     * so in-flight contracts written by the previous version are still recovered instead of silently
+     * stranded as CLAIMED until the TTL sweep kills them.
+     */
+    readJournalEntries(): DaemonJournalEntry[];
+    /**
+     * Scans `daemon-journal.jsonl` upon acquiring leadership and heals any in-flight contracts
+     * orphaned by a crashed predecessor daemon instance (Phase 3 Step 2, FC-404).
+     *
+     * Safety invariants:
+     *  - CK-05 (PID reuse safety): never sends kill signals to bare numeric PIDs from old runs.
+     *  - Liveness quarantine: probes `isProcessAlive(child_pid)` and `isProcessAlive(daemon_pid)`.
+     *    If the predecessor daemon or orphaned child is still alive (e.g. GC pause / lease expiry),
+     *    quarantines the contract as `FAILED` (`QUARANTINED_ORPHAN_ALIVE`) instead of re-queueing
+     *    to prevent concurrent double-execution on the same workspace.
+     *  - Mutation task protection: `implementation` and `test_generation` tasks interrupted mid-flight
+     *    are never auto-requeued (`MARKED_FAILED_MUTATION_UNSAFE`) to protect working-tree integrity.
+     *  - Read-only tasks (`code_review` / `architecture_audit`) whose predecessor & child are confirmed
+     *    dead are released back to the `SUBMITTED` queue (or marked `FAILED` if `MAX_RELEASES` is reached).
+     */
+    recoverFromJournal(): JournalRecoveryItem[];
+    compactJournalIfSettled(): boolean;
+    /**
+     * R7: operator-facing snapshot of the daemon's lease and journal health.
+     * Exposes `journalDegraded` / `lastJournalError`, which were previously only internal fields
+     * with no reader — a silently degraded write-ahead journal now shows up here and on stderr.
+     */
+    getStatus(): {
+        lock_id: string;
+        is_leader: boolean;
+        owner_token: string;
+        daemon_pid: number;
+        daemon_started_at: number;
+        journal_path: string;
+        journal_degraded: boolean;
+        last_journal_error: string | null;
+        journal_entries: number;
+        lease: {
+            owner_token: string;
+            heartbeat_at: number;
+            expires_at: number;
+            metadata: unknown;
+        } | null;
+        lease_held_by_self: boolean;
+    };
     renewLease(): boolean;
     releaseLease(): void;
     resolveHandler(targetAgent: string, taskType: string): HandlerDefinition | null;