@provos/ironcurtain 0.6.0 → 0.7.1

package/dist/cron/job-customizer.js

@@ -0,0 +1,47 @@
+/**
+ * Interactive LLM-assisted constitution customizer for cron jobs.
+ *
+ * Thin wrapper around the shared customizer loop, adding
+ * task-specific context to the LLM system prompt.
+ */
+import { buildSystemPrompt } from '../pipeline/constitution-customizer.js';
+import { runConstitutionCustomizerLoop } from '../pipeline/customizer-loop.js';
+// ---------------------------------------------------------------------------
+// Job-Scoped System Prompt
+// ---------------------------------------------------------------------------
+/**
+ * Builds a system prompt for the job constitution customizer.
+ * Extends the base customizer prompt with task-specific context.
+ */
+export function buildJobCustomizerSystemPrompt(baseConstitution, toolAnnotations, taskDescription, githubIdentity) {
+    const basePrompt = buildSystemPrompt(baseConstitution, toolAnnotations, githubIdentity);
+    return `${basePrompt}
+
+## Task Context
+
+This constitution is for a scheduled job with the following task:
+
+${taskDescription}
+
+Focus your suggestions on what THIS SPECIFIC TASK needs. Do not suggest
+broad permissions unless the task requires them.`;
+}
+// ---------------------------------------------------------------------------
+// Main Entry Point
+// ---------------------------------------------------------------------------
+/**
+ * Runs an interactive constitution customizer session for a job.
+ * Operates on an in-memory constitution string (not the global file).
+ *
+ * @param initialConstitution - Starting constitution text (from generator or existing job)
+ * @param taskDescription - The task description (context for the LLM)
+ * @returns The final constitution text, or undefined if the user cancelled
+ */
+export async function runJobConstitutionCustomizer(initialConstitution, taskDescription) {
+    return runConstitutionCustomizerLoop(initialConstitution, (ctx) => buildJobCustomizerSystemPrompt('', ctx.annotations, taskDescription, ctx.githubIdentity), {
+        stepName: 'job-customize-policy',
+        noteTitle: 'Current Job Constitution',
+        refinePlaceholder: 'e.g., "also allow git push to origin"',
+    });
+}
+//# sourceMappingURL=job-customizer.js.map

package/dist/cron/job-customizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-customizer.js","sourceRoot":"","sources":["../../src/cron/job-customizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAC3E,OAAO,EAAE,6BAA6B,EAA8B,MAAM,gCAAgC,CAAC;AAI3G,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC5C,gBAAwB,EACxB,eAAiC,EACjC,eAAuB,EACvB,cAAsC;IAEtC,MAAM,UAAU,GAAG,iBAAiB,CAAC,gBAAgB,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC;IAExF,OAAO,GAAG,UAAU;;;;;;EAMpB,eAAe;;;iDAGgC,CAAC;AAClD,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,mBAA2B,EAC3B,eAAuB;IAEvB,OAAO,6BAA6B,CAClC,mBAAmB,EACnB,CAAC,GAA0B,EAAE,EAAE,CAC7B,8BAA8B,CAAC,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,eAAe,EAAE,GAAG,CAAC,cAAc,CAAC,EAC1F;QACE,QAAQ,EAAE,sBAAsB;QAChC,SAAS,EAAE,0BAA0B;QACrC,iBAAiB,EAAE,uCAAuC;KAC3D,CACF,CAAC;AACJ,CAAC"}

package/dist/cron/job-store.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Filesystem-backed store for job definitions and run records.
+ *
+ * Directory layout:
+ *   ~/.ironcurtain/jobs/{jobId}/
+ *     job.json              -- JobDefinition
+ *     generated/            -- per-job compiled policy artifacts
+ *       compiled-policy.json
+ *       dynamic-lists.json  -- (optional)
+ *     workspace/            -- persistent agent workspace
+ *     runs/                 -- run history
+ *       2026-03-04T09:00:00.000Z.json
+ *
+ * Tool annotations (tool-annotations.json) are always loaded from
+ * the global location, never stored per-job.
+ */
+import type { JobDefinition, JobId, RunRecord } from './types.js';
+/** Loads a job definition from disk. Returns undefined if not found. */
+export declare function loadJob(jobId: JobId): JobDefinition | undefined;
+/** Loads all job definitions from disk. */
+export declare function loadAllJobs(): JobDefinition[];
+/**
+ * Saves a job definition to disk. Creates directories as needed.
+ * Acquires an advisory file lock to prevent concurrent write corruption.
+ */
+export declare function saveJob(job: JobDefinition): Promise<void>;
+/** Deletes a job and all its artifacts (generated, workspace, runs). */
+export declare function deleteJob(jobId: JobId): void;
+/** Records a completed run. Filenames are unique (timestamp-based), so no lock needed. */
+export declare function saveRunRecord(jobId: JobId, record: RunRecord): void;
+/**
+ * Loads recent run records for a job, most recent first.
+ * @param limit Maximum number of records to return (default 10).
+ */
+export declare function loadRecentRuns(jobId: JobId, limit?: number): RunRecord[];

package/dist/cron/job-store.js

@@ -0,0 +1,111 @@
+/**
+ * Filesystem-backed store for job definitions and run records.
+ *
+ * Directory layout:
+ *   ~/.ironcurtain/jobs/{jobId}/
+ *     job.json              -- JobDefinition
+ *     generated/            -- per-job compiled policy artifacts
+ *       compiled-policy.json
+ *       dynamic-lists.json  -- (optional)
+ *     workspace/            -- persistent agent workspace
+ *     runs/                 -- run history
+ *       2026-03-04T09:00:00.000Z.json
+ *
+ * Tool annotations (tool-annotations.json) are always loaded from
+ * the global location, never stored per-job.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getJobsDir, getJobDir, getJobRunsDir } from '../config/paths.js';
+import { createJobId } from './types.js';
+import { withFileLock, getJobLockDir } from './file-lock.js';
+/** Loads a job definition from disk. Returns undefined if not found. */
+export function loadJob(jobId) {
+    const jobFile = resolve(getJobDir(jobId), 'job.json');
+    if (!existsSync(jobFile))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(jobFile, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Loads all job definitions from disk. */
+export function loadAllJobs() {
+    const jobsDir = getJobsDir();
+    if (!existsSync(jobsDir))
+        return [];
+    const jobs = [];
+    let entries;
+    try {
+        entries = readdirSync(jobsDir);
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        try {
+            const jobId = createJobId(entry);
+            const job = loadJob(jobId);
+            if (job)
+                jobs.push(job);
+        }
+        catch {
+            // Skip invalid directory names or malformed job files
+        }
+    }
+    return jobs;
+}
+/**
+ * Saves a job definition to disk. Creates directories as needed.
+ * Acquires an advisory file lock to prevent concurrent write corruption.
+ */
+export async function saveJob(job) {
+    const jobDir = getJobDir(job.id);
+    mkdirSync(jobDir, { recursive: true });
+    await withFileLock(getJobLockDir(jobDir), () => {
+        writeFileSync(resolve(jobDir, 'job.json'), JSON.stringify(job, null, 2) + '\n');
+    });
+}
+/** Deletes a job and all its artifacts (generated, workspace, runs). */
+export function deleteJob(jobId) {
+    rmSync(getJobDir(jobId), { recursive: true, force: true });
+}
+/** Records a completed run. Filenames are unique (timestamp-based), so no lock needed. */
+export function saveRunRecord(jobId, record) {
+    const runsDir = getJobRunsDir(jobId);
+    mkdirSync(runsDir, { recursive: true });
+    const filename = record.startedAt.replace(/:/g, '-') + '.json';
+    writeFileSync(resolve(runsDir, filename), JSON.stringify(record, null, 2) + '\n');
+}
+/**
+ * Loads recent run records for a job, most recent first.
+ * @param limit Maximum number of records to return (default 10).
+ */
+export function loadRecentRuns(jobId, limit = 10) {
+    const runsDir = getJobRunsDir(jobId);
+    if (!existsSync(runsDir))
+        return [];
+    let files;
+    try {
+        files = readdirSync(runsDir).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    // Sort by filename (ISO timestamp-based) descending
+    files.sort((a, b) => b.localeCompare(a));
+    const records = [];
+    for (const file of files.slice(0, limit)) {
+        try {
+            const record = JSON.parse(readFileSync(resolve(runsDir, file), 'utf-8'));
+            records.push(record);
+        }
+        catch {
+            // Skip malformed run records
+        }
+    }
+    return records;
+}
+//# sourceMappingURL=job-store.js.map

package/dist/cron/job-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-store.js","sourceRoot":"","sources":["../../src/cron/job-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClG,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE7D,wEAAwE;AACxE,MAAM,UAAU,OAAO,CAAC,KAAY;IAClC,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAE3C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAkB,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,WAAW;IACzB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,IAAI,GAAoB,EAAE,CAAC;IACjC,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;YACjC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAC3B,IAAI,GAAG;gBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,sDAAsD;QACxD,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAkB;IAC9C,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,MAAM,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE;QAC7C,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,SAAS,CAAC,KAAY;IACpC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,aAAa,CAAC,KAAY,EAAE,MAAiB;IAC3D,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACrC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAExC,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC;IAC/D,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACpF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY,EAAE,QAAgB,EAAE;IAC7D,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,oDAAoD;IACpD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzC,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAc,CAAC;YACtF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,6BAA6B;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cron/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Cron Mode types -- job definitions, run records, and budget overrides.
+ *
+ * These types are used by the job store, cron scheduler, daemon,
+ * and CLI commands.
+ */
+/**
+ * Stable, user-chosen identifier for a cron job.
+ * Must be a valid slug: lowercase alphanumeric, hyphens, underscores.
+ * Branded to prevent mixing with other string identifiers.
+ */
+export type JobId = string & {
+    readonly __brand: 'JobId';
+};
+/** Regex for valid job IDs: 1-63 chars, lowercase alphanumeric, hyphens, or underscores. */
+export declare const JOB_ID_PATTERN: RegExp;
+/** Validates and creates a JobId from a user-provided string. */
+export declare function createJobId(raw: string): JobId;
+/**
+ * Persisted job definition. Stored as JSON at
+ * ~/.ironcurtain/jobs/{jobId}/job.json.
+ *
+ * Invariant: the `task` field is the "constitution" input for
+ * per-job policy compilation. Changing it invalidates the
+ * compiled policy (detected via content hash comparison).
+ */
+export interface JobDefinition {
+    /** Stable user-chosen slug. Matches the directory name. */
+    readonly id: JobId;
+    /** Human-friendly display name. */
+    readonly name: string;
+    /** Standard cron expression (5 fields: min hour dom mon dow). */
+    readonly schedule: string;
+    /**
+     * English task description sent to the agent as its work prompt.
+     */
+    readonly taskDescription: string;
+    /**
+     * English constitution text used as the policy compilation input.
+     * Describes what the agent is and is not permitted to do.
+     */
+    readonly taskConstitution: string;
+    /**
+     * Working directory for this job. Persists across runs.
+     * Default: ~/.ironcurtain/jobs/{jobId}/workspace/
+     */
+    readonly workspace?: string;
+    /**
+     * Optional git repository URI to clone into the workspace.
+     * On first run, the repo is cloned. On subsequent runs,
+     * tracked files are reset to remote HEAD (untracked files preserved).
+     */
+    readonly gitRepo?: string;
+    /**
+     * When true and Signal is configured, the daemon sends a Signal
+     * message on escalation and waits for approval. When false or
+     * Signal is not configured, escalations are auto-denied.
+     */
+    readonly notifyOnEscalation: boolean;
+    /**
+     * When true and Signal is configured, the daemon sends a Signal
+     * message with the run summary on completion.
+     */
+    readonly notifyOnCompletion: boolean;
+    /**
+     * Per-job resource budget overrides. Null fields inherit from
+     * the cron-specific defaults.
+     */
+    readonly budgetOverrides?: Partial<JobBudgetOverrides>;
+    /**
+     * Optional persona name. When set, the job uses this persona's
+     * compiled policy instead of its inline taskConstitution.
+     * Mutually exclusive with taskConstitution -- if persona is set,
+     * taskConstitution is ignored for policy loading (but still used
+     * as the system prompt augmentation if present).
+     */
+    readonly persona?: string;
+    /** Whether this job is active. Disabled jobs are not scheduled. */
+    readonly enabled: boolean;
+}
+/**
+ * Budget fields that can be overridden per-job.
+ * All fields are nullable: null means "disable this limit".
+ */
+export interface JobBudgetOverrides {
+    readonly maxTotalTokens: number | null;
+    readonly maxSteps: number | null;
+    readonly maxSessionSeconds: number | null;
+    readonly maxEstimatedCostUsd: number | null;
+}
+/**
+ * Outcome status for a completed run.
+ */
+export type RunOutcome = {
+    readonly kind: 'success';
+} | {
+    readonly kind: 'budget_exhausted';
+    readonly dimension: string;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+/**
+ * Persisted run record. Written to
+ * ~/.ironcurtain/jobs/{jobId}/runs/{timestamp}.json
+ * after each run completes.
+ */
+export interface RunRecord {
+    /** ISO 8601 start time. Also used as the filename. */
+    readonly startedAt: string;
+    /** ISO 8601 end time. */
+    readonly completedAt: string;
+    /** How the run ended. */
+    readonly outcome: RunOutcome;
+    /** Resource consumption snapshot. */
+    readonly budget: {
+        readonly totalTokens: number;
+        readonly stepCount: number;
+        readonly elapsedSeconds: number;
+        readonly estimatedCostUsd: number;
+    };
+    /**
+     * Brief summary extracted from workspace/last-run.md, if it exists.
+     * Truncated to 2000 chars. Null if the file was not written.
+     */
+    readonly summary: string | null;
+    /** Whether any escalations were surfaced during this run. */
+    readonly escalationsEncountered: number;
+    /** Whether any escalations were approved (vs. denied or timed out). */
+    readonly escalationsApproved: number;
+    /** git diff --stat of tracked-file changes discarded during pre-run sync. */
+    readonly discardedChanges: string | null;
+}
+/** Cron-specific budget defaults (differ from interactive defaults). */
+export declare const CRON_BUDGET_DEFAULTS: Required<JobBudgetOverrides>;

package/dist/cron/types.js

@@ -0,0 +1,22 @@
+/**
+ * Cron Mode types -- job definitions, run records, and budget overrides.
+ *
+ * These types are used by the job store, cron scheduler, daemon,
+ * and CLI commands.
+ */
+import { SLUG_PATTERN, validateSlug } from '../types/slug.js';
+/** Regex for valid job IDs: 1-63 chars, lowercase alphanumeric, hyphens, or underscores. */
+export const JOB_ID_PATTERN = SLUG_PATTERN;
+/** Validates and creates a JobId from a user-provided string. */
+export function createJobId(raw) {
+    validateSlug(raw, 'job ID');
+    return raw;
+}
+/** Cron-specific budget defaults (differ from interactive defaults). */
+export const CRON_BUDGET_DEFAULTS = {
+    maxTotalTokens: 500_000,
+    maxSteps: 100,
+    maxSessionSeconds: 3_600,
+    maxEstimatedCostUsd: 2.0,
+};
+//# sourceMappingURL=types.js.map

package/dist/cron/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cron/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAS9D,4FAA4F;AAC5F,MAAM,CAAC,MAAM,cAAc,GAAW,YAAY,CAAC;AAEnD,iEAAiE;AACjE,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,YAAY,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC5B,OAAO,GAAY,CAAC;AACtB,CAAC;AAsID,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAiC;IAChE,cAAc,EAAE,OAAO;IACvB,QAAQ,EAAE,GAAG;IACb,iBAAiB,EAAE,KAAK;IACxB,mBAAmB,EAAE,GAAG;CACzB,CAAC"}

package/dist/daemon/control-socket.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Control socket for live daemon communication.
+ *
+ * The daemon listens on a Unix domain socket at ~/.ironcurtain/daemon.sock.
+ * CLI commands detect whether the daemon is running (socket exists and
+ * responds) and forward commands to it. If no daemon is running, CLI
+ * commands fall back to direct filesystem operations.
+ *
+ * Protocol: newline-delimited JSON. Each request is a single JSON line;
+ * the daemon writes a single JSON response line and closes the connection.
+ */
+import type { JobDefinition, RunRecord } from '../cron/types.js';
+/** Commands the CLI can send to the daemon. */
+export type ControlRequest = {
+    readonly command: 'ping';
+} | {
+    readonly command: 'status';
+} | {
+    readonly command: 'add-job';
+    readonly job: JobDefinition;
+} | {
+    readonly command: 'remove-job';
+    readonly jobId: string;
+} | {
+    readonly command: 'enable-job';
+    readonly jobId: string;
+} | {
+    readonly command: 'disable-job';
+    readonly jobId: string;
+} | {
+    readonly command: 'recompile-job';
+    readonly jobId: string;
+} | {
+    readonly command: 'reload-job';
+    readonly jobId: string;
+} | {
+    readonly command: 'run-job';
+    readonly jobId: string;
+} | {
+    readonly command: 'list-jobs';
+};
+/** Successful response from the daemon. */
+export interface ControlResponseOk {
+    readonly ok: true;
+    readonly data?: unknown;
+}
+/** Error response from the daemon. */
+export interface ControlResponseError {
+    readonly ok: false;
+    readonly error: string;
+}
+export type ControlResponse = ControlResponseOk | ControlResponseError;
+/** Status snapshot returned by the daemon. */
+export interface DaemonStatus {
+    readonly uptimeSeconds: number;
+    readonly jobs: {
+        total: number;
+        enabled: number;
+        running: number;
+    };
+    readonly signalConnected: boolean;
+    readonly nextFireTime: Date | null;
+}
+/** JSON-serialized form of DaemonStatus (Date → ISO string). */
+export interface DaemonStatusDto {
+    readonly uptimeSeconds: number;
+    readonly jobs: {
+        total: number;
+        enabled: number;
+        running: number;
+    };
+    readonly signalConnected: boolean;
+    readonly nextFireTime: string | null;
+}
+export interface ControlRequestHandler {
+    getStatus(): DaemonStatus;
+    addJob(job: JobDefinition): Promise<void>;
+    removeJob(jobId: string): Promise<void>;
+    enableJob(jobId: string): Promise<void>;
+    disableJob(jobId: string): Promise<void>;
+    recompileJob(jobId: string): Promise<void>;
+    reloadJob(jobId: string): Promise<void>;
+    runJobNow(jobId: string): Promise<RunRecord>;
+    listJobs(): Array<{
+        job: JobDefinition;
+        nextRun: Date | undefined;
+        lastRun: RunRecord | undefined;
+        isRunning: boolean;
+    }>;
+}
+export declare class ControlSocketServer {
+    private server;
+    private readonly socketPath;
+    private readonly handler;
+    constructor(handler: ControlRequestHandler, socketPath?: string);
+    /** Starts listening on the Unix domain socket. */
+    start(): Promise<void>;
+    /** Stops the server and removes the socket file. */
+    stop(): Promise<void>;
+    /**
+     * Removes a stale socket file left behind by a crashed daemon.
+     * Attempts to connect first — only unlinks when the socket is
+     * confirmed stale (ECONNREFUSED) or absent (ENOENT). If the
+     * socket is live, throws so the caller knows another daemon is running.
+     */
+    private removeStaleSocket;
+    /**
+     * Probes whether the socket is actively accepting connections.
+     * Returns true if a daemon is listening, false if stale/absent.
+     */
+    private isSocketAlive;
+    private cleanupSocketFile;
+    private onConnection;
+    private handleRequest;
+    private dispatch;
+    private sendResponse;
+}
+/**
+ * Sends a request to the running daemon via the control socket.
+ * Returns the parsed response, or null if the daemon is not reachable.
+ */
+export declare function sendControlRequest(request: ControlRequest, socketPath?: string): Promise<ControlResponse | null>;
+/**
+ * Checks if a daemon is currently running and responsive.
+ * Returns true if the daemon responds to a ping.
+ */
+export declare function isDaemonRunning(socketPath?: string): Promise<boolean>;