@pleri/olam-cli 0.1.144 → 0.1.146

package/dist/lib/instrumentation.d.ts

@@ -0,0 +1,85 @@
+/**
+ * instrumentation.ts — stdout JSON event emitter for olam-cli.
+ *
+ * Phase 1b A3 of olam-host-suite-phase-1b-k3s-beta-flavour (plan
+ * ~/.claude/plans/olam-host-suite-phase-1b-k3s-beta-flavour.md).
+ *
+ * Canonical event schema (Decision 21 — `olam.instr.v1`):
+ *   {
+ *     "schema": "olam.instr.v1",
+ *     "event": "substrate.set" | "upgrade.complete",
+ *     "install_id": "<uuid-v4-from-config>",
+ *     "ts": "<ISO-8601-UTC>",
+ *     <event-specific-fields>
+ *   }
+ *
+ * Emission target: **stderr**, newline-delimited, each line prefixed with
+ * `OLAM_INSTR ` so consumers can grep-distinguish from other stderr output.
+ *
+ * Why stderr (and not stdout)? olam-cli's existing stdout-JSON contracts
+ * (e.g. `olam status --json`, `olam doctor --json`) reserve stdout for
+ * command output that consumers parse positionally. Mixing instrumentation
+ * into stdout breaks those contracts. stderr keeps the emitter
+ * grep-distinguishable AND segregated from the data-plane output.
+ *
+ * Consumers: month-6 aggregator script (`scripts/aggregate-substrate-events.mjs`,
+ * D20) groups events by `install_id` for Falsifiable signal thresholds 1+4.
+ *
+ * Defensive contract:
+ *   - emit() MUST NOT throw if the config can't be read; falls back to a
+ *     placeholder install_id ('unknown') + emits a one-line stderr WARN.
+ *   - Schema is versioned (`olam.instr.v1`); v2 fields land additively.
+ *     Consumers MUST tolerate unknown fields.
+ */
+export declare const INSTRUMENTATION_SCHEMA: "olam.instr.v1";
+export declare const INSTRUMENTATION_PREFIX: "OLAM_INSTR ";
+export type SubstrateSetEvent = {
+    schema: typeof INSTRUMENTATION_SCHEMA;
+    event: 'substrate.set';
+    install_id: string;
+    ts: string;
+    substrate: 'compose' | 'kubernetes';
+    flavor?: string;
+};
+export type UpgradeCompleteEvent = {
+    schema: typeof INSTRUMENTATION_SCHEMA;
+    event: 'upgrade.complete';
+    install_id: string;
+    ts: string;
+    substrate: 'compose' | 'kubernetes';
+    duration_ms: number;
+    flavor?: string;
+};
+export type InstrumentationEvent = SubstrateSetEvent | UpgradeCompleteEvent;
+export type EmitOpts = {
+    /** Inject a stderr-like sink for tests; defaults to process.stderr. */
+    stderr?: NodeJS.WritableStream;
+    /** Inject a clock for tests; defaults to Date.now(). */
+    now?: () => Date;
+    /** Inject a config-reader for tests; defaults to readConfig(). */
+    installIdProvider?: () => string;
+};
+/**
+ * Emit a `substrate.set` event. Called by `olam substrate set` ONLY on success
+ * (failure paths emit nothing — by design; thresholds count successful switches).
+ *
+ * @param payload — substrate + optional flavor
+ * @param opts — test-only injection points (stderr / now / installIdProvider)
+ */
+export declare function emitSubstrateSet(payload: {
+    substrate: 'compose' | 'kubernetes';
+    flavor?: string;
+}, opts?: EmitOpts): void;
+/**
+ * Emit an `upgrade.complete` event. Called by Phase C C2's substrate-aware
+ * `olam upgrade` ONLY on success.
+ *
+ * @param payload — substrate + duration_ms (and optional flavor)
+ * @param opts — test-only injection points
+ */
+export declare function emitUpgradeComplete(payload: {
+    substrate: 'compose' | 'kubernetes';
+    duration_ms: number;
+    flavor?: string;
+}, opts?: EmitOpts): void;
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/lib/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/lib/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,eAAO,MAAM,sBAAsB,EAAG,eAAwB,CAAC;AAC/D,eAAO,MAAM,sBAAsB,EAAG,aAAsB,CAAC;AAE7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,KAAK,EAAE,eAAe,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,GAAG,YAAY,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,GAAG,YAAY,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AAE5E,MAAM,MAAM,QAAQ,GAAG;IACrB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC;CAClC,CAAC;AAmCF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE;IAAE,SAAS,EAAE,SAAS,GAAG,YAAY,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EACjE,IAAI,GAAE,QAAa,GAClB,IAAI,CAUN;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IACP,SAAS,EAAE,SAAS,GAAG,YAAY,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,EACD,IAAI,GAAE,QAAa,GAClB,IAAI,CAWN"}

package/dist/lib/instrumentation.js

@@ -0,0 +1,104 @@
+/**
+ * instrumentation.ts — stdout JSON event emitter for olam-cli.
+ *
+ * Phase 1b A3 of olam-host-suite-phase-1b-k3s-beta-flavour (plan
+ * ~/.claude/plans/olam-host-suite-phase-1b-k3s-beta-flavour.md).
+ *
+ * Canonical event schema (Decision 21 — `olam.instr.v1`):
+ *   {
+ *     "schema": "olam.instr.v1",
+ *     "event": "substrate.set" | "upgrade.complete",
+ *     "install_id": "<uuid-v4-from-config>",
+ *     "ts": "<ISO-8601-UTC>",
+ *     <event-specific-fields>
+ *   }
+ *
+ * Emission target: **stderr**, newline-delimited, each line prefixed with
+ * `OLAM_INSTR ` so consumers can grep-distinguish from other stderr output.
+ *
+ * Why stderr (and not stdout)? olam-cli's existing stdout-JSON contracts
+ * (e.g. `olam status --json`, `olam doctor --json`) reserve stdout for
+ * command output that consumers parse positionally. Mixing instrumentation
+ * into stdout breaks those contracts. stderr keeps the emitter
+ * grep-distinguishable AND segregated from the data-plane output.
+ *
+ * Consumers: month-6 aggregator script (`scripts/aggregate-substrate-events.mjs`,
+ * D20) groups events by `install_id` for Falsifiable signal thresholds 1+4.
+ *
+ * Defensive contract:
+ *   - emit() MUST NOT throw if the config can't be read; falls back to a
+ *     placeholder install_id ('unknown') + emits a one-line stderr WARN.
+ *   - Schema is versioned (`olam.instr.v1`); v2 fields land additively.
+ *     Consumers MUST tolerate unknown fields.
+ */
+import { readConfig } from './config.js';
+export const INSTRUMENTATION_SCHEMA = 'olam.instr.v1';
+export const INSTRUMENTATION_PREFIX = 'OLAM_INSTR ';
+function nowIso(now) {
+    const d = now ? now() : new Date();
+    return d.toISOString();
+}
+function resolveInstallId(opts) {
+    try {
+        if (opts.installIdProvider)
+            return opts.installIdProvider();
+        const cfg = readConfig();
+        return cfg.install_id;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function writeLine(stderr, payload) {
+    try {
+        const line = `${INSTRUMENTATION_PREFIX}${JSON.stringify(payload)}\n`;
+        stderr.write(line);
+    }
+    catch (err) {
+        // emit must never throw; surface the failure tersely to stderr.
+        try {
+            stderr.write(`[WARN] olam instrumentation emit failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        catch {
+            // give up; emitter contract is best-effort.
+        }
+    }
+}
+/**
+ * Emit a `substrate.set` event. Called by `olam substrate set` ONLY on success
+ * (failure paths emit nothing — by design; thresholds count successful switches).
+ *
+ * @param payload — substrate + optional flavor
+ * @param opts — test-only injection points (stderr / now / installIdProvider)
+ */
+export function emitSubstrateSet(payload, opts = {}) {
+    const event = {
+        schema: INSTRUMENTATION_SCHEMA,
+        event: 'substrate.set',
+        install_id: resolveInstallId(opts),
+        ts: nowIso(opts.now),
+        substrate: payload.substrate,
+        ...(payload.flavor !== undefined ? { flavor: payload.flavor } : {}),
+    };
+    writeLine(opts.stderr ?? process.stderr, event);
+}
+/**
+ * Emit an `upgrade.complete` event. Called by Phase C C2's substrate-aware
+ * `olam upgrade` ONLY on success.
+ *
+ * @param payload — substrate + duration_ms (and optional flavor)
+ * @param opts — test-only injection points
+ */
+export function emitUpgradeComplete(payload, opts = {}) {
+    const event = {
+        schema: INSTRUMENTATION_SCHEMA,
+        event: 'upgrade.complete',
+        install_id: resolveInstallId(opts),
+        ts: nowIso(opts.now),
+        substrate: payload.substrate,
+        duration_ms: payload.duration_ms,
+        ...(payload.flavor !== undefined ? { flavor: payload.flavor } : {}),
+    };
+    writeLine(opts.stderr ?? process.stderr, event);
+}
+//# sourceMappingURL=instrumentation.js.map

package/dist/lib/instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../../src/lib/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,CAAC,MAAM,sBAAsB,GAAG,eAAwB,CAAC;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAsB,CAAC;AAgC7D,SAAS,MAAM,CAAC,GAAgB;IAC9B,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IACnC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;AACzB,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAc;IACtC,IAAI,CAAC;QACH,IAAI,IAAI,CAAC,iBAAiB;YAAE,OAAO,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC5D,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC,UAAU,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,MAA6B,EAAE,OAA6B;IAC7E,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,GAAG,sBAAsB,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;QACrE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gEAAgE;QAChE,IAAI,CAAC;YACH,MAAM,CAAC,KAAK,CACV,4CACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,IAAI,CACL,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAiE,EACjE,OAAiB,EAAE;IAEnB,MAAM,KAAK,GAAsB;QAC/B,MAAM,EAAE,sBAAsB;QAC9B,KAAK,EAAE,eAAe;QACtB,UAAU,EAAE,gBAAgB,CAAC,IAAI,CAAC;QAClC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QACpB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;IACF,SAAS,CAAC,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAIC,EACD,OAAiB,EAAE;IAEnB,MAAM,KAAK,GAAyB;QAClC,MAAM,EAAE,sBAAsB;QAC9B,KAAK,EAAE,kBAAkB;QACzB,UAAU,EAAE,gBAAgB,CAAC,IAAI,CAAC;QAClC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QACpB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;IACF,SAAS,CAAC,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC"}

package/dist/lib/kubectl-wrap.d.ts

@@ -0,0 +1,59 @@
+/**
+ * kubectl-wrap.ts — subprocess timeout wrapper for kubectl invocations.
+ *
+ * Phase 1b C1 of olam-host-suite-phase-1b-k3s-beta-flavour (plan
+ * ~/.claude/plans/olam-host-suite-phase-1b-k3s-beta-flavour.md).
+ *
+ * ALL kubectl invocations in olam-cli MUST go through `kubectlWrap`.
+ * Direct `child_process.spawn('kubectl', ...)` calls outside this module
+ * break the timeout guarantee and fail `audit:kubectl-callers` (Seam C1).
+ *
+ * Timeout lifecycle:
+ *   1. Spawn kubectl with the provided args.
+ *   2. Start wall-clock timer (default 120 000 ms; per-call configurable).
+ *   3. On timer fire: SIGTERM the process; wait 5 000 ms; SIGKILL if still alive.
+ *   4. Returns { ok: false, reason: 'timeout', … } immediately after the kill
+ *      sequence completes (does not wait further for exit after SIGKILL).
+ *
+ * Returns:
+ *   { ok: true,  stdout, stderr, exitCode }       — clean exit 0
+ *   { ok: false, stdout, stderr, exitCode, reason } — non-zero exit or timeout
+ *
+ * reason values:
+ *   'timeout'  — wall-clock limit exceeded; process SIGKILLed
+ *   'spawn'    — spawn itself failed (e.g. kubectl not on PATH)
+ *   'nonzero'  — kubectl exited with non-zero status
+ */
+import { spawn } from 'node:child_process';
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+export type KubectlResult = {
+    ok: true;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+} | {
+    ok: false;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    reason: 'timeout' | 'spawn' | 'nonzero';
+};
+export interface KubectlWrapOpts {
+    /** Per-call timeout override (ms). Defaults to DEFAULT_TIMEOUT_MS (120 s). */
+    readonly timeout?: number;
+    /** Additional environment variables to merge into the subprocess env. */
+    readonly env?: Record<string, string>;
+    /**
+     * spawn factory — injectable for tests so unit tests never fork a real kubectl.
+     * Signature matches `child_process.spawn` return type.
+     */
+    readonly spawnImpl?: typeof spawn;
+}
+/**
+ * Invoke kubectl with a timeout.
+ *
+ * @param args - kubectl arguments (e.g. ['get', 'pods', '-n', 'olam'])
+ * @param opts - timeout, env overrides, and spawn factory for injection
+ */
+export declare function kubectlWrap(args: readonly string[], opts?: KubectlWrapOpts): Promise<KubectlResult>;
+//# sourceMappingURL=kubectl-wrap.d.ts.map

package/dist/lib/kubectl-wrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kubectl-wrap.d.ts","sourceRoot":"","sources":["../../src/lib/kubectl-wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAG1C,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;CAAE,CAAC;AAE7G,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,aAAa,CAAC,CAuFxB"}

package/dist/lib/kubectl-wrap.js

@@ -0,0 +1,130 @@
+/**
+ * kubectl-wrap.ts — subprocess timeout wrapper for kubectl invocations.
+ *
+ * Phase 1b C1 of olam-host-suite-phase-1b-k3s-beta-flavour (plan
+ * ~/.claude/plans/olam-host-suite-phase-1b-k3s-beta-flavour.md).
+ *
+ * ALL kubectl invocations in olam-cli MUST go through `kubectlWrap`.
+ * Direct `child_process.spawn('kubectl', ...)` calls outside this module
+ * break the timeout guarantee and fail `audit:kubectl-callers` (Seam C1).
+ *
+ * Timeout lifecycle:
+ *   1. Spawn kubectl with the provided args.
+ *   2. Start wall-clock timer (default 120 000 ms; per-call configurable).
+ *   3. On timer fire: SIGTERM the process; wait 5 000 ms; SIGKILL if still alive.
+ *   4. Returns { ok: false, reason: 'timeout', … } immediately after the kill
+ *      sequence completes (does not wait further for exit after SIGKILL).
+ *
+ * Returns:
+ *   { ok: true,  stdout, stderr, exitCode }       — clean exit 0
+ *   { ok: false, stdout, stderr, exitCode, reason } — non-zero exit or timeout
+ *
+ * reason values:
+ *   'timeout'  — wall-clock limit exceeded; process SIGKILLed
+ *   'spawn'    — spawn itself failed (e.g. kubectl not on PATH)
+ *   'nonzero'  — kubectl exited with non-zero status
+ */
+import { spawn } from 'node:child_process';
+export const DEFAULT_TIMEOUT_MS = 120_000;
+const SIGKILL_GRACE_MS = 5_000;
+/**
+ * Invoke kubectl with a timeout.
+ *
+ * @param args - kubectl arguments (e.g. ['get', 'pods', '-n', 'olam'])
+ * @param opts - timeout, env overrides, and spawn factory for injection
+ */
+export async function kubectlWrap(args, opts = {}) {
+    const timeoutMs = opts.timeout ?? DEFAULT_TIMEOUT_MS;
+    const spawnImpl = opts.spawnImpl ?? spawn;
+    const stdout = [];
+    const stderr = [];
+    return new Promise((resolve) => {
+        let resolved = false;
+        let killTimer = null;
+        let sigkillTimer = null;
+        function safeResolve(r) {
+            if (resolved)
+                return;
+            resolved = true;
+            if (killTimer !== null) {
+                clearTimeout(killTimer);
+                killTimer = null;
+            }
+            if (sigkillTimer !== null) {
+                clearTimeout(sigkillTimer);
+                sigkillTimer = null;
+            }
+            resolve(r);
+        }
+        let child;
+        try {
+            child = spawnImpl('kubectl', [...args], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: { ...process.env, ...(opts.env ?? {}) },
+            });
+        }
+        catch (err) {
+            resolve({
+                ok: false,
+                stdout: '',
+                stderr: err instanceof Error ? err.message : String(err),
+                exitCode: -1,
+                reason: 'spawn',
+            });
+            return;
+        }
+        if (child.stdout) {
+            child.stdout.on('data', (chunk) => { stdout.push(chunk.toString('utf8')); });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (chunk) => { stderr.push(chunk.toString('utf8')); });
+        }
+        child.on('error', (err) => {
+            safeResolve({
+                ok: false,
+                stdout: stdout.join(''),
+                stderr: err.message,
+                exitCode: -1,
+                reason: 'spawn',
+            });
+        });
+        child.on('exit', (code) => {
+            const exitCode = code ?? -1;
+            const stdoutStr = stdout.join('');
+            const stderrStr = stderr.join('');
+            if (exitCode === 0) {
+                safeResolve({ ok: true, stdout: stdoutStr, stderr: stderrStr, exitCode });
+            }
+            else {
+                safeResolve({ ok: false, stdout: stdoutStr, stderr: stderrStr, exitCode, reason: 'nonzero' });
+            }
+        });
+        // Wall-clock timeout: SIGTERM then SIGKILL after grace period.
+        killTimer = setTimeout(() => {
+            killTimer = null;
+            // SIGTERM — polite shutdown request.
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* already exited */ }
+            // SIGKILL after 5 s grace — hard kill if SIGTERM wasn't enough.
+            sigkillTimer = setTimeout(() => {
+                sigkillTimer = null;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* already exited */ }
+                // Resolve immediately after SIGKILL without waiting for the 'exit' event.
+                // The 'exit' event may fire after this resolve; safeResolve is idempotent.
+                safeResolve({
+                    ok: false,
+                    stdout: stdout.join(''),
+                    stderr: stderr.join(''),
+                    exitCode: -1,
+                    reason: 'timeout',
+                });
+            }, SIGKILL_GRACE_MS);
+        }, timeoutMs);
+    });
+}
+//# sourceMappingURL=kubectl-wrap.js.map

package/dist/lib/kubectl-wrap.js.map

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

package/dist/lib/manifest-refresh.d.ts

@@ -0,0 +1,95 @@
+/**
+ * manifest-refresh.ts — D14 --force-refresh-manifests flag implementation.
+ *
+ * Phase 1b C2 of olam-host-suite-phase-1b-k3s-beta-flavour (plan
+ * ~/.claude/plans/olam-host-suite-phase-1b-k3s-beta-flavour.md).
+ *
+ * Decisions consumed:
+ *   D14 — --force-refresh-manifests flag (NOT a subcommand); requires
+ *          --accept-security-regression when security-sensitive fields differ.
+ *
+ * Security-sensitive manifest fields (refuse without --accept-security-regression):
+ *   - securityContext (pod or container level)
+ *   - resources.limits
+ *   - capabilities (add/drop lists)
+ *   - readOnlyRootFilesystem
+ *   - RBAC Role rules (rules[].verbs / resources / apiGroups)
+ *
+ * Audit log:
+ *   ~/.olam/state/manifest-refresh-audit.jsonl (mode 0600; append-only)
+ *   ENOSPC aborts the refresh with "audit log unavailable: <error>".
+ *   The file is created on first write; mode set via writeFileSync options.
+ *
+ * Two functions are exported:
+ *   diffManifestSecurityFields — pure diff, no I/O; testable.
+ *   runManifestRefresh         — performs the full refresh with audit-log.
+ */
+import * as fs from 'node:fs';
+export declare const MANIFEST_REFRESH_AUDIT_LOG: string;
+/** Security-sensitive field paths checked by the diff. */
+export declare const SECURITY_SENSITIVE_FIELDS: readonly ["securityContext", "resources.limits", "capabilities", "readOnlyRootFilesystem", "rules"];
+export type SecuritySensitiveField = (typeof SECURITY_SENSITIVE_FIELDS)[number];
+export interface ManifestDiffResult {
+    /** True when any security-sensitive field value differs between old and new. */
+    hasSecurityRegression: boolean;
+    /** List of field keys that changed. */
+    changedFields: SecuritySensitiveField[];
+}
+export interface ManifestRefreshAuditEntry {
+    ts: string;
+    manifests_path: string;
+    security_regression: boolean;
+    changed_fields: string[];
+    accepted: boolean;
+    operator_pid: number;
+}
+export interface ManifestRefreshDeps {
+    /** Override state dir for tests. */
+    readonly stateDir?: string;
+    /** Override manifests dir for tests. */
+    readonly manifestsDir?: string;
+    /** Override audit log path for tests. */
+    readonly auditLogPath?: string;
+    /** Override fs.readdirSync for tests. */
+    readonly readdirSync?: typeof fs.readdirSync;
+    /** Override fs.readFileSync for tests. */
+    readonly readFileSync?: typeof fs.readFileSync;
+    /** Override fs.writeFileSync for tests. */
+    readonly writeFileSync?: typeof fs.writeFileSync;
+    /** Override fs.existsSync for tests. */
+    readonly existsSync?: typeof fs.existsSync;
+    /** Override Date.now for tests. */
+    readonly now?: () => Date;
+}
+/**
+ * Pure diff between two YAML manifest file contents (as strings).
+ * Parses each as JSON (manifests may be JSON or YAML; we handle JSON
+ * and treat parse failures as "content changed" = regression to be safe).
+ *
+ * Used by runManifestRefresh and directly by tests.
+ */
+export declare function diffManifestSecurityFields(oldContent: string, newContent: string): ManifestDiffResult;
+export type ManifestRefreshResult = {
+    ok: true;
+    message: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Run the manifest refresh check.
+ *
+ * @param manifestsDir    — path to ~/.olam/k8s/manifests/
+ * @param acceptRegression — true when --accept-security-regression is set
+ * @param deps            — injectable for tests
+ *
+ * Returns ok=false when:
+ *   - Security-sensitive fields differ AND !acceptRegression.
+ *   - Audit log write fails (ENOSPC).
+ *
+ * On ok=true the audit log entry is written with accepted=true (or
+ * accepted=false when no regression was detected — regression-free
+ * refreshes are still audited).
+ */
+export declare function runManifestRefresh(manifestsDir: string, acceptRegression: boolean, deps?: ManifestRefreshDeps): Promise<ManifestRefreshResult>;
+//# sourceMappingURL=manifest-refresh.d.ts.map

package/dist/lib/manifest-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-refresh.d.ts","sourceRoot":"","sources":["../../src/lib/manifest-refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAI9B,eAAO,MAAM,0BAA0B,QAA4D,CAAC;AAEpG,0DAA0D;AAC1D,eAAO,MAAM,yBAAyB,qGAM5B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhF,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,qBAAqB,EAAE,OAAO,CAAC;IAC/B,uCAAuC;IACvC,aAAa,EAAE,sBAAsB,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC,WAAW,CAAC;IAC7C,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,YAAY,CAAC;IAC/C,2CAA2C;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC,aAAa,CAAC;IACjD,wCAAwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,UAAU,CAAC;IAC3C,mCAAmC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAkCD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,kBAAkB,CA4BpB;AAyBD,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,OAAO,EACzB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAqFhC"}