@schema-weaver/pg-connector 0.0.0-stage → 2.0.1

package/dist/esm/cli/daemon/fault-shutdown.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Fail-closed shutdown on an unexpected process-level fault.
+ *
+ * Node's default behaviour for `uncaughtException` and `unhandledRejection` is
+ * to print and terminate. Installing a handler that only records the error
+ * OVERRIDES that default: the process stays alive, keeps its PostgreSQL pools,
+ * its permission state and its audit writer, and keeps answering queries while
+ * running in a state nobody reasoned about. For a long-lived daemon that holds
+ * database credentials and executes DDL, "keep serving after an unknown fault"
+ * is the wrong answer — the correct answer is to stop, leave a durable trace,
+ * and let the supervisor restart it.
+ *
+ * Everything here is injectable so a test can assert the exit DECISION without
+ * killing the test runner: `exit`, `log`, the flush hooks and the clock are all
+ * parameters, and no module-level `process.exit` call exists in this file.
+ *
+ * ## The non-fatal rejection tag
+ *
+ * `unhandledRejection` is fail-closed by default, because a rejected promise
+ * nobody handled is a bug by definition and this daemon holds credentials. The
+ * single exception has to be explicit and greppable, so the only value that is
+ * allowed to be swallowed is one that a call site deliberately tagged:
+ *
+ * ```ts
+ * markNonFatalRejection(new Error('wake-channel reconnect already in flight'));
+ * ```
+ *
+ * It sets a non-enumerable symbol on the reason object. A `Symbol`, not a
+ * string field: it cannot collide with a database column, an error message or
+ * a JSON body, it does not survive serialisation (so it cannot be replayed by
+ * anything reading the value back), and nothing outside this module can set it
+ * except by calling {@link markNonFatalRejection}. A plain
+ * `{ nonFatal: true }` flag would be forgeable by any rejected object, which
+ * would make the tag no control at all.
+ */
+/** Which process-level event produced the fault. */
+export type FaultKind = 'uncaughtException' | 'unhandledRejection';
+/**
+ * Exit code used for a fail-closed fault. `EX_SOFTWARE` from `sysexits.h`: an
+ * internal software error, as opposed to a usage or configuration error. Any
+ * non-zero value satisfies `Restart=on-failure`; a distinct one means a fault
+ * restart is greppable in the journal and separable from an ordinary crash.
+ */
+export declare const FAULT_EXIT_CODE = 70;
+/**
+ * Upper bound on the best-effort flush before the process exits anyway.
+ *
+ * Short on purpose. The flush exists to get the last audit record onto the disk,
+ * not to complete an orderly shutdown: a daemon that cannot flush in two seconds
+ * is a daemon whose I/O is stuck, and waiting longer only widens the window in
+ * which a half-released pool keeps serving. Well under the five seconds the
+ * regression test allows.
+ */
+export declare const FAULT_FLUSH_TIMEOUT_MS = 2000;
+/**
+ * Marker for a rejection a call site has decided is safe to log and continue
+ * from. Non-enumerable, so the tag cannot be discovered by enumeration or
+ * serialisation of the reason.
+ */
+export declare const NON_FATAL_REJECTION_TAG: unique symbol;
+/**
+ * Tags a rejection as deliberately non-fatal.
+ *
+ * Only for a rejection that is genuinely a duplicate/benign outcome — a wake
+ * reconnect already in flight, a cancellation racing a completion. NEVER for a
+ * failure to record an audit record, to release a permit, to classify SQL, or to
+ * do anything the product promises not to hide.
+ */
+export declare function markNonFatalRejection<T>(reason: T): T;
+/** True when {@link markNonFatalRejection} was applied to this exact value. */
+export declare function isNonFatalRejection(reason: unknown): boolean;
+/** What the fault handler is allowed to touch. Every field is injectable. */
+export interface FaultShutdownDeps {
+    /**
+     * Records the fault in `errors.jsonl`. Must never throw; a fault handler that
+     * throws has replaced a contained failure with an uncontained one.
+     */
+    track: (err: unknown, opts: {
+        op: FaultKind;
+        level: 'fatal' | 'error' | 'warn';
+    }) => void;
+    /**
+     * Best-effort: makes the last appended record durable (append + fsync).
+     * Separate from `track` because `track` must not do I/O that can block.
+     */
+    flushLocalLog?: () => void;
+    /** Drains and fsyncs the audit sink. Registered by the daemon runtime. */
+    flushAudit?: () => Promise<void>;
+    /** Releases every PostgreSQL pool. Registered by the daemon runtime. */
+    closePools?: () => Promise<void>;
+    /** Operator/journal line. Must be synchronous; the exit can follow at once. */
+    log?: (line: string) => void;
+    /** Terminates the process. Injected so a test can observe the decision. */
+    exit: (code: number) => void;
+    /** Upper bound on the flush. Defaults to {@link FAULT_FLUSH_TIMEOUT_MS}. */
+    flushTimeoutMs?: number;
+}
+/** The decision the handler reached. Every field is asserted by the tests. */
+export interface FaultShutdownDecision {
+    /** True when this call asked the process to terminate. */
+    exit_requested: boolean;
+    /** The code passed to `exit`, or null when no exit was requested. */
+    exit_code: number | null;
+    /** True when this call was a no-op because an earlier fault is already exiting. */
+    suppressed_by_earlier_fault: boolean;
+    /** True when the rejection carried the explicit non-fatal tag. */
+    non_fatal: boolean;
+    /** True when every flush hook completed within the timeout. */
+    flushed: boolean;
+    /** True when the flush did not complete in time and the exit was forced. */
+    flush_timed_out: boolean;
+}
+/**
+ * One-shot fault handler for the whole process.
+ *
+ * Idempotent by construction: the first fault latches `firing` and every later
+ * one — including an `unhandledRejection` that lands while the first fault's
+ * flush is still in flight — returns a suppressed decision without a second
+ * flush and without a second `exit`. Without the latch, an uncaught exception
+ * followed immediately by the rejection it caused would flush and close twice,
+ * and the second `close()` on an already-closed pool rejects, which is exactly
+ * the kind of cascading undefined behaviour this module exists to stop.
+ */
+export interface FaultShutdownController {
+    handle(kind: FaultKind, err: unknown): Promise<FaultShutdownDecision>;
+    /** True once the first fatal fault has started the exit path. */
+    isFiring(): boolean;
+    /**
+     * Registers the audit/pool handles after construction.
+     *
+     * Needed because the daemon builds its audit sink and `PoolManager` AFTER it
+     * installs the process handlers — the handlers must exist before the parser
+     * load so a startup crash is tracked, and the sink does not exist until after
+     * that. Refuses once a fault is in flight: swapping the flush set mid-shutdown
+     * is how a half-completed flush becomes two.
+     */
+    setHooks(hooks: Pick<FaultShutdownDeps, 'flushAudit' | 'closePools'>): boolean;
+}
+/**
+ * Builds the controller. One per process; the process handlers hold a reference
+ * to it so they share the latch.
+ */
+export declare function createFaultShutdownController(deps: FaultShutdownDeps): FaultShutdownController;
+//# sourceMappingURL=fault-shutdown.d.ts.map

package/dist/esm/cli/daemon/fault-shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fault-shutdown.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/fault-shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,oDAAoD;AACpD,MAAM,MAAM,SAAS,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,eAA2C,CAAC;AAEhF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAiBrD;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAM5D;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,EAAE,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1F;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,+EAA+E;IAC/E,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,2EAA2E;IAC3E,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,cAAc,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mFAAmF;IACnF,2BAA2B,EAAE,OAAO,CAAC;IACrC,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAWD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACtE,iEAAiE;IACjE,QAAQ,IAAI,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,YAAY,GAAG,YAAY,CAAC,GAAG,OAAO,CAAC;CAChF;AAeD;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,iBAAiB,GAAG,uBAAuB,CA2I9F"}

package/dist/esm/cli/daemon/fault-shutdown.js

@@ -0,0 +1,273 @@
+/**
+ * Fail-closed shutdown on an unexpected process-level fault.
+ *
+ * Node's default behaviour for `uncaughtException` and `unhandledRejection` is
+ * to print and terminate. Installing a handler that only records the error
+ * OVERRIDES that default: the process stays alive, keeps its PostgreSQL pools,
+ * its permission state and its audit writer, and keeps answering queries while
+ * running in a state nobody reasoned about. For a long-lived daemon that holds
+ * database credentials and executes DDL, "keep serving after an unknown fault"
+ * is the wrong answer — the correct answer is to stop, leave a durable trace,
+ * and let the supervisor restart it.
+ *
+ * Everything here is injectable so a test can assert the exit DECISION without
+ * killing the test runner: `exit`, `log`, the flush hooks and the clock are all
+ * parameters, and no module-level `process.exit` call exists in this file.
+ *
+ * ## The non-fatal rejection tag
+ *
+ * `unhandledRejection` is fail-closed by default, because a rejected promise
+ * nobody handled is a bug by definition and this daemon holds credentials. The
+ * single exception has to be explicit and greppable, so the only value that is
+ * allowed to be swallowed is one that a call site deliberately tagged:
+ *
+ * ```ts
+ * markNonFatalRejection(new Error('wake-channel reconnect already in flight'));
+ * ```
+ *
+ * It sets a non-enumerable symbol on the reason object. A `Symbol`, not a
+ * string field: it cannot collide with a database column, an error message or
+ * a JSON body, it does not survive serialisation (so it cannot be replayed by
+ * anything reading the value back), and nothing outside this module can set it
+ * except by calling {@link markNonFatalRejection}. A plain
+ * `{ nonFatal: true }` flag would be forgeable by any rejected object, which
+ * would make the tag no control at all.
+ */
+import * as fs from 'fs';
+/**
+ * Exit code used for a fail-closed fault. `EX_SOFTWARE` from `sysexits.h`: an
+ * internal software error, as opposed to a usage or configuration error. Any
+ * non-zero value satisfies `Restart=on-failure`; a distinct one means a fault
+ * restart is greppable in the journal and separable from an ordinary crash.
+ */
+export const FAULT_EXIT_CODE = 70;
+/**
+ * Upper bound on the best-effort flush before the process exits anyway.
+ *
+ * Short on purpose. The flush exists to get the last audit record onto the disk,
+ * not to complete an orderly shutdown: a daemon that cannot flush in two seconds
+ * is a daemon whose I/O is stuck, and waiting longer only widens the window in
+ * which a half-released pool keeps serving. Well under the five seconds the
+ * regression test allows.
+ */
+export const FAULT_FLUSH_TIMEOUT_MS = 2_000;
+/**
+ * Marker for a rejection a call site has decided is safe to log and continue
+ * from. Non-enumerable, so the tag cannot be discovered by enumeration or
+ * serialisation of the reason.
+ */
+export const NON_FATAL_REJECTION_TAG = Symbol.for('sw-agent.nonFatalRejection');
+/**
+ * Tags a rejection as deliberately non-fatal.
+ *
+ * Only for a rejection that is genuinely a duplicate/benign outcome — a wake
+ * reconnect already in flight, a cancellation racing a completion. NEVER for a
+ * failure to record an audit record, to release a permit, to classify SQL, or to
+ * do anything the product promises not to hide.
+ */
+export function markNonFatalRejection(reason) {
+    if (reason === null || (typeof reason !== 'object' && typeof reason !== 'function')) {
+        return reason;
+    }
+    try {
+        Object.defineProperty(reason, NON_FATAL_REJECTION_TAG, {
+            value: true,
+            enumerable: false,
+            configurable: true,
+            writable: false,
+        });
+    }
+    catch {
+        // A frozen or sealed reason cannot be tagged, so it stays fatal. That is the
+        // safe direction: a caller that cannot record its intent does not get the
+        // benefit of the doubt.
+    }
+    return reason;
+}
+/** True when {@link markNonFatalRejection} was applied to this exact value. */
+export function isNonFatalRejection(reason) {
+    return (reason !== null &&
+        (typeof reason === 'object' || typeof reason === 'function') &&
+        reason[NON_FATAL_REJECTION_TAG] === true);
+}
+function textOf(err) {
+    if (err instanceof Error)
+        return `${err.name}: ${err.message}`;
+    try {
+        return String(err);
+    }
+    catch {
+        return '<unprintable rejection reason>';
+    }
+}
+/** A decision that does nothing, used for the suppressed and non-fatal paths. */
+function inertDecision(overrides = {}) {
+    return {
+        exit_requested: false,
+        exit_code: null,
+        suppressed_by_earlier_fault: false,
+        non_fatal: false,
+        flushed: false,
+        flush_timed_out: false,
+        ...overrides,
+    };
+}
+/**
+ * Builds the controller. One per process; the process handlers hold a reference
+ * to it so they share the latch.
+ */
+export function createFaultShutdownController(deps) {
+    const timeoutMs = deps.flushTimeoutMs ?? FAULT_FLUSH_TIMEOUT_MS;
+    const log = deps.log ?? defaultSyncLog;
+    // Read through a mutable holder so `setHooks` can register the audit and pool
+    // handles that only exist after the process handlers are installed.
+    const flushLocalLog = deps.flushLocalLog;
+    let flushAudit = deps.flushAudit;
+    let closePools = deps.closePools;
+    let firing = false;
+    /** Runs every hook, never exceeding `timeoutMs`, and never rejecting. */
+    const flushEverything = async () => {
+        const work = [];
+        if (flushLocalLog)
+            work.push(flushLocalLog);
+        if (flushAudit)
+            work.push(flushAudit);
+        if (closePools)
+            work.push(closePools);
+        if (work.length === 0)
+            return { flushed: true, timedOut: false };
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), timeoutMs);
+            // Never hold the event loop open for the deadline alone: if the flush
+            // finishes early the timer must not keep a stopped process alive.
+            timer.unref?.();
+        });
+        const ran = (async () => {
+            for (const hook of work) {
+                try {
+                    await hook();
+                }
+                catch (err) {
+                    // A hook that fails is exactly why we are here. Log it and keep going:
+                    // the remaining hooks may still get the audit chain onto the disk.
+                    log(`[fatal] flush step failed during fault shutdown: ${textOf(err)}`);
+                }
+            }
+            return 'done';
+        })();
+        try {
+            const outcome = await Promise.race([ran, deadline]);
+            return { flushed: outcome === 'done', timedOut: outcome === 'timeout' };
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+    return {
+        isFiring: () => firing,
+        setHooks(hooks) {
+            if (firing) {
+                log('[fatal] refusing to register fault-shutdown hooks: a fault is already in flight, so ' +
+                    'the flush set must not change mid-shutdown.');
+                return false;
+            }
+            if (hooks.flushAudit)
+                flushAudit = hooks.flushAudit;
+            if (hooks.closePools)
+                closePools = hooks.closePools;
+            return true;
+        },
+        async handle(kind, err) {
+            const nonFatal = kind === 'unhandledRejection' && isNonFatalRejection(err);
+            if (nonFatal) {
+                // Recorded at `warn`, never at `fatal`: this is the one path that keeps
+                // the process alive, so it must be visibly distinguishable in
+                // errors.jsonl from a fault that stopped the daemon.
+                try {
+                    deps.track(err, { op: kind, level: 'warn' });
+                }
+                catch {
+                    // Never let tracking throw from a process handler.
+                }
+                log(`[warn] unhandledRejection tagged non-fatal (${textOf(err)}); the daemon continues. ` +
+                    'Untagged rejections are fail-closed.');
+                return inertDecision({ non_fatal: true });
+            }
+            if (firing) {
+                log(`[fatal] ${kind} during fault shutdown; already exiting, so this one is recorded only. ` +
+                    `${textOf(err)}`);
+                try {
+                    deps.track(err, { op: kind, level: 'error' });
+                }
+                catch {
+                    // ignore
+                }
+                return inertDecision({ suppressed_by_earlier_fault: true });
+            }
+            firing = true;
+            log(`[fatal] ${kind}: ${textOf(err)}` +
+                '\n[fatal] Flushing the audit sink and releasing the pools, then exiting ' +
+                `${FAULT_EXIT_CODE} so the supervisor can restart a clean process.` +
+                '\n[fatal] The daemon does not continue after an unhandled fault: its pools, its ' +
+                'permission state and its audit writer are all in an undefined state.');
+            try {
+                deps.track(err, { op: kind, level: 'fatal' });
+            }
+            catch {
+                // ignore
+            }
+            const { flushed, timedOut } = await flushEverything();
+            if (timedOut) {
+                log(`[fatal] The fault flush did not complete within ${timeoutMs}ms; exiting anyway. ` +
+                    'The last audit records may be missing — `sw-agent audit verify` will report the ' +
+                    'chain as truncated.');
+            }
+            else {
+                log('[fatal] Fault flush complete; the last audit record is durable.');
+            }
+            // Exit LAST, and unconditionally. Every path above is wrapped, so the only
+            // way to reach here is with the decision made; nothing after this line can
+            // prevent the exit, which is the property that makes the handler
+            // fail-closed rather than fail-open.
+            try {
+                deps.exit(FAULT_EXIT_CODE);
+            }
+            catch {
+                // An injected `exit` that throws must not re-enter the handler.
+            }
+            return {
+                exit_requested: true,
+                exit_code: FAULT_EXIT_CODE,
+                suppressed_by_earlier_fault: false,
+                non_fatal: false,
+                flushed,
+                flush_timed_out: timedOut,
+            };
+        },
+    };
+}
+/**
+ * Writes to fd 2 synchronously.
+ *
+ * `process.stderr.write` is asynchronous when stderr is a pipe or a file, so a
+ * message written with it can be lost to `process.exit` immediately afterwards —
+ * and a systemd unit pipes stderr to the journal. `fs.writeSync` cannot be
+ * reordered against the exit, which matters because this is the last thing the
+ * daemon says before it dies.
+ */
+function defaultSyncLog(line) {
+    try {
+        fs.writeSync(2, `${line}\n`);
+    }
+    catch {
+        try {
+            fs.writeSync(1, `${line}\n`);
+        }
+        catch {
+            // Nothing left to try; the exit still happens.
+        }
+    }
+}
+//# sourceMappingURL=fault-shutdown.js.map

package/dist/esm/cli/daemon/fault-shutdown.js.map

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

package/dist/esm/cli/daemon/index.d.ts

@@ -0,0 +1,12 @@
+export { readPidFile, writePidFile, deletePidFile, isProcessAlive } from './pid-file';
+export type { PidFile, PidFileOptions } from './pid-file';
+export { readStatusFile, writeStatusFile, isStatusStale } from './status-file';
+export type { DaemonStatus, StatusFileOptions } from './status-file';
+export { resolveAgentRuntimeState, formatDuration, formatTimestamp } from './state';
+export type { AgentRuntimeKind, AgentRuntimeState } from './state';
+export { createShutdownCoordinator } from './shutdown';
+export type { ShutdownCoordinator } from './shutdown';
+export { installSignalHandlers } from './signal-handlers';
+export { runAgent } from './runtime';
+export type { RuntimeOptions } from './runtime';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/cli/daemon/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACtF,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC/E,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,wBAAwB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/esm/cli/daemon/index.js

@@ -0,0 +1,7 @@
+export { readPidFile, writePidFile, deletePidFile, isProcessAlive } from './pid-file';
+export { readStatusFile, writeStatusFile, isStatusStale } from './status-file';
+export { resolveAgentRuntimeState, formatDuration, formatTimestamp } from './state';
+export { createShutdownCoordinator } from './shutdown';
+export { installSignalHandlers } from './signal-handlers';
+export { runAgent } from './runtime';
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/daemon/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cli/daemon/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGtF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG/E,OAAO,EAAE,wBAAwB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGpF,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAGvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}

package/dist/esm/cli/daemon/pid-file.d.ts

@@ -0,0 +1,13 @@
+export interface PidFile {
+    pid: number;
+    started_at: string;
+    version: string;
+}
+export interface PidFileOptions {
+    path: string;
+}
+export declare function writePidFile(opts: PidFileOptions, info: PidFile): Promise<void>;
+export declare function readPidFile(opts: PidFileOptions): Promise<PidFile | null>;
+export declare function deletePidFile(opts: PidFileOptions): Promise<void>;
+export declare function isProcessAlive(pid: number): boolean;
+//# sourceMappingURL=pid-file.d.ts.map

package/dist/esm/cli/daemon/pid-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid-file.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/pid-file.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAarF;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAW/E;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CASvE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUnD"}

package/dist/esm/cli/daemon/pid-file.js

@@ -0,0 +1,51 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export async function writePidFile(opts, info) {
+    const dir = path.dirname(opts.path);
+    await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+    const existing = await readPidFile(opts);
+    if (existing && isProcessAlive(existing.pid)) {
+        throw new Error(`Agent already running (pid ${existing.pid})`);
+    }
+    await fs.promises.writeFile(opts.path, JSON.stringify(info, null, 2), {
+        mode: 0o600,
+        encoding: 'utf8',
+    });
+}
+export async function readPidFile(opts) {
+    try {
+        const content = await fs.promises.readFile(opts.path, 'utf8');
+        return JSON.parse(content);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
+}
+export async function deletePidFile(opts) {
+    try {
+        await fs.promises.unlink(opts.path);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT') {
+            throw err;
+        }
+    }
+}
+export function isProcessAlive(pid) {
+    if (pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=pid-file.js.map

package/dist/esm/cli/daemon/pid-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid-file.js","sourceRoot":"","sources":["../../../../src/cli/daemon/pid-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAY7B,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAoB,EAAE,IAAa;IACpE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAE/D,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,QAAQ,IAAI,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,CAAC,GAAG,GAAG,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;QACpE,IAAI,EAAE,KAAK;QACX,QAAQ,EAAE,MAAM;KACjB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAoB;IACpD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAY,CAAC;IACxC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAoB;IACtD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/esm/cli/daemon/readiness.d.ts

@@ -0,0 +1,30 @@
+export interface ReadinessOptions {
+    /** Max time to wait in ms. Default 8000. */
+    timeoutMs?: number;
+    /** Poll interval in ms. Default 250. */
+    intervalMs?: number;
+}
+export interface ReadinessResult {
+    ready: boolean;
+    pid: number | null;
+    /** Time spent waiting in ms. */
+    waitedMs: number;
+    /** Why we stopped polling. */
+    reason: 'ready' | 'timeout' | 'process_dead' | 'no_pid';
+}
+/**
+ * Poll until the daemon has written a fresh PID file AND a non-stale status
+ * file with a live process. Fixes the start → status race where status was
+ * queried before the detached daemon had a chance to write its files.
+ */
+export declare function waitForAgentReady(pidFile: string, statusFile: string, opts?: ReadinessOptions): Promise<ReadinessResult>;
+/**
+ * Poll until the daemon process is gone AND its PID file is cleaned up.
+ * Fixes the symmetric race on stop, so an immediately-following status
+ * check never reports a half-shutdown agent.
+ */
+export declare function waitForAgentGone(pidFile: string, opts?: ReadinessOptions): Promise<{
+    gone: boolean;
+    waitedMs: number;
+}>;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/esm/cli/daemon/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/readiness.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,cAAc,GAAG,QAAQ,CAAC;CACzD;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA0C1B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqB9C"}

package/dist/esm/cli/daemon/readiness.js

@@ -0,0 +1,70 @@
+import { readPidFile, isProcessAlive } from './pid-file';
+import { readStatusFile, isStatusStale } from './status-file';
+/**
+ * Poll until the daemon has written a fresh PID file AND a non-stale status
+ * file with a live process. Fixes the start → status race where status was
+ * queried before the detached daemon had a chance to write its files.
+ */
+export async function waitForAgentReady(pidFile, statusFile, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 8_000;
+    const intervalMs = opts.intervalMs ?? 250;
+    const start = Date.now();
+    for (;;) {
+        const pidInfo = await readPidFile({ path: pidFile });
+        if (pidInfo) {
+            const alive = isProcessAlive(pidInfo.pid);
+            if (!alive) {
+                // PID file exists but process is gone — it crashed during startup.
+                return {
+                    ready: false,
+                    pid: pidInfo.pid,
+                    waitedMs: Date.now() - start,
+                    reason: 'process_dead',
+                };
+            }
+            const status = await readStatusFile({ path: statusFile });
+            if (status && status.pid === pidInfo.pid && !isStatusStale(status)) {
+                return {
+                    ready: true,
+                    pid: pidInfo.pid,
+                    waitedMs: Date.now() - start,
+                    reason: 'ready',
+                };
+            }
+        }
+        if (Date.now() - start >= timeoutMs) {
+            return {
+                ready: false,
+                pid: pidInfo?.pid ?? null,
+                waitedMs: Date.now() - start,
+                reason: pidInfo ? 'timeout' : 'no_pid',
+            };
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}
+/**
+ * Poll until the daemon process is gone AND its PID file is cleaned up.
+ * Fixes the symmetric race on stop, so an immediately-following status
+ * check never reports a half-shutdown agent.
+ */
+export async function waitForAgentGone(pidFile, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    const intervalMs = opts.intervalMs ?? 250;
+    const start = Date.now();
+    const pidInfo = await readPidFile({ path: pidFile });
+    const pid = pidInfo?.pid ?? null;
+    if (pid === null) {
+        return { gone: true, waitedMs: 0 };
+    }
+    for (;;) {
+        if (!isProcessAlive(pid)) {
+            return { gone: true, waitedMs: Date.now() - start };
+        }
+        if (Date.now() - start >= timeoutMs) {
+            return { gone: false, waitedMs: Date.now() - start };
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}
+//# sourceMappingURL=readiness.js.map

package/dist/esm/cli/daemon/readiness.js.map

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