harnery 0.15.0 → 0.16.0

package/README.md

@@ -23,7 +23,7 @@
 - **Cross-machine presence:** sessions on every machine that shares a repo see each other, labeled by machine. Zero-config over the repo's own git remote (presence refs), with an optional live-socket upgrade via an end-to-end-encrypted relay — the public `relay.harnery.com`, or self-host with `harn relay serve` / the bundled Cloudflare Worker (`relay/worker/`). The relay sees only ciphertext in opaquely-named rooms.
 - **Coordination-aware workflows:** `harn workflow run <script>` executes bounded, schema-gated multi-subagent workflow scripts — plain JS stages fanning out to headless harness-CLI subagents that are born coordination-registered (heartbeats, events, claim guards), with deterministic code deciding the routing between stages. An optional host-owned policy gates dispatch and declared external mutations with `ALLOW`, `ASK`, and `DENY`; CLI `ASK` requests park durably for an explicit approve/deny and same-run resume, while library callers remain fail-closed by default.
 - **Durable work above attempts:** `harn work` preserves an objective across bounded workflow attempts, dependencies, approval parks, failures, and review. Its one-shot reconciler derives state from append-only local evidence and reports the next explicit action without silently spawning, retrying, or accepting work.
-- **Bounded goal supervision:** `harn supervisor` freezes a specialist team and safety limits around a root durable-work graph, then runs foreground scheduling cycles until success, human attention, no progress, or budget exhaustion. Specialist roles survive as configuration while every child remains a bounded process.
+- **Bounded goal supervision:** `harn supervisor` freezes a specialist team and safety limits around a root durable-work graph, then runs scheduling cycles until success, human attention, no progress, or budget exhaustion. Use explicit foreground ticks or enroll goals in the optional heartbeat-backed background service; specialist roles survive as configuration while every child remains a bounded process.
 - **Standalone web UI:** `harn web up` boots a local Next.js dashboard for the coord layer, councils, per-project state, and a local coding-agent status view (Claude Code / Codex / Cursor usage, backed by `harn devtools`). Ships with the git clone, not the npm package (see [Install](#install)).
 - **Backup + sync:** `harn backup` snapshots `.harnery/` via [restic](https://restic.net/); `harn sync` keeps a curated subset live across machines via [rclone](https://rclone.org/) (Google Drive or any rclone remote).
 

package/dist/commands/supervisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/commands/supervisor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA4CnD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA0FnF"}
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/commands/supervisor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA4DnD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA2FnF"}

package/dist/commands/supervisor.js

@@ -1,10 +1,10 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { workflowSubscriptionOnly } from "../core/config.js";
 import { createBuiltinHarnessRegistry } from "../core/harnesses/index.js";
 import { findCoordRoot } from "../core/hooks/resolve/coord-root.js";
 import { loadPolicyFile } from "../core/policy/index.js";
-import { createSupervisor, listSupervisors, readSupervisor, runSupervisor, } from "../core/supervisor/index.js";
+import { configureSupervisorService, createSupervisor, listSupervisors, readSupervisor, readSupervisorServiceConfig, readSupervisorServiceStatus, requestSupervisorServiceStop, runSupervisor, runSupervisorServiceDaemon, spawnSupervisorService, supervisorServiceLogPath, } from "../core/supervisor/index.js";
 export function registerSupervisorCommand(program, emit) {
     const registry = createBuiltinHarnessRegistry();
     const supervisor = program
@@ -84,9 +84,214 @@ export function registerSupervisorCommand(program, emit) {
             emitSupervisor(readSupervisor(coordRoot, goalId), opts.json, emit, true);
         });
     });
+    registerServiceCommand(supervisor, registry, emit);
     registerRunCommand(supervisor, "tick", registry, emit);
     registerRunCommand(supervisor, "run", registry, emit);
 }
+function registerServiceCommand(supervisor, registry, emit) {
+    const service = supervisor
+        .command("service")
+        .description("Run explicitly enrolled durable goals in a restartable background service.");
+    addServiceOptions(service
+        .command("start [goal-ids...]")
+        .description("Configure and start the detached per-repository supervisor service."))
+        .option("--json", "Emit complete service status as JSON")
+        .action(async (goalIds, opts) => {
+        await withSupervisorRootAsync(emit, async (coordRoot) => {
+            prepareServiceConfig(coordRoot, goalIds, opts, registry);
+            const status = await spawnSupervisorService(coordRoot);
+            emitServiceStatus(status, opts.json, emit);
+        });
+    });
+    addServiceOptions(service
+        .command("run [goal-ids...]")
+        .description("Run the persistent service loop in the foreground for a process manager."))
+        .option("--json", "Emit terminal service status as JSON")
+        .action(async (goalIds, opts) => {
+        await withSupervisorRootAsync(emit, async (coordRoot) => {
+            const config = prepareServiceConfig(coordRoot, goalIds, opts, registry);
+            const status = await runSupervisorServiceDaemon({
+                coordRoot,
+                engine: serviceEngine(config, registry),
+                onLog: opts.json ? undefined : (line) => emit.text(`${line}\n`),
+            });
+            if (opts.json) {
+                emit.config({ format: "json" });
+                emit.data(status);
+            }
+        });
+    });
+    service
+        .command("status")
+        .description("Show service liveness, heartbeat, enrolled goals, and durable wake state.")
+        .option("--json", "Emit complete service status as JSON")
+        .action((opts) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+            emitServiceStatus(readSupervisorServiceStatus(coordRoot), opts.json, emit);
+        });
+    });
+    service
+        .command("stop")
+        .description("Request a graceful stop; an active goal tick is allowed to finish safely.")
+        .option("--json", "Emit complete service status as JSON")
+        .action(async (opts) => {
+        await withSupervisorRootAsync(emit, async (coordRoot) => {
+            let status = requestSupervisorServiceStop(coordRoot);
+            const deadline = Date.now() + 5_000;
+            while (status.running && Date.now() < deadline) {
+                await delay(50);
+                status = readSupervisorServiceStatus(coordRoot);
+            }
+            emitServiceStatus(status, opts.json, emit);
+        });
+    });
+    service
+        .command("logs")
+        .description("Show the tail of the private background-service log.")
+        .option("--lines <n>", "Number of lines to show (default 50)", "50")
+        .action((opts) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+            const lines = integer(opts.lines) ?? 50;
+            if (lines > 10_000)
+                throw new Error("service log lines must not exceed 10000");
+            const path = supervisorServiceLogPath(coordRoot);
+            if (!existsSync(path)) {
+                emit.text("no supervisor service log\n");
+                return;
+            }
+            const selected = readFileSync(path, "utf8")
+                .split("\n")
+                .slice(-(lines + 1))
+                .join("\n");
+            emit.text(selected.endsWith("\n") ? selected : `${selected}\n`);
+        });
+    });
+    service
+        .command("daemon", { hidden: true })
+        .description("Internal detached service entrypoint.")
+        .action(async () => {
+        await withSupervisorRootAsync(emit, async (coordRoot) => {
+            const config = readSupervisorServiceConfig(coordRoot);
+            await runSupervisorServiceDaemon({
+                coordRoot,
+                engine: serviceEngine(config, registry),
+                onLog: (line) => emit.text(`${line}\n`),
+            });
+        });
+    });
+}
+function addServiceOptions(command) {
+    return command
+        .option("--wake-interval-ms <n>", "State-change poll interval (default 5000)")
+        .option("--heartbeat-interval-ms <n>", "Heartbeat interval (default 2000)")
+        .option("--error-backoff-base-ms <n>", "Initial service-error backoff (default 2000)")
+        .option("--error-backoff-max-ms <n>", "Maximum service-error backoff (default 300000)")
+        .option("--harness <name>", "Fallback harness for agent calls without a specialist")
+        .option("--cwd <dir>", "Working directory for child agents")
+        .option("--subscription-only", "Require stored harness-login billing")
+        .option("--allow-api-billing", "Permit API-key override billing")
+        .option("--policy <file>", "Host policy JSON/JSONC")
+        .option("--isolation <mode>", "shared | worktree | sandbox | remote")
+        .option("--approval-to <address>", "Address durable ASK requests");
+}
+function prepareServiceConfig(coordRoot, goalIds, opts, registry) {
+    if (goalIds.length === 0) {
+        if (hasServiceConfigOverrides(opts)) {
+            throw new Error("goal ids are required when changing supervisor service options");
+        }
+        return readSupervisorServiceConfig(coordRoot);
+    }
+    if (opts.harness && !registry.get(opts.harness)) {
+        throw new Error(`unknown harness ${JSON.stringify(opts.harness)}`);
+    }
+    const policy = opts.policy ? loadPolicyFile(opts.policy) : undefined;
+    return configureSupervisorService({
+        coordRoot,
+        goalIds,
+        wakeIntervalMs: integer(opts.wakeIntervalMs),
+        heartbeatIntervalMs: integer(opts.heartbeatIntervalMs),
+        errorBackoffBaseMs: integer(opts.errorBackoffBaseMs),
+        errorBackoffMaxMs: integer(opts.errorBackoffMaxMs),
+        engine: {
+            default_harness: opts.harness,
+            cwd: opts.cwd,
+            subscription_only: opts.subscriptionOnly === true ? true : workflowSubscriptionOnly(coordRoot),
+            allow_api_billing: opts.allowApiBilling,
+            policy,
+            isolation: opts.isolation,
+            approval_addressee: opts.approvalTo,
+        },
+    });
+}
+function hasServiceConfigOverrides(opts) {
+    return Boolean(opts.wakeIntervalMs ||
+        opts.heartbeatIntervalMs ||
+        opts.errorBackoffBaseMs ||
+        opts.errorBackoffMaxMs ||
+        opts.harness ||
+        opts.cwd ||
+        opts.subscriptionOnly ||
+        opts.allowApiBilling ||
+        opts.policy ||
+        opts.isolation ||
+        opts.approvalTo);
+}
+function serviceEngine(config, registry) {
+    return {
+        spawners: registry.spawners(),
+        defaultHarness: config.engine.default_harness,
+        cwd: config.engine.cwd,
+        subscriptionOnly: config.engine.subscription_only,
+        allowApiBilling: config.engine.allow_api_billing,
+        harnessEvidence: Object.fromEntries(registry
+            .list()
+            .map((adapter) => [
+            adapter.profile.id,
+            { toolEvidence: adapter.profile.capabilities.toolEvidence },
+        ])),
+        policy: config.engine.policy,
+        approvalMode: "park",
+        approvalAddressee: config.engine.approval_addressee,
+        isolation: config.engine.isolation,
+        networkAccess: "enabled",
+    };
+}
+function emitServiceStatus(status, json, emit) {
+    if (json) {
+        emit.config({ format: "json" });
+        emit.data(status);
+        return;
+    }
+    if (!status.config && !status.record) {
+        emit.text("supervisor service: unconfigured\n");
+        return;
+    }
+    const state = status.running
+        ? (status.record?.state ?? "running")
+        : status.stale
+            ? "stale"
+            : "stopped";
+    const lines = [
+        `supervisor service: ${state}`,
+        `goals: ${status.config?.goal_ids.join(", ") || "none"}`,
+    ];
+    if (status.record) {
+        lines.push(`pid: ${status.record.pid} on ${status.record.host}`);
+        lines.push(`heartbeat: ${status.record.heartbeat_at}`);
+        lines.push(`sweeps: ${status.record.sweep_count}`);
+        if (status.record.active_goal_id)
+            lines.push(`active: ${status.record.active_goal_id}`);
+        if (status.record.next_wake_at)
+            lines.push(`next wake: ${status.record.next_wake_at}`);
+        if (status.record.last_error)
+            lines.push(`error: ${status.record.last_error}`);
+    }
+    const backingOff = Object.entries(status.runtime?.goals ?? {}).filter(([, runtime]) => runtime.state === "backoff");
+    if (backingOff.length) {
+        lines.push(`backoff: ${backingOff.map(([goalId]) => goalId).join(", ")}`);
+    }
+    emit.text(`${lines.join("\n")}\n`);
+}
 function registerRunCommand(supervisor, mode, registry, emit) {
     supervisor
         .command(`${mode} <goal-id>`)
@@ -200,6 +405,9 @@ function integer(value) {
         throw new Error(`expected a positive integer, got ${JSON.stringify(value)}`);
     return Number.parseInt(value, 10);
 }
+function delay(ms) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
 function withSupervisorRoot(emit, fn) {
     const coordRoot = findCoordRoot();
     if (!coordRoot) {

package/dist/core/supervisor/index.d.ts

@@ -1,3 +1,4 @@
 export { type RunSupervisorInput, runSupervisor, type SupervisorDispatchOutcome, type SupervisorRunReport, type SupervisorStopReason, } from "./runner.js";
+export { type ConfigureSupervisorServiceInput, configureSupervisorService, type RunSupervisorServiceDaemonInput, type RunSupervisorServiceSweepInput, readSupervisorServiceConfig, readSupervisorServiceRuntime, readSupervisorServiceStatus, requestSupervisorServiceStop, runSupervisorServiceDaemon, runSupervisorServiceSweep, SUPERVISOR_SERVICE_CONFIG_SCHEMA_VERSION, SUPERVISOR_SERVICE_RUNTIME_SCHEMA_VERSION, SUPERVISOR_SERVICE_STATUS_SCHEMA_VERSION, type SupervisorServiceConfig, type SupervisorServiceEngineConfig, type SupervisorServiceGoalRuntime, type SupervisorServiceGoalState, type SupervisorServiceProcessState, type SupervisorServiceRuntime, type SupervisorServiceStatus, type SupervisorServiceStatusRecord, type SupervisorServiceSweepOutcome, type SupervisorServiceSweepReport, spawnSupervisorService, supervisorServiceLogPath, } from "./service.js";
 export { assertSupervisorId, type CreateSupervisorInput, collectSupervisorWork, createSupervisor, listSupervisors, newSupervisorId, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, type SupervisorAutomationPolicy, type SupervisorIntent, type SupervisorLimits, type SupervisorNextAction, type SupervisorProjection, type SupervisorRecord, type SupervisorState, } from "./state.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/core/supervisor/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,EACd,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,+BAA+B,EACpC,0BAA0B,EAC1B,KAAK,+BAA+B,EACpC,KAAK,8BAA8B,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,wCAAwC,EACxC,yCAAyC,EACzC,wCAAwC,EACxC,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,EACd,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC"}

package/dist/core/supervisor/index.js

@@ -1,2 +1,3 @@
 export { runSupervisor, } from "./runner.js";
+export { configureSupervisorService, readSupervisorServiceConfig, readSupervisorServiceRuntime, readSupervisorServiceStatus, requestSupervisorServiceStop, runSupervisorServiceDaemon, runSupervisorServiceSweep, SUPERVISOR_SERVICE_CONFIG_SCHEMA_VERSION, SUPERVISOR_SERVICE_RUNTIME_SCHEMA_VERSION, SUPERVISOR_SERVICE_STATUS_SCHEMA_VERSION, spawnSupervisorService, supervisorServiceLogPath, } from "./service.js";
 export { assertSupervisorId, collectSupervisorWork, createSupervisor, listSupervisors, newSupervisorId, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, } from "./state.js";

package/dist/core/supervisor/read.d.ts

@@ -1,2 +1,4 @@
+export type { SupervisorServiceConfig, SupervisorServiceGoalRuntime, SupervisorServiceGoalState, SupervisorServiceProcessState, SupervisorServiceRuntime, SupervisorServiceStatus, SupervisorServiceStatusRecord, } from "./service.js";
+export { readSupervisorServiceConfig, readSupervisorServiceRuntime, readSupervisorServiceStatus, supervisorServiceLogPath, } from "./service-read.js";
 export { assertSupervisorId, collectSupervisorWork, listSupervisors, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, type SupervisorAutomationPolicy, type SupervisorIntent, type SupervisorLimits, type SupervisorNextAction, type SupervisorProjection, type SupervisorRecord, type SupervisorState, } from "./state.js";
 //# sourceMappingURL=read.d.ts.map

package/dist/core/supervisor/read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/read.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/read.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,uBAAuB,EACvB,4BAA4B,EAC5B,0BAA0B,EAC1B,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC"}

package/dist/core/supervisor/read.js

@@ -1 +1,2 @@
+export { readSupervisorServiceConfig, readSupervisorServiceRuntime, readSupervisorServiceStatus, supervisorServiceLogPath, } from "./service-read.js";
 export { assertSupervisorId, collectSupervisorWork, listSupervisors, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, } from "./state.js";

package/dist/core/supervisor/service-read.d.ts

@@ -0,0 +1,6 @@
+import type { SupervisorServiceConfig, SupervisorServiceRuntime, SupervisorServiceStatus } from "./service.js";
+export declare function readSupervisorServiceConfig(coordRootRaw: string): SupervisorServiceConfig;
+export declare function readSupervisorServiceRuntime(coordRootRaw: string): SupervisorServiceRuntime | undefined;
+export declare function readSupervisorServiceStatus(coordRootRaw: string): SupervisorServiceStatus;
+export declare function supervisorServiceLogPath(coordRoot: string): string;
+//# sourceMappingURL=service-read.d.ts.map

package/dist/core/supervisor/service-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-read.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/service-read.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EAExB,MAAM,cAAc,CAAC;AAMtB,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,uBAAuB,CA0BzF;AAED,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,MAAM,GACnB,wBAAwB,GAAG,SAAS,CAgBtC;AAED,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,uBAAuB,CAkBzF;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE"}

package/dist/core/supervisor/service-read.js

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_GOALS = 100;
+const FOREIGN_STATUS_STALE_MS = 30_000;
+export function readSupervisorServiceConfig(coordRootRaw) {
+    const coordRoot = resolve(coordRootRaw);
+    const config = readBoundedJson(join(serviceDir(coordRoot), "config.json"), "supervisor service configuration");
+    if (config.schema_version !== 1 ||
+        !validTimestamp(config.created_at) ||
+        !Array.isArray(config.goal_ids) ||
+        config.goal_ids.length < 1 ||
+        config.goal_ids.length > MAX_GOALS ||
+        config.goal_ids.some((goalId) => typeof goalId !== "string" || !goalId.trim()) ||
+        !positive(config.wake_interval_ms) ||
+        !positive(config.heartbeat_interval_ms) ||
+        !positive(config.error_backoff_base_ms) ||
+        !positive(config.error_backoff_max_ms) ||
+        config.error_backoff_max_ms < config.error_backoff_base_ms ||
+        !config.engine ||
+        typeof config.engine !== "object" ||
+        typeof config.engine.subscription_only !== "boolean" ||
+        typeof config.engine.allow_api_billing !== "boolean") {
+        throw new Error("supervisor service configuration has an unsupported schema");
+    }
+    return config;
+}
+export function readSupervisorServiceRuntime(coordRootRaw) {
+    const coordRoot = resolve(coordRootRaw);
+    const path = join(serviceDir(coordRoot), "runtime.json");
+    if (!existsSync(path))
+        return undefined;
+    const runtime = readBoundedJson(path, "supervisor service runtime");
+    if (runtime.schema_version !== 1 ||
+        !validTimestamp(runtime.config_created_at) ||
+        !validTimestamp(runtime.updated_at) ||
+        !runtime.goals ||
+        typeof runtime.goals !== "object" ||
+        Array.isArray(runtime.goals)) {
+        throw new Error("supervisor service runtime has an unsupported schema");
+    }
+    return runtime;
+}
+export function readSupervisorServiceStatus(coordRootRaw) {
+    const coordRoot = resolve(coordRootRaw);
+    const record = readStatusRecord(coordRoot);
+    let config;
+    let runtime;
+    try {
+        config = readSupervisorServiceConfig(coordRoot);
+    }
+    catch {
+        // Unconfigured or corrupt service state is represented without throwing.
+    }
+    try {
+        runtime = readSupervisorServiceRuntime(coordRoot);
+    }
+    catch {
+        // Runtime is recoverable and must not make the dashboard unreadable.
+    }
+    if (!record)
+        return { running: false, stale: false, config, runtime };
+    const running = statusOwnerIsLive(record);
+    return { running, stale: !running && record.state !== "stopped", record, config, runtime };
+}
+export function supervisorServiceLogPath(coordRoot) {
+    return join(serviceDir(resolve(coordRoot)), "service.log");
+}
+function readStatusRecord(coordRoot) {
+    const path = join(serviceDir(coordRoot), "status.json");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const value = readBoundedJson(path, "supervisor service status");
+        if (value.schema_version !== 1 ||
+            !Number.isSafeInteger(value.pid) ||
+            value.pid < 1 ||
+            typeof value.host !== "string" ||
+            typeof value.nonce !== "string" ||
+            !validTimestamp(value.started_at) ||
+            !validTimestamp(value.heartbeat_at)) {
+            return undefined;
+        }
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+function statusOwnerIsLive(record) {
+    if (record.state === "stopped")
+        return false;
+    if (record.host === hostname()) {
+        try {
+            process.kill(record.pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code === "EPERM";
+        }
+    }
+    const age = Date.now() - Date.parse(record.heartbeat_at);
+    return Number.isFinite(age) && age < FOREIGN_STATUS_STALE_MS;
+}
+function readBoundedJson(path, label) {
+    if (!existsSync(path))
+        throw new Error(`${label} does not exist`);
+    const size = statSync(path).size;
+    if (size <= 0 || size > MAX_FILE_BYTES)
+        throw new Error(`${label} has invalid size ${size}`);
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`cannot parse ${label}: ${error.message}`);
+    }
+}
+function serviceDir(coordRoot) {
+    return join(coordRoot, ".harnery", "supervisor-service");
+}
+function positive(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+function validTimestamp(value) {
+    return typeof value === "string" && value.length <= 40 && Number.isFinite(Date.parse(value));
+}

package/dist/core/supervisor/service.d.ts

@@ -0,0 +1,114 @@
+import { type NormalizedPolicy, type PolicyIsolation } from "../policy/index.js";
+import type { RunWorkItemInput } from "../work/index.js";
+import { type SupervisorRunReport, type SupervisorStopReason } from "./runner.js";
+import { type SupervisorRecord } from "./state.js";
+export declare const SUPERVISOR_SERVICE_CONFIG_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_SERVICE_RUNTIME_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_SERVICE_STATUS_SCHEMA_VERSION: 1;
+export interface SupervisorServiceEngineConfig {
+    default_harness?: string;
+    cwd?: string;
+    subscription_only: boolean;
+    allow_api_billing: boolean;
+    policy?: NormalizedPolicy;
+    isolation?: PolicyIsolation;
+    approval_addressee?: string;
+}
+export interface SupervisorServiceConfig {
+    schema_version: typeof SUPERVISOR_SERVICE_CONFIG_SCHEMA_VERSION;
+    goal_ids: string[];
+    wake_interval_ms: number;
+    heartbeat_interval_ms: number;
+    error_backoff_base_ms: number;
+    error_backoff_max_ms: number;
+    engine: SupervisorServiceEngineConfig;
+    created_at: string;
+}
+export interface ConfigureSupervisorServiceInput {
+    coordRoot: string;
+    goalIds: readonly string[];
+    wakeIntervalMs?: number;
+    heartbeatIntervalMs?: number;
+    errorBackoffBaseMs?: number;
+    errorBackoffMaxMs?: number;
+    engine?: Partial<SupervisorServiceEngineConfig>;
+}
+export type SupervisorServiceGoalState = "idle" | "backoff" | "awaiting_change";
+export interface SupervisorServiceGoalRuntime {
+    state: SupervisorServiceGoalState;
+    consecutive_errors: number;
+    observed_fingerprint?: string;
+    next_wake_at?: string;
+    last_tick_at?: string;
+    last_stop_reason?: SupervisorStopReason;
+    last_error?: string;
+}
+export interface SupervisorServiceRuntime {
+    schema_version: typeof SUPERVISOR_SERVICE_RUNTIME_SCHEMA_VERSION;
+    config_created_at: string;
+    updated_at: string;
+    goals: Record<string, SupervisorServiceGoalRuntime>;
+}
+export type SupervisorServiceProcessState = "starting" | "running" | "stopping" | "stopped";
+export interface SupervisorServiceStatusRecord {
+    schema_version: typeof SUPERVISOR_SERVICE_STATUS_SCHEMA_VERSION;
+    pid: number;
+    host: string;
+    nonce: string;
+    state: SupervisorServiceProcessState;
+    started_at: string;
+    heartbeat_at: string;
+    config_created_at: string;
+    sweep_count: number;
+    active_goal_id?: string;
+    last_sweep_at?: string;
+    next_wake_at?: string;
+    last_error?: string;
+    stopped_at?: string;
+}
+export interface SupervisorServiceStatus {
+    running: boolean;
+    stale: boolean;
+    record?: SupervisorServiceStatusRecord;
+    config?: SupervisorServiceConfig;
+    runtime?: SupervisorServiceRuntime;
+}
+export interface SupervisorServiceSweepOutcome {
+    goal_id: string;
+    action: "tick" | "skip" | "backoff";
+    reason: string;
+    stop_reason?: SupervisorStopReason;
+    next_wake_at?: string;
+}
+export interface SupervisorServiceSweepReport {
+    started_at: string;
+    ended_at: string;
+    outcomes: SupervisorServiceSweepOutcome[];
+}
+export interface RunSupervisorServiceSweepInput {
+    coordRoot: string;
+    config: SupervisorServiceConfig;
+    engine?: Omit<RunWorkItemInput["engine"], "maxAgents" | "concurrency" | "specialists">;
+    actor?: string;
+    now?: () => number;
+    readGoal?: (coordRoot: string, goalId: string) => SupervisorRecord;
+    runGoal?: (goalId: string) => Promise<SupervisorRunReport>;
+    onGoalStart?: (goalId: string) => void;
+}
+export interface RunSupervisorServiceDaemonInput {
+    coordRoot: string;
+    engine: Omit<RunWorkItemInput["engine"], "maxAgents" | "concurrency" | "specialists">;
+    actor?: string;
+    maxSweeps?: number;
+    onLog?: (line: string) => void;
+}
+export declare function configureSupervisorService(input: ConfigureSupervisorServiceInput): SupervisorServiceConfig;
+export declare function readSupervisorServiceConfig(coordRootRaw: string): SupervisorServiceConfig;
+export declare function readSupervisorServiceRuntime(coordRootRaw: string): SupervisorServiceRuntime | undefined;
+export declare function readSupervisorServiceStatus(coordRootRaw: string): SupervisorServiceStatus;
+export declare function spawnSupervisorService(coordRootRaw: string): Promise<SupervisorServiceStatus>;
+export declare function requestSupervisorServiceStop(coordRootRaw: string): SupervisorServiceStatus;
+export declare function runSupervisorServiceSweep(input: RunSupervisorServiceSweepInput): Promise<SupervisorServiceSweepReport>;
+export declare function runSupervisorServiceDaemon(input: RunSupervisorServiceDaemonInput): Promise<SupervisorServiceStatusRecord>;
+export declare function supervisorServiceLogPath(coordRoot: string): string;
+//# sourceMappingURL=service.d.ts.map

package/dist/core/supervisor/service.d.ts.map

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