harnery 0.13.0 → 0.15.0

package/dist/core/supervisor/runner.js

@@ -0,0 +1,198 @@
+import { resolve } from "node:path";
+import { acceptWorkItem, reconcileWorkItem, runWorkItem, } from "../work/index.js";
+import { acquireSupervisorLease, readSupervisorIgnoringLease, } from "./state.js";
+export async function runSupervisor(input) {
+    const coordRoot = resolve(input.coordRoot);
+    const mode = input.mode ?? "run";
+    const actor = input.actor?.trim() || `supervisor:${input.goalId}`;
+    const log = input.onLog ?? (() => undefined);
+    const startedAt = new Date().toISOString();
+    const startedMs = Date.now();
+    const release = acquireSupervisorLease(coordRoot, input.goalId);
+    let cycles = 0;
+    let dispatches = 0;
+    let acceptances = 0;
+    const outcomes = [];
+    try {
+        const initial = readSupervisorIgnoringLease(coordRoot, input.goalId);
+        const cycleLimit = mode === "tick" ? 1 : initial.intent.limits.max_cycles;
+        const deadline = startedMs + initial.intent.limits.max_runtime_ms;
+        while (cycles < cycleLimit) {
+            cycles++;
+            let record = refreshGraph(coordRoot, input.goalId, actor);
+            log(`[${record.intent.title}] cycle ${cycles}: ${record.projection.state}; ` +
+                `${record.projection.ready_work.length} ready, ${record.projection.attention_work.length} attention`);
+            if (record.projection.state === "succeeded") {
+                return report("succeeded", record.projection.reason, record);
+            }
+            if (Date.now() >= deadline) {
+                return report("budget_exhausted", "supervisor wall-time limit reached", record);
+            }
+            const before = graphFingerprint(record);
+            let changed = false;
+            if (record.intent.automation.accept_passing_proof) {
+                for (const work of record.work) {
+                    if (work.projection.state !== "in_review")
+                        continue;
+                    acceptWorkItem(coordRoot, work.intent.id, {
+                        actor,
+                        reason: "passing proof accepted by frozen supervisor policy",
+                    });
+                    acceptances++;
+                    changed = true;
+                    log(`[${record.intent.title}] accepted ${work.intent.id} from passing proof`);
+                }
+                if (changed)
+                    record = refreshGraph(coordRoot, input.goalId, actor);
+                if (record.projection.state === "succeeded") {
+                    return report("succeeded", record.projection.reason, record);
+                }
+            }
+            const candidates = selectCandidates(record);
+            const selected = selectWithinAttemptBudget(record, candidates).slice(0, record.intent.limits.max_parallel_work);
+            if (selected.length > 0 && Date.now() < deadline) {
+                const settled = await Promise.all(selected.map(async (candidate) => {
+                    dispatches++;
+                    log(`[${record.intent.title}] ${candidate.action} ${candidate.record.intent.id}`);
+                    try {
+                        const result = await runWorkItem({
+                            coordRoot,
+                            workId: candidate.record.intent.id,
+                            retry: candidate.action === "retry",
+                            actor,
+                            engine: {
+                                ...input.engine,
+                                specialists: record.intent.specialists,
+                                maxAgents: record.intent.limits.max_agents_per_work,
+                                concurrency: record.intent.limits.agent_concurrency,
+                            },
+                        });
+                        return {
+                            work_id: candidate.record.intent.id,
+                            action: candidate.action,
+                            status: "completed",
+                            run_id: result.runId,
+                        };
+                    }
+                    catch (error) {
+                        const latest = reconcileWorkItem(coordRoot, candidate.record.intent.id, actor);
+                        return {
+                            work_id: candidate.record.intent.id,
+                            action: candidate.action,
+                            status: latest.projection.state === "awaiting_approval" ? "parked" : "failed",
+                            run_id: latest.projection.latest_run_id,
+                            error: boundedError(error.message),
+                        };
+                    }
+                }));
+                outcomes.push(...settled);
+                changed = true;
+            }
+            record = refreshGraph(coordRoot, input.goalId, actor);
+            const after = graphFingerprint(record);
+            if (record.projection.state === "succeeded") {
+                return report("succeeded", record.projection.reason, record);
+            }
+            if (mode === "tick") {
+                return report(before === after ? "no_progress" : "tick_complete", before === after
+                    ? "the tick found no legal progress action"
+                    : "one bounded supervisor cycle completed", record);
+            }
+            if (Date.now() >= deadline) {
+                return report("budget_exhausted", "supervisor wall-time limit reached", record);
+            }
+            if (record.projection.state === "budget_exhausted") {
+                return report("budget_exhausted", record.projection.reason, record);
+            }
+            if (selected.length === 0 && !changed) {
+                return report(stopForProjection(record.projection), record.projection.reason, record);
+            }
+            if (selected.length === 0 && record.projection.state !== "ready") {
+                return report(stopForProjection(record.projection), record.projection.reason, record);
+            }
+            if (before === after) {
+                return report("no_progress", "a supervisor cycle produced no durable state change", record);
+            }
+        }
+        const final = refreshGraph(coordRoot, input.goalId, actor);
+        return report("budget_exhausted", `supervisor cycle limit reached (${cycleLimit})`, final);
+    }
+    finally {
+        release();
+    }
+    function report(stopReason, reason, record) {
+        const endedAt = new Date().toISOString();
+        return {
+            goal_id: input.goalId,
+            mode,
+            stop_reason: stopReason,
+            reason,
+            started_at: startedAt,
+            ended_at: endedAt,
+            duration_ms: Date.now() - startedMs,
+            cycles,
+            dispatches,
+            acceptances,
+            outcomes,
+            projection: record.projection,
+        };
+    }
+}
+function refreshGraph(coordRoot, goalId, actor) {
+    const before = readSupervisorIgnoringLease(coordRoot, goalId);
+    for (const work of before.work)
+        reconcileWorkItem(coordRoot, work.intent.id, actor);
+    return readSupervisorIgnoringLease(coordRoot, goalId);
+}
+function selectCandidates(record) {
+    const candidates = [];
+    for (const work of record.work) {
+        if (work.projection.state === "ready") {
+            candidates.push({ record: work, action: "run", consumesAttempt: true });
+            continue;
+        }
+        if (work.projection.state === "awaiting_approval" &&
+            work.projection.next_action === "resume" &&
+            record.intent.automation.resume_approved) {
+            candidates.push({ record: work, action: "resume", consumesAttempt: false });
+            continue;
+        }
+        if (work.projection.state === "blocked" &&
+            work.projection.next_action === "retry" &&
+            record.intent.automation.retry_blocked) {
+            candidates.push({ record: work, action: "retry", consumesAttempt: true });
+        }
+    }
+    return candidates;
+}
+function selectWithinAttemptBudget(record, candidates) {
+    let remaining = record.projection.attempts_remaining;
+    return candidates.filter((candidate) => {
+        if (!candidate.consumesAttempt)
+            return true;
+        if (remaining <= 0)
+            return false;
+        remaining--;
+        return true;
+    });
+}
+function graphFingerprint(record) {
+    return JSON.stringify(record.work.map((work) => [
+        work.intent.id,
+        work.projection.state,
+        work.projection.next_action,
+        work.projection.attempts_used,
+        work.events.length,
+    ]));
+}
+function stopForProjection(projection) {
+    if (projection.state === "budget_exhausted")
+        return "budget_exhausted";
+    if (projection.state === "blocked")
+        return "blocked";
+    return "awaiting_attention";
+}
+function boundedError(message) {
+    const normalized = message.replace(/\s+/g, " ").trim();
+    return normalized.length > 2_000 ? `${normalized.slice(0, 1_999)}…` : normalized;
+}

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

@@ -0,0 +1,69 @@
+import { type WorkRecord } from "../work/read.js";
+import type { WorkflowSpecialistProfile } from "../workflow/types.js";
+export declare const SUPERVISOR_INTENT_SCHEMA_VERSION: 1;
+export interface SupervisorLimits {
+    max_cycles: number;
+    max_runtime_ms: number;
+    max_parallel_work: number;
+    max_total_attempts: number;
+    max_agents_per_work: number;
+    agent_concurrency: number;
+}
+export interface SupervisorAutomationPolicy {
+    accept_passing_proof: boolean;
+    resume_approved: boolean;
+    retry_blocked: boolean;
+}
+export interface SupervisorIntent {
+    schema_version: typeof SUPERVISOR_INTENT_SCHEMA_VERSION;
+    id: string;
+    title: string;
+    root_work_id: string;
+    specialists: Record<string, WorkflowSpecialistProfile>;
+    limits: SupervisorLimits;
+    automation: SupervisorAutomationPolicy;
+    created_at: string;
+}
+export type SupervisorState = "ready" | "running" | "awaiting_attention" | "blocked" | "budget_exhausted" | "succeeded";
+export type SupervisorNextAction = "run" | "wait_for_run" | "resolve_approval" | "review" | "retry" | "none";
+export interface SupervisorProjection {
+    id: string;
+    title: string;
+    root_work_id: string;
+    state: SupervisorState;
+    reason: string;
+    next_action: SupervisorNextAction;
+    work_ids: string[];
+    ready_work: string[];
+    resumable_work: string[];
+    retryable_work: string[];
+    attention_work: string[];
+    attempts_used: number;
+    attempts_remaining: number;
+    specialists: string[];
+}
+export interface SupervisorRecord {
+    intent: SupervisorIntent;
+    projection: SupervisorProjection;
+    work: WorkRecord[];
+}
+export interface CreateSupervisorInput {
+    coordRoot: string;
+    rootWorkId: string;
+    specialists: Readonly<Record<string, WorkflowSpecialistProfile>>;
+    title?: string;
+    id?: string;
+    limits?: Partial<SupervisorLimits>;
+    automation?: Partial<SupervisorAutomationPolicy>;
+}
+export declare function createSupervisor(input: CreateSupervisorInput): SupervisorRecord;
+export declare function readSupervisor(coordRoot: string, goalId: string): SupervisorRecord;
+/** @internal Runner seam; ignores the lease held by this supervisor process. */
+export declare function readSupervisorIgnoringLease(coordRoot: string, goalId: string): SupervisorRecord;
+export declare function listSupervisors(coordRoot: string): SupervisorRecord[];
+export declare function collectSupervisorWork(coordRoot: string, rootWorkId: string): WorkRecord[];
+export declare function assertSupervisorId(goalId: string): void;
+export declare function newSupervisorId(): string;
+/** @internal Runner seam; one exclusive crash-recoverable supervisor lease. */
+export declare function acquireSupervisorLease(coordRoot: string, goalId: string): () => void;
+//# sourceMappingURL=state.d.ts.map

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

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

package/dist/core/supervisor/state.js

@@ -0,0 +1,413 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { assertWorkId, readWorkItem } from "../work/read.js";
+import { normalizeWorkflowSpecialists } from "../workflow/specialists.js";
+export const SUPERVISOR_INTENT_SCHEMA_VERSION = 1;
+const GOAL_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const MAX_TITLE = 200;
+const MAX_INTENT_BYTES = 256 * 1024;
+const FOREIGN_LEASE_STALE_MS = 24 * 60 * 60 * 1_000;
+export function createSupervisor(input) {
+    const coordRoot = resolve(input.coordRoot);
+    assertWorkId(input.rootWorkId);
+    const root = readWorkItem(coordRoot, input.rootWorkId);
+    const id = input.id ?? newSupervisorId();
+    assertSupervisorId(id);
+    const intent = {
+        schema_version: SUPERVISOR_INTENT_SCHEMA_VERSION,
+        id,
+        title: bounded(input.title ?? root.intent.title, "supervisor title", MAX_TITLE),
+        root_work_id: input.rootWorkId,
+        specialists: normalizeWorkflowSpecialists(input.specialists),
+        limits: normalizeLimits(input.limits),
+        automation: normalizeAutomation(input.automation),
+        created_at: new Date().toISOString(),
+    };
+    const path = supervisorIntentPath(coordRoot, id);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(path), 0o700);
+    writePrivateJson(path, intent);
+    return readSupervisor(coordRoot, id);
+}
+export function readSupervisor(coordRoot, goalId) {
+    return readSupervisorInternal(coordRoot, goalId, false);
+}
+/** @internal Runner seam; ignores the lease held by this supervisor process. */
+export function readSupervisorIgnoringLease(coordRoot, goalId) {
+    return readSupervisorInternal(coordRoot, goalId, true);
+}
+export function listSupervisors(coordRoot) {
+    const base = join(resolve(coordRoot), ".harnery", "supervisors");
+    if (!existsSync(base))
+        return [];
+    const records = [];
+    for (const name of readdirSync(base)) {
+        if (!GOAL_ID.test(name) || !existsSync(supervisorIntentPath(coordRoot, name)))
+            continue;
+        records.push(readSupervisor(coordRoot, name));
+    }
+    return records.sort((left, right) => right.intent.created_at.localeCompare(left.intent.created_at));
+}
+export function collectSupervisorWork(coordRoot, rootWorkId) {
+    const records = new Map();
+    const visiting = new Set();
+    const visit = (workId) => {
+        if (records.has(workId))
+            return;
+        if (visiting.has(workId))
+            throw new Error(`supervisor work graph contains a cycle at ${workId}`);
+        visiting.add(workId);
+        const record = readWorkItem(coordRoot, workId);
+        for (const dependency of record.intent.dependencies)
+            visit(dependency);
+        visiting.delete(workId);
+        records.set(workId, record);
+    };
+    visit(rootWorkId);
+    return Array.from(records.values());
+}
+export function assertSupervisorId(goalId) {
+    if (!GOAL_ID.test(goalId))
+        throw new Error(`invalid supervisor id ${JSON.stringify(goalId)}`);
+}
+export function newSupervisorId() {
+    return `goal-${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
+}
+/** @internal Runner seam; one exclusive crash-recoverable supervisor lease. */
+export function acquireSupervisorLease(coordRoot, goalId) {
+    readSupervisorIntent(coordRoot, goalId);
+    const path = join(supervisorDir(coordRoot, goalId), "lease.json");
+    const owner = {
+        pid: process.pid,
+        host: hostname(),
+        created_at: new Date().toISOString(),
+        nonce: randomUUID(),
+    };
+    const acquire = () => {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            try {
+                writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8");
+            }
+            finally {
+                closeSync(fd);
+            }
+            chmodSync(path, 0o600);
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            return false;
+        }
+    };
+    if (!acquire()) {
+        const existing = readLease(path);
+        if (existing && leaseIsLive(existing)) {
+            throw new Error(`supervisor ${goalId} is already running under pid ${existing.pid} on ${existing.host}`);
+        }
+        unlinkSync(path);
+        if (!acquire())
+            throw new Error(`supervisor ${goalId} lease raced with another process`);
+    }
+    return () => {
+        try {
+            const existing = readLease(path);
+            if (existing?.nonce === owner.nonce)
+                unlinkSync(path);
+        }
+        catch {
+            // A stale private lease is recoverable by the next explicit run.
+        }
+    };
+}
+function readSupervisorInternal(coordRootRaw, goalId, ignoreLease) {
+    const coordRoot = resolve(coordRootRaw);
+    const intent = readSupervisorIntent(coordRoot, goalId);
+    const work = collectSupervisorWork(coordRoot, intent.root_work_id);
+    return {
+        intent,
+        work,
+        projection: deriveProjection(coordRoot, intent, work, ignoreLease),
+    };
+}
+function deriveProjection(coordRoot, intent, work, ignoreLease) {
+    const root = work.find((record) => record.intent.id === intent.root_work_id);
+    if (!root)
+        throw new Error(`supervisor ${intent.id} root work is missing`);
+    const attemptsUsed = work.reduce((sum, record) => sum + record.projection.attempts_used, 0);
+    const readyWork = work
+        .filter((record) => record.projection.state === "ready")
+        .map((record) => record.intent.id);
+    const resumableWork = work
+        .filter((record) => record.projection.state === "awaiting_approval" &&
+        record.projection.next_action === "resume")
+        .map((record) => record.intent.id);
+    const retryableWork = work
+        .filter((record) => record.projection.state === "blocked" && record.projection.next_action === "retry")
+        .map((record) => record.intent.id);
+    const pendingApproval = work
+        .filter((record) => record.projection.state === "awaiting_approval" &&
+        record.projection.next_action === "resolve_approval")
+        .map((record) => record.intent.id);
+    const reviews = work
+        .filter((record) => record.projection.state === "in_review")
+        .map((record) => record.intent.id);
+    const cancelled = work
+        .filter((record) => record.projection.state === "cancelled")
+        .map((record) => record.intent.id);
+    const terminalBlocked = work
+        .filter((record) => record.projection.state === "blocked" && record.projection.next_action === "none")
+        .map((record) => record.intent.id);
+    const attentionWork = unique([
+        ...pendingApproval,
+        ...(intent.automation.accept_passing_proof ? [] : reviews),
+        ...(intent.automation.resume_approved ? [] : resumableWork),
+        ...(intent.automation.retry_blocked ? [] : retryableWork),
+        ...cancelled,
+        ...terminalBlocked,
+    ]);
+    const base = {
+        id: intent.id,
+        title: intent.title,
+        root_work_id: intent.root_work_id,
+        work_ids: work.map((record) => record.intent.id),
+        ready_work: readyWork,
+        resumable_work: resumableWork,
+        retryable_work: retryableWork,
+        attention_work: attentionWork,
+        attempts_used: attemptsUsed,
+        attempts_remaining: Math.max(0, intent.limits.max_total_attempts - attemptsUsed),
+        specialists: Object.keys(intent.specialists),
+    };
+    if (!ignoreLease && supervisorLeaseIsLive(coordRoot, intent.id)) {
+        return {
+            ...base,
+            state: "running",
+            reason: "the foreground supervisor holds the goal lease",
+            next_action: "wait_for_run",
+        };
+    }
+    if (root.projection.state === "succeeded") {
+        return {
+            ...base,
+            state: "succeeded",
+            reason: "root work was explicitly accepted",
+            next_action: "none",
+        };
+    }
+    const resumableDispatchable = intent.automation.resume_approved ? resumableWork : [];
+    const attemptDispatchable = [
+        ...readyWork,
+        ...(intent.automation.retry_blocked ? retryableWork : []),
+    ];
+    const dispatchable = [...resumableDispatchable, ...attemptDispatchable];
+    if (intent.automation.accept_passing_proof && reviews.length > 0) {
+        return {
+            ...base,
+            state: "ready",
+            reason: `${reviews.length} passing work item${reviews.length === 1 ? "" : "s"} may be accepted by frozen policy`,
+            next_action: "run",
+        };
+    }
+    if (resumableDispatchable.length > 0) {
+        return {
+            ...base,
+            state: "ready",
+            reason: `${resumableDispatchable.length} parked run${resumableDispatchable.length === 1 ? " is" : "s are"} resumable`,
+            next_action: "run",
+        };
+    }
+    if (attemptsUsed >= intent.limits.max_total_attempts && attemptDispatchable.length > 0) {
+        return {
+            ...base,
+            state: "budget_exhausted",
+            reason: `goal exhausted its ${intent.limits.max_total_attempts} total attempts`,
+            next_action: "none",
+        };
+    }
+    if (dispatchable.length > 0) {
+        return {
+            ...base,
+            state: "ready",
+            reason: `${dispatchable.length} work item${dispatchable.length === 1 ? " is" : "s are"} dispatchable`,
+            next_action: "run",
+        };
+    }
+    if (pendingApproval.length > 0) {
+        return {
+            ...base,
+            state: "awaiting_attention",
+            reason: `${pendingApproval.length} work item${pendingApproval.length === 1 ? " needs" : "s need"} approval`,
+            next_action: "resolve_approval",
+        };
+    }
+    if (reviews.length > 0) {
+        return {
+            ...base,
+            state: "awaiting_attention",
+            reason: `${reviews.length} work item${reviews.length === 1 ? " awaits" : "s await"} explicit review`,
+            next_action: "review",
+        };
+    }
+    if (resumableWork.length > 0) {
+        return {
+            ...base,
+            state: "awaiting_attention",
+            reason: `${resumableWork.length} resolved approval${resumableWork.length === 1 ? " requires" : "s require"} explicit resume`,
+            next_action: "run",
+        };
+    }
+    if (retryableWork.length > 0) {
+        return {
+            ...base,
+            state: "blocked",
+            reason: `${retryableWork.length} blocked work item${retryableWork.length === 1 ? " requires" : "s require"} explicit retry`,
+            next_action: "retry",
+        };
+    }
+    return {
+        ...base,
+        state: "blocked",
+        reason: attentionWork.length > 0
+            ? `${attentionWork.length} work item${attentionWork.length === 1 ? " needs" : "s need"} intervention`
+            : "goal graph has no legal progress action",
+        next_action: "none",
+    };
+}
+function readSupervisorIntent(coordRoot, goalId) {
+    assertSupervisorId(goalId);
+    const path = supervisorIntentPath(coordRoot, goalId);
+    if (!existsSync(path))
+        throw new Error(`supervisor ${goalId} does not exist`);
+    const size = statSync(path).size;
+    if (size <= 0 || size > MAX_INTENT_BYTES) {
+        throw new Error(`supervisor intent has invalid size ${size}`);
+    }
+    let intent;
+    try {
+        intent = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`cannot parse supervisor intent ${goalId}: ${error.message}`);
+    }
+    validateIntent(intent, goalId);
+    return intent;
+}
+function validateIntent(intent, goalId) {
+    if (intent.schema_version !== SUPERVISOR_INTENT_SCHEMA_VERSION ||
+        intent.id !== goalId ||
+        !validTimestamp(intent.created_at)) {
+        throw new Error(`supervisor intent ${goalId} has an unsupported or mismatched schema`);
+    }
+    bounded(intent.title, "supervisor title", MAX_TITLE);
+    assertWorkId(intent.root_work_id);
+    const specialists = normalizeWorkflowSpecialists(intent.specialists);
+    if (JSON.stringify(specialists) !== JSON.stringify(intent.specialists)) {
+        throw new Error(`supervisor intent ${goalId} specialists are not canonical`);
+    }
+    if (JSON.stringify(normalizeLimits(intent.limits)) !== JSON.stringify(intent.limits)) {
+        throw new Error(`supervisor intent ${goalId} limits are not canonical`);
+    }
+    if (JSON.stringify(normalizeAutomation(intent.automation)) !== JSON.stringify(intent.automation)) {
+        throw new Error(`supervisor intent ${goalId} automation policy is not canonical`);
+    }
+}
+function normalizeLimits(input) {
+    return {
+        max_cycles: positive(input?.max_cycles ?? 50, "supervisor max_cycles", 1_000),
+        max_runtime_ms: positive(input?.max_runtime_ms ?? 4 * 60 * 60 * 1_000, "supervisor max_runtime_ms", 7 * 24 * 60 * 60 * 1_000),
+        max_parallel_work: positive(input?.max_parallel_work ?? 1, "supervisor max_parallel_work", 20),
+        max_total_attempts: positive(input?.max_total_attempts ?? 100, "supervisor max_total_attempts", 10_000),
+        max_agents_per_work: positive(input?.max_agents_per_work ?? 20, "supervisor max_agents_per_work", 1_000),
+        agent_concurrency: positive(input?.agent_concurrency ?? 4, "supervisor agent_concurrency", 100),
+    };
+}
+function normalizeAutomation(input) {
+    return {
+        accept_passing_proof: boolean(input?.accept_passing_proof ?? false, "accept_passing_proof"),
+        resume_approved: boolean(input?.resume_approved ?? true, "resume_approved"),
+        retry_blocked: boolean(input?.retry_blocked ?? false, "retry_blocked"),
+    };
+}
+function supervisorDir(coordRoot, goalId) {
+    assertSupervisorId(goalId);
+    return join(resolve(coordRoot), ".harnery", "supervisors", goalId);
+}
+function supervisorIntentPath(coordRoot, goalId) {
+    return join(supervisorDir(coordRoot, goalId), "intent.json");
+}
+function supervisorLeaseIsLive(coordRoot, goalId) {
+    const lease = readLease(join(supervisorDir(coordRoot, goalId), "lease.json"));
+    return lease ? leaseIsLive(lease) : false;
+}
+function readLease(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return typeof value.pid === "number" &&
+            Number.isSafeInteger(value.pid) &&
+            value.pid > 0 &&
+            typeof value.host === "string" &&
+            typeof value.created_at === "string"
+            ? {
+                pid: value.pid,
+                host: value.host,
+                created_at: value.created_at,
+                nonce: typeof value.nonce === "string" ? value.nonce : undefined,
+            }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function leaseIsLive(lease) {
+    if (lease.host !== hostname()) {
+        const age = Date.now() - Date.parse(lease.created_at);
+        return Number.isFinite(age) && age < FOREIGN_LEASE_STALE_MS;
+    }
+    try {
+        process.kill(lease.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function writePrivateJson(path, value) {
+    const body = `${JSON.stringify(value, null, 2)}\n`;
+    if (Buffer.byteLength(body) > MAX_INTENT_BYTES) {
+        throw new Error(`supervisor intent exceeds ${MAX_INTENT_BYTES} bytes`);
+    }
+    writeFileSync(path, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+function bounded(value, field, max) {
+    if (typeof value !== "string")
+        throw new Error(`${field} must be a string`);
+    const normalized = value.trim();
+    if (!normalized)
+        throw new Error(`${field} must not be empty`);
+    if (normalized.length > max)
+        throw new Error(`${field} exceeds ${max} characters`);
+    return normalized;
+}
+function positive(value, field, max) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > max) {
+        throw new Error(`${field} must be an integer from 1 to ${max}`);
+    }
+    return value;
+}
+function boolean(value, field) {
+    if (typeof value !== "boolean")
+        throw new Error(`supervisor ${field} must be boolean`);
+    return value;
+}
+function validTimestamp(value) {
+    return typeof value === "string" && value.length <= 40 && Number.isFinite(Date.parse(value));
+}
+function unique(values) {
+    return [...new Set(values)];
+}