@cat-factory/local-server 0.15.0 → 0.17.0

package/dist/LocalProcessRunnerTransport.d.ts

@@ -0,0 +1,63 @@
+import { spawn } from 'node:child_process';
+import type { RunnerDispatchKind, RunnerJobRef, RunnerJobView, RunnerTransport } from '@cat-factory/kernel';
+export interface LocalProcessRunnerTransportOptions {
+    /**
+     * Path to the executor-harness HTTP server entry (its `server.js`/`server.ts`). Spawned
+     * as `node <entry>`; with a `.ts` entry, Node's type-stripping (Node 24+) runs it.
+     */
+    harnessEntry: string;
+    /** Node executable to spawn the harness with. Default `process.execPath`. */
+    nodePath?: string;
+    /** Extra args to pass to node before the entry (e.g. `--experimental-strip-types`). */
+    nodeArgs?: string[];
+    /** Shared secret injected as `HARNESS_SHARED_SECRET` + sent on every call. Default random. */
+    sharedSecret?: string;
+    /** Extra env for the harness process (e.g. GITHUB_ALLOWED_HOSTS). */
+    env?: Record<string, string>;
+    /** Injectable fetch — defaults to the global. */
+    fetchImpl?: typeof fetch;
+    /** Injectable spawn — defaults to node:child_process.spawn (overridable in tests). */
+    spawnImpl?: typeof spawn;
+    /** Injectable free-port picker — defaults to an ephemeral OS port (overridable in tests). */
+    pickPort?: () => Promise<number>;
+    /** How long to wait for the harness `/health` after spawn. Default 30s. */
+    readyTimeoutMs?: number;
+    /** Per-HTTP-call timeout. Default 30s. */
+    requestTimeoutMs?: number;
+}
+export declare class LocalProcessRunnerTransport implements RunnerTransport {
+    private readonly harnessEntry;
+    private readonly nodePath;
+    private readonly nodeArgs;
+    private readonly sharedSecret;
+    private readonly extraEnv;
+    private readonly fetchImpl;
+    private readonly spawnImpl;
+    private readonly pickPort;
+    private readonly readyTimeoutMs;
+    private readonly requestTimeoutMs;
+    /** The single long-lived harness process, started lazily and reused across all runs. */
+    private proc;
+    private starting;
+    constructor(options: LocalProcessRunnerTransportOptions);
+    dispatch(ref: RunnerJobRef, spec: Record<string, unknown>, kind?: RunnerDispatchKind): Promise<void>;
+    poll(ref: RunnerJobRef): Promise<RunnerJobView>;
+    /**
+     * No per-run teardown: the harness host process is long-lived and reused across runs
+     * (the harness already removes each job's ephemeral workspace itself). Provided so the
+     * port contract is satisfied; kept idempotent.
+     */
+    release(): Promise<void>;
+    /** Stop the harness process (for shutdown / tests). Idempotent. */
+    shutdown(): Promise<void>;
+    private ensureProcess;
+    private startProcess;
+    private waitForHealth;
+}
+/**
+ * Build a {@link LocalProcessRunnerTransport} from the environment. Requires
+ * `LOCAL_HARNESS_ENTRY` (the path to the executor-harness server entry to run as a host
+ * process). The native CLIs (`claude` / `codex`) must already be installed on the host.
+ */
+export declare function createLocalProcessTransportFromEnv(env: NodeJS.ProcessEnv): LocalProcessRunnerTransport;
+//# sourceMappingURL=LocalProcessRunnerTransport.d.ts.map

package/dist/LocalProcessRunnerTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalProcessRunnerTransport.d.ts","sourceRoot":"","sources":["../src/LocalProcessRunnerTransport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAG7D,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,eAAe,EAChB,MAAM,qBAAqB,CAAA;AA0B5B,MAAM,WAAW,kCAAkC;IACjD;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IAChC,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAeD,qBAAa,2BAA4B,YAAW,eAAe;IACjE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IAEzC,wFAAwF;IACxF,OAAO,CAAC,IAAI,CAAoE;IAChF,OAAO,CAAC,QAAQ,CAA6E;IAE7F,YAAY,OAAO,EAAE,kCAAkC,EAWtD;IAEK,QAAQ,CACZ,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,GAAE,kBAA4B,GACjC,OAAO,CAAC,IAAI,CAAC,CAYf;IAEK,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAapD;IAED;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7B;IAED,mEAAmE;IAC7D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAK9B;YAIa,aAAa;YAWb,YAAY;IAoC1B,OAAO,CAAC,aAAa;CAYtB;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,2BAA2B,CAmB7B"}

package/dist/LocalProcessRunnerTransport.js

@@ -0,0 +1,188 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:net';
+import { EVICTION_ERROR, pollHarnessJob, postHarnessJob, waitForHarnessHealth, } from './harnessHttp.js';
+// The NATIVE local runner backend (opt-in via `LOCAL_NATIVE_AGENTS`): instead of a Docker
+// container per run, it runs the SAME executor-harness as a long-lived HOST PROCESS on
+// 127.0.0.1 and drives it through the harness's existing HTTP API. So all the harness
+// machinery — git clone/push/PR, structured-output, watchdogs, the JobRegistry, progress —
+// is reused unchanged; the only difference from the container transport is WHERE the harness
+// runs (a host `node` process vs a container) and that the agent uses the developer's OWN
+// installed `claude` / `codex` CLI with its ambient login (the executor sets `ambientAuth`
+// on the job, so no credential is leased). This bypasses Docker entirely.
+//
+// SECURITY: the agent runs as a plain host subprocess with the developer's full shell/file
+// access and their personal subscription — no container sandbox, no spend metering, no
+// model-locking. Acceptable ONLY because local mode is the developer's own machine; it is
+// therefore opt-in (default off) and reachable only from `buildLocalContainer`.
+/** The harness is always on loopback for the native host-process transport. */
+const endpointFor = (port) => ({ host: '127.0.0.1', port });
+/** An ephemeral free localhost port (best-effort; a tiny TOCTOU window is fine for dev). */
+function ephemeralPort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.on('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            srv.close(() => (port ? resolve(port) : reject(new Error('could not pick a free port'))));
+        });
+    });
+}
+export class LocalProcessRunnerTransport {
+    harnessEntry;
+    nodePath;
+    nodeArgs;
+    sharedSecret;
+    extraEnv;
+    fetchImpl;
+    spawnImpl;
+    pickPort;
+    readyTimeoutMs;
+    requestTimeoutMs;
+    /** The single long-lived harness process, started lazily and reused across all runs. */
+    proc;
+    starting;
+    constructor(options) {
+        this.harnessEntry = options.harnessEntry;
+        this.nodePath = options.nodePath ?? process.execPath;
+        this.nodeArgs = options.nodeArgs ?? [];
+        this.sharedSecret = options.sharedSecret ?? randomBytes(24).toString('hex');
+        this.extraEnv = options.env ?? {};
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.spawnImpl = options.spawnImpl ?? spawn;
+        this.pickPort = options.pickPort ?? ephemeralPort;
+        this.readyTimeoutMs = options.readyTimeoutMs ?? 30_000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+    }
+    async dispatch(ref, spec, kind = 'agent') {
+        const proc = await this.ensureProcess();
+        // The harness keys jobs by the per-step `ref.jobId` in the body; a re-dispatch
+        // (durable-driver replay) re-POSTs, which the JobRegistry treats as a re-attach.
+        await postHarnessJob({
+            fetchImpl: this.fetchImpl,
+            endpoint: endpointFor(proc.port),
+            secret: this.sharedSecret,
+            body: { ...spec, kind },
+            timeoutMs: this.requestTimeoutMs,
+            label: 'Native harness',
+        });
+    }
+    async poll(ref) {
+        const proc = this.proc;
+        // The process died (or was never started) → report an eviction so the run can recover.
+        if (!proc || proc.exited)
+            return { state: 'failed', error: EVICTION_ERROR };
+        return pollHarnessJob({
+            fetchImpl: this.fetchImpl,
+            endpoint: endpointFor(proc.port),
+            jobId: ref.jobId,
+            secret: this.sharedSecret,
+            timeoutMs: this.requestTimeoutMs,
+            label: 'Native harness',
+            isDead: () => proc.exited,
+        });
+    }
+    /**
+     * No per-run teardown: the harness host process is long-lived and reused across runs
+     * (the harness already removes each job's ephemeral workspace itself). Provided so the
+     * port contract is satisfied; kept idempotent.
+     */
+    async release() {
+        // intentionally a no-op
+    }
+    /** Stop the harness process (for shutdown / tests). Idempotent. */
+    async shutdown() {
+        const proc = this.proc;
+        this.proc = undefined;
+        this.starting = undefined;
+        if (proc && !proc.exited)
+            proc.child.kill();
+    }
+    // --- internals ----------------------------------------------------------
+    async ensureProcess() {
+        if (this.proc && !this.proc.exited)
+            return this.proc;
+        this.starting ??= this.startProcess();
+        try {
+            this.proc = await this.starting;
+            return this.proc;
+        }
+        finally {
+            this.starting = undefined;
+        }
+    }
+    async startProcess() {
+        const port = await this.pickPort();
+        const child = this.spawnImpl(this.nodePath, [...this.nodeArgs, this.harnessEntry], {
+            env: {
+                ...process.env,
+                ...this.extraEnv,
+                PORT: String(port),
+                HARNESS_SHARED_SECRET: this.sharedSecret,
+                // The harness only auto-listens when NODE_ENV !== 'test'.
+                NODE_ENV: 'production',
+            },
+            stdio: 'ignore',
+        });
+        const handle = { child, port, exited: false };
+        // The harness child is long-lived and not detached, but Node does NOT auto-kill a
+        // child when the parent exits — without this, every dev restart orphans a `node
+        // <harness>` process still bound to its port (and possibly mid-run on the developer's
+        // live Claude/Codex login). `shutdown()` covers the graceful path; this `exit` hook is
+        // the backstop for SIGTERM/SIGINT/uncaught exits that reach `process.exit` directly.
+        const killOnParentExit = () => {
+            try {
+                child.kill();
+            }
+            catch {
+                // best-effort
+            }
+        };
+        process.once('exit', killOnParentExit);
+        child.on('exit', () => {
+            handle.exited = true;
+            process.removeListener('exit', killOnParentExit);
+            if (this.proc === handle)
+                this.proc = undefined;
+        });
+        await this.waitForHealth(port, handle);
+        return handle;
+    }
+    waitForHealth(port, handle) {
+        return waitForHarnessHealth({
+            fetchImpl: this.fetchImpl,
+            endpoint: endpointFor(port),
+            readyTimeoutMs: this.readyTimeoutMs,
+            requestTimeoutMs: this.requestTimeoutMs,
+            intervalMs: 200,
+            isDead: () => handle.exited,
+            deadError: 'the native harness process exited before becoming healthy',
+            timeoutError: `Timed out waiting for the native harness on 127.0.0.1:${port} to become healthy`,
+        });
+    }
+}
+/**
+ * Build a {@link LocalProcessRunnerTransport} from the environment. Requires
+ * `LOCAL_HARNESS_ENTRY` (the path to the executor-harness server entry to run as a host
+ * process). The native CLIs (`claude` / `codex`) must already be installed on the host.
+ */
+export function createLocalProcessTransportFromEnv(env) {
+    const harnessEntry = env.LOCAL_HARNESS_ENTRY?.trim();
+    if (!harnessEntry) {
+        throw new Error('LOCAL_HARNESS_ENTRY is required for native local mode (LOCAL_NATIVE_AGENTS): set it to ' +
+            'the executor-harness server entry path (its built server.js, or src/server.ts run via ' +
+            'Node type-stripping).');
+    }
+    const nodeArgs = env.LOCAL_HARNESS_NODE_ARGS?.trim()
+        ? env.LOCAL_HARNESS_NODE_ARGS.trim().split(/\s+/)
+        : undefined;
+    const allowedHosts = env.GITHUB_ALLOWED_HOSTS?.trim();
+    return new LocalProcessRunnerTransport({
+        harnessEntry,
+        ...(nodeArgs ? { nodeArgs } : {}),
+        sharedSecret: env.HARNESS_SHARED_SECRET?.trim() || undefined,
+        ...(allowedHosts ? { env: { GITHUB_ALLOWED_HOSTS: allowedHosts } } : {}),
+    });
+}
+//# sourceMappingURL=LocalProcessRunnerTransport.js.map

package/dist/LocalProcessRunnerTransport.js.map

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

package/dist/NativeRoutingRunnerTransport.d.ts

@@ -0,0 +1,20 @@
+import type { RunnerDispatchKind, RunnerDispatchOptions, RunnerJobRef, RunnerJobView, RunnerTransport } from '@cat-factory/kernel';
+export declare class NativeRoutingRunnerTransport implements RunnerTransport {
+    /** Host-process transport for ambient (native CLI) steps — built lazily, cached. */
+    private readonly ambient;
+    /** Per-run container transport for everything else — built lazily, cached (the
+     * container transport resolves its pool config from the DB, so this may be async). */
+    private readonly managed;
+    /** ref → the transport that handled its dispatch, so poll/release hit the same backend. */
+    private readonly routed;
+    constructor(
+    /** Host-process transport for ambient (native CLI) steps — built lazily, cached. */
+    ambient: () => RunnerTransport | Promise<RunnerTransport>, 
+    /** Per-run container transport for everything else — built lazily, cached (the
+     * container transport resolves its pool config from the DB, so this may be async). */
+    managed: () => RunnerTransport | Promise<RunnerTransport>);
+    dispatch(ref: RunnerJobRef, spec: Record<string, unknown>, kind?: RunnerDispatchKind, options?: RunnerDispatchOptions): Promise<void>;
+    poll(ref: RunnerJobRef): Promise<RunnerJobView>;
+    release(ref: RunnerJobRef): Promise<void>;
+}
+//# sourceMappingURL=NativeRoutingRunnerTransport.d.ts.map

package/dist/NativeRoutingRunnerTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeRoutingRunnerTransport.d.ts","sourceRoot":"","sources":["../src/NativeRoutingRunnerTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,eAAe,EAChB,MAAM,qBAAqB,CAAA;AAqB5B,qBAAa,4BAA6B,YAAW,eAAe;IAKhE,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB;0FACsF;IACtF,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAE5D;IACE,oFAAoF;IACnE,OAAO,EAAE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAC1E;0FACsF;IACrE,OAAO,EAAE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,EACxE;IAEE,QAAQ,CACZ,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,GAAE,kBAA4B,EAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAIf;IAEK,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAMpD;IAEK,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAI9C;CACF"}

package/dist/NativeRoutingRunnerTransport.js

@@ -0,0 +1,50 @@
+// NATIVE-MODE transport router (local facade, `LOCAL_NATIVE_AGENTS`): native mode runs the
+// developer's OWN `claude` / `codex` CLI as a host process (no sandbox), which is only
+// appropriate for the steps that actually use that ambient login. The executor flags such a
+// step with `ambientAuth: true` on its job body; everything else (a proxy/`pi` model, or a
+// non-native vendor reusing the claude-code harness) MUST still run in a sandboxed per-run
+// container, exactly as the README promises ("proxy-only models still need the container
+// path"). Previously native mode sent EVERY dispatch to the host process, silently running
+// proxy-model steps unsandboxed.
+//
+// So this routes per JOB (not per run — a single run legitimately mixes an ambient Claude
+// step with a proxy step): `ambientAuth` jobs → the host-process transport; the rest → the
+// container transport (built lazily, so a native deployment that only runs Claude/Codex
+// never needs LOCAL_HARNESS_IMAGE; a proxy step without an image fails loudly there). The
+// chosen transport is remembered per ref so poll/release reach the same backend.
+const EVICTION_ERROR = 'Job not found (container evicted or crashed)';
+const refKey = (ref) => `${ref.runId}:${ref.jobId}`;
+export class NativeRoutingRunnerTransport {
+    ambient;
+    managed;
+    /** ref → the transport that handled its dispatch, so poll/release hit the same backend. */
+    routed = new Map();
+    constructor(
+    /** Host-process transport for ambient (native CLI) steps — built lazily, cached. */
+    ambient, 
+    /** Per-run container transport for everything else — built lazily, cached (the
+     * container transport resolves its pool config from the DB, so this may be async). */
+    managed) {
+        this.ambient = ambient;
+        this.managed = managed;
+    }
+    async dispatch(ref, spec, kind = 'agent', options) {
+        const transport = await (spec.ambientAuth === true ? this.ambient() : this.managed());
+        this.routed.set(refKey(ref), transport);
+        await transport.dispatch(ref, spec, kind, options);
+    }
+    async poll(ref) {
+        // Unknown ref (a fresh process after a durable replay): report an eviction so the
+        // sweeper re-drives — the re-dispatch (idempotent) re-populates the routing map.
+        const transport = this.routed.get(refKey(ref));
+        if (!transport)
+            return { state: 'failed', error: EVICTION_ERROR };
+        return transport.poll(ref);
+    }
+    async release(ref) {
+        const transport = this.routed.get(refKey(ref));
+        this.routed.delete(refKey(ref));
+        await transport?.release?.(ref);
+    }
+}
+//# sourceMappingURL=NativeRoutingRunnerTransport.js.map

package/dist/NativeRoutingRunnerTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeRoutingRunnerTransport.js","sourceRoot":"","sources":["../src/NativeRoutingRunnerTransport.ts"],"names":[],"mappings":"AAQA,2FAA2F;AAC3F,uFAAuF;AACvF,4FAA4F;AAC5F,2FAA2F;AAC3F,2FAA2F;AAC3F,yFAAyF;AACzF,2FAA2F;AAC3F,iCAAiC;AACjC,EAAE;AACF,0FAA0F;AAC1F,2FAA2F;AAC3F,wFAAwF;AACxF,0FAA0F;AAC1F,iFAAiF;AAEjF,MAAM,cAAc,GAAG,8CAA8C,CAAA;AAErE,MAAM,MAAM,GAAG,CAAC,GAAiB,EAAU,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,EAAE,CAAA;AAEzE,MAAM,OAAO,4BAA4B;IAMpB,OAAO;IAGP,OAAO;IAR1B,2FAA2F;IAC1E,MAAM,GAAG,IAAI,GAAG,EAA2B,CAAA;IAE5D;IACE,oFAAoF;IACnE,OAAyD;IAC1E;0FACsF;IACrE,OAAyD;uBAHzD,OAAO;uBAGP,OAAO;IACvB,CAAC;IAEJ,KAAK,CAAC,QAAQ,CACZ,GAAiB,EACjB,IAA6B,EAC7B,IAAI,GAAuB,OAAO,EAClC,OAA+B;QAE/B,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;QACrF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAA;QACvC,MAAM,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACpD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAiB;QAC1B,kFAAkF;QAClF,iFAAiF;QACjF,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAC9C,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,CAAA;QACjE,OAAO,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC5B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAiB;QAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAC9C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAC/B,MAAM,SAAS,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAAA;IACjC,CAAC;CACF"}

package/dist/container.d.ts

@@ -1,4 +1,17 @@
 import type { NodeContainerOptions } from '@cat-factory/node-server';
 import type { ServerContainer } from '@cat-factory/server';
+import type { HarnessKind } from '@cat-factory/kernel';
 export declare function buildLocalContainer(options: NodeContainerOptions): ServerContainer;
+/**
+ * Parse `LOCAL_NATIVE_AGENTS` into the set of subscription harnesses to run natively. The
+ * documented form is a comma-separated list of harness ids (`claude-code,codex`); `claude`
+ * is accepted as an alias for `claude-code`. Blank/unset OR an explicit off value
+ * (`false`/`0`/`off`/`no`/`none`/`disabled`) ⇒ off (`[]`) — so disabling native mode never
+ * accidentally enables it. An affirmative value naming no harness (`true`/`1`/`on`/…) ⇒ BOTH
+ * native harnesses. Only `claude-code` / `codex` are ever native; any other unrecognised
+ * token is ignored. A value with neither a recognised harness nor an affirmative keyword
+ * (e.g. a typo) ⇒ off, so an unintelligible setting fails safe rather than enabling an
+ * unsandboxed, unmetered mode.
+ */
+export declare function parseNativeHarnesses(raw: string | undefined): HarnessKind[];
 //# sourceMappingURL=container.d.ts.map

package/dist/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAGpE,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,qBAAqB,CAAA;AA8B7F,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,eAAe,CAiLlF"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAIpE,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAG7F,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,qBAAqB,CAAA;AAuCvE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,eAAe,CA2RlF;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,EAAE,CAc3E"}

package/dist/container.js

@@ -1,22 +1,31 @@
-import { CryptoIdGenerator, DrizzleGitHubInstallationRepository, DrizzleRunnerPoolConnectionRepository, ProvisioningLogRecorder, SystemClock, buildNodeContainer, buildNodeResolveTransport, createDrizzleRepositories, loadNodeConfig, withProvisioningLog, } from '@cat-factory/node-server';
+import { CryptoIdGenerator, DrizzleGitHubInstallationRepository, DrizzleLocalSettingsRepository, DrizzleRunnerPoolConnectionRepository, ProvisioningLogRecorder, SystemClock, buildNodeContainer, buildNodeResolveTransport, createDrizzleRepositories, loadNodeConfig, withProvisioningLog, } from '@cat-factory/node-server';
 import { ConflictError } from '@cat-factory/kernel';
 import { WorkspaceSettingsService } from '@cat-factory/orchestration';
+import { logger } from '@cat-factory/server';
+import { LocalSettingsService } from '@cat-factory/integrations';
+import { NativeRoutingRunnerTransport } from './NativeRoutingRunnerTransport.js';
 import { applyLocalDefaults } from './config.js';
 import { createLocalGitHubClient, fetchPatAccount, githubPatCreationUrl } from './github.js';
 import { AutoProvisioningInstallationRepository } from './installations.js';
 import { createLocalContainerTransportFromEnv, } from './LocalContainerRunnerTransport.js';
+import { createLocalProcessTransportFromEnv, } from './LocalProcessRunnerTransport.js';
 import { createRuntimeAdapter } from './runtimes/index.js';
 // The local-mode composition root. It is intentionally thin: the ENTIRE Drizzle/
 // Postgres persistence, pg-boss durable execution, gateways and model provisioning
 // come from `buildNodeContainer` unchanged. Local mode only swaps the differentiators
 // behind the seams `buildNodeContainer` exposes:
 //   - the runner backend → host Docker by default (a per-run local container,
-//     LocalContainerRunnerTransport, Docker/Podman/OrbStack/Colima/Apple `container`),
-//     but PER WORKSPACE it can be delegated to the workspace's registered self-hosted
-//     runner pool (the `delegateAgentsToRunnerPool` setting) — the local-vs-external
-//     opt-in. The Tester's environment is the symmetric opt-in (`delegateTestEnvToProvider`,
-//     wired below as the tester fallback default), so a developer runs everything locally
-//     by default but can flip either concern to an external service from the UI;
+//     LocalContainerRunnerTransport, Docker/Podman/OrbStack/Colima/Apple `container`,
+//     with the warm pool + per-repo checkout reuse configured from the DB local-mode
+//     settings), but PER WORKSPACE it can be delegated to the workspace's registered
+//     self-hosted runner pool (the `delegateAgentsToRunnerPool` setting) — the
+//     local-vs-external opt-in. The Tester's environment is the symmetric opt-in
+//     (`delegateTestEnvToProvider`, wired below as the tester fallback default), so a
+//     developer runs everything locally by default but can flip either concern to an
+//     external service from the UI;
+//   - optional NATIVE execution: run agents as a host process driving the developer's own
+//     installed `claude` / `codex` CLI (ambient login), bypassing Docker for the steps that
+//     use that login (`LOCAL_NATIVE_AGENTS`); everything else still runs in a container;
 //   - the push/clone token → a static GitHub PAT (`GITHUB_PAT`) instead of a GitHub
 //     App installation token.
 // Repo resolution is unchanged: the executor still resolves a block's repo from the
@@ -34,9 +43,18 @@ export function buildLocalContainer(options) {
     // ON: the Node loader only enables it for a configured GitHub App, but local mode reaches
     // GitHub through the PAT-backed client, so the read/link endpoints (connection, available
     // repos, "add from existing repo") should be served the same way.
+    // Native local execution (opt-in): run agents as a host process driving the developer's
+    // OWN installed `claude` / `codex` CLI (ambient login), bypassing Docker. The env is the
+    // ALLOW-LIST of subscription harnesses to run natively (`claude-code,codex`); parsed into
+    // a harness set so the executor flags `ambientAuth` ONLY for a listed harness whose vendor
+    // is that CLI's native vendor (Claude/Codex), and the personal-credential gate skips just
+    // those vendors. Default off — the container path is unchanged.
+    const nativeHarnesses = parseNativeHarnesses(env.LOCAL_NATIVE_AGENTS);
+    const nativeAgents = nativeHarnesses.length > 0;
     const config = {
         ...base,
         ...(pat ? { github: { ...base.github, enabled: true } } : {}),
+        ...(nativeAgents ? { nativeAmbientAuth: nativeHarnesses } : {}),
         localMode: {
             enabled: true,
             ...(pat ? {} : { githubPatSetupUrl: githubPatCreationUrl() }),
@@ -62,15 +80,92 @@ export function buildLocalContainer(options) {
         workspaceSettingsRepository: repos.workspaceSettingsRepository,
         workspaceRepository: repos.workspaceRepository,
     });
-    // The Docker transport is constructed LAZILY on first container-job dispatch, so the
-    // service still boots to serve the board (and inline kinds) when LOCAL_HARNESS_IMAGE
-    // is unset — only repo-operating kinds then fail, loudly and with a clear message,
+    // The local container transport is constructed LAZILY on first dispatch, so the service
+    // still boots to serve the board (and inline kinds) when LOCAL_HARNESS_IMAGE is unset —
+    // only repo-operating container kinds then fail, loudly and with a clear message,
     // mirroring how the Node facade treats a missing runner backend.
-    let transport;
-    const localResolve = () => {
-        transport ??= createLocalContainerTransportFromEnv(env);
-        return Promise.resolve(transport);
+    //
+    // Native mode does NOT blanket-route every dispatch to the host process: a host process
+    // has no sandbox, so only the steps that actually use the developer's ambient CLI login
+    // (flagged `ambientAuth` by the executor) run there. Everything else — a proxy/`pi` model,
+    // or a non-native vendor reusing the claude-code harness — still runs in a per-run
+    // container (built lazily, so a Claude/Codex-only native deployment never needs an image;
+    // a proxy step without one fails loudly there). See NativeRoutingRunnerTransport.
+    // Local-mode operational settings (warm-pool sizing + per-repo checkout reuse) live in
+    // the DB as a per-deployment singleton, edited through the dedicated local-mode settings
+    // panel — they REPLACED the old LOCAL_POOL_* / HARNESS_* env vars. Built here so the
+    // serving transport resolves its pool config from it and the local-settings controller
+    // can read/write it. Requires the Drizzle db (always present for the local service).
+    // The serving container transport is built once, lazily, reading its pool + checkout
+    // config from the DB settings (not env). The promise is cached so every dispatch — and
+    // the native router's container leg — reuses the same instance (and its in-process pool).
+    // A settings edit is applied LIVE to this instance (see the service's `onChange` below),
+    // so the panel takes effect without a restart.
+    let containerTransport;
+    const localSettingsService = options.db
+        ? new LocalSettingsService({
+            localSettingsRepository: new DrizzleLocalSettingsRepository(options.db),
+            clock: { now: () => Date.now() },
+            // Apply an edit to the already-built serving transport so the warm-pool + checkout
+            // config takes effect WITHOUT a restart. No-op until the transport is built (the
+            // next build reads the fresh settings anyway); a still-failing build is swallowed
+            // (a later dispatch surfaces the real problem with a clearer message).
+            onChange: async (settings) => {
+                if (!containerTransport)
+                    return;
+                try {
+                    ;
+                    (await containerTransport).applySettings(settings);
+                }
+                catch {
+                    // transport build is still failing — nothing to reconfigure yet
+                }
+            },
+        })
+        : undefined;
+    const buildServingTransport = async () => {
+        const settings = await localSettingsService?.resolve();
+        const transport = createLocalContainerTransportFromEnv(env, settings);
+        // Boot housekeeping on the SERVING instance: reap exited per-run containers, drain
+        // pool members orphaned by a previous process, and pre-warm to poolMinWarm. Best
+        // -effort — if the container runtime is down this throws, but a later dispatch then
+        // fails loudly with a clearer message, so swallow it here.
+        await transport.reapExited().catch((err) => {
+            logger.warn({ err: err instanceof Error ? err.message : String(err) }, 'local mode: could not reap / pre-warm job containers at startup');
+        });
+        return transport;
+    };
+    const resolveContainerTransport = () => {
+        if (!containerTransport) {
+            containerTransport = buildServingTransport();
+            // Don't let a transient build failure (e.g. a DB blip resolving the settings) poison
+            // every future dispatch: drop the cached promise on rejection so the next call retries.
+            containerTransport.catch(() => {
+                containerTransport = undefined;
+            });
+        }
+        return containerTransport;
     };
+    // The local-agents resolver: in native mode the per-job router (only ambient-CLI steps go
+    // to the host process, the rest to a container), otherwise the warm-pool container
+    // transport directly.
+    let routed;
+    const localAgentsResolve = () => {
+        if (nativeAgents) {
+            if (!routed) {
+                let proc;
+                routed = new NativeRoutingRunnerTransport(() => (proc ??= createLocalProcessTransportFromEnv(env)), resolveContainerTransport);
+            }
+            return Promise.resolve(routed);
+        }
+        return resolveContainerTransport();
+    };
+    // Eagerly kick off the serving transport's boot housekeeping (reap + pre-warm) when an
+    // image is configured, so a warm pool is ready before the first run rather than warming
+    // on first dispatch. Skipped without an image (the board still boots; only container
+    // kinds fail, loudly). Fire-and-forget: dispatch reuses the same cached promise.
+    if (env.LOCAL_HARNESS_IMAGE?.trim())
+        void resolveContainerTransport().catch(() => { });
     // The runner-pool resolver (the external opt-in target). In local mode `runners` is
     // enabled (it keys off ENCRYPTION_KEY, which `applyLocalDefaults` always sets), so this
     // is non-null and a workspace can register a pool via the API; a native adapter injected
@@ -87,11 +182,12 @@ export function buildLocalContainer(options) {
         idGenerator,
         clock,
     });
-    const wrappedLocal = withProvisioningLog(localResolve, recorder, 'container');
+    const wrappedLocal = withProvisioningLog(localAgentsResolve, recorder, 'container');
     const wrappedPool = poolResolve ? withProvisioningLog(poolResolve, recorder, 'runner-pool') : null;
     // The local-vs-external agents opt-in: dispatch to the registered runner pool when the
-    // workspace opts in (and one is wrapped), else to host Docker. The pool branch's own
-    // throw surfaces a clean "register a pool" message when delegation is on but none exists.
+    // workspace opts in (and one is wrapped), else to host Docker (the warm-pool / native
+    // local backend). The pool branch's own throw surfaces a clean "register a pool" message
+    // when delegation is on but none exists.
     const resolveTransport = async (workspaceId) => {
         const delegate = !!workspaceId && (await wsSettings.get(workspaceId)).delegateAgentsToRunnerPool;
         if (delegate && wrappedPool)
@@ -132,15 +228,21 @@ export function buildLocalContainer(options) {
     // engine so it refuses a local-infra Tester run on an incapable runtime ("limited
     // mode") instead of dispatching a job that can't stand its dependencies up. Building
     // the adapter is pure (no IO), so this is cheap even though the transport stays lazy.
-    const localTestInfraSupported = createRuntimeAdapter(env).capabilities.localDind;
-    return buildNodeContainer({
+    // Native mode runs agents on the host with no per-run Docker container; the Tester's
+    // local docker-compose infra (host compose with per-run project names) is a later phase,
+    // so it's reported unsupported for now (the engine steers to "limited mode"). The
+    // container path keeps the runtime's real Docker-in-Docker capability.
+    const localTestInfraSupported = nativeAgents
+        ? false
+        : createRuntimeAdapter(env).capabilities.localDind;
+    const container = buildNodeContainer({
         ...options,
         env,
         config,
         repos,
-        // The per-workspace chooser (host Docker vs the runner pool). Pre-wrapped with the
-        // correct provisioning-log subsystem per branch, so tell buildNodeContainer not to
-        // re-wrap with a single subsystem tag.
+        // The per-workspace chooser (host Docker / native local vs the runner pool). Pre-wrapped
+        // with the correct provisioning-log subsystem per branch, so tell buildNodeContainer not
+        // to re-wrap with a single subsystem tag.
         resolveTransport,
         skipProvisioningLogWrap: true,
         // Authenticate git with the developer's PAT when present. Absent → the executor
@@ -174,5 +276,46 @@ export function buildLocalContainer(options) {
             localTestInfraSupported,
         },
     });
+    // Surface the local-mode settings service so the dedicated local-settings panel can
+    // read/write the warm-pool + checkout config (the controller 503s when this is absent,
+    // which is the case on every non-local facade).
+    return localSettingsService
+        ? { ...container, localSettings: { service: localSettingsService } }
+        : container;
+}
+/** Values that explicitly DISABLE native mode (so `LOCAL_NATIVE_AGENTS=false` means off). */
+const NATIVE_OFF_VALUES = new Set(['false', '0', 'off', 'no', 'none', 'disabled']);
+/** Affirmative values that enable BOTH native harnesses without naming one. */
+const NATIVE_ALL_VALUES = new Set(['true', '1', 'on', 'yes', 'all', 'both']);
+/**
+ * Parse `LOCAL_NATIVE_AGENTS` into the set of subscription harnesses to run natively. The
+ * documented form is a comma-separated list of harness ids (`claude-code,codex`); `claude`
+ * is accepted as an alias for `claude-code`. Blank/unset OR an explicit off value
+ * (`false`/`0`/`off`/`no`/`none`/`disabled`) ⇒ off (`[]`) — so disabling native mode never
+ * accidentally enables it. An affirmative value naming no harness (`true`/`1`/`on`/…) ⇒ BOTH
+ * native harnesses. Only `claude-code` / `codex` are ever native; any other unrecognised
+ * token is ignored. A value with neither a recognised harness nor an affirmative keyword
+ * (e.g. a typo) ⇒ off, so an unintelligible setting fails safe rather than enabling an
+ * unsandboxed, unmetered mode.
+ */
+export function parseNativeHarnesses(raw) {
+    const trimmed = raw?.trim().toLowerCase();
+    if (!trimmed || NATIVE_OFF_VALUES.has(trimmed))
+        return [];
+    const out = new Set();
+    let affirmative = false;
+    for (const token of trimmed.split(',').map((s) => s.trim())) {
+        if (token === 'claude-code' || token === 'claude')
+            out.add('claude-code');
+        else if (token === 'codex')
+            out.add('codex');
+        else if (NATIVE_ALL_VALUES.has(token))
+            affirmative = true;
+    }
+    if (out.size > 0)
+        return [...out];
+    // No harness named: enable both ONLY for an explicit affirmative keyword; anything else
+    // unrecognised stays off (fail-safe — see the doc comment).
+    return affirmative ? ['claude-code', 'codex'] : [];
 }
 //# sourceMappingURL=container.js.map