spexcode 0.6.5 → 0.6.6

package/node_modules/@spexcode/spec-cli/dist/codex-runtime-generations.d.ts

@@ -31,7 +31,12 @@ export type CodexGenerationLedger = Readonly<{
 export declare function codexGenerationSocketPath(root: string, generationId?: string): string;
 export declare function legacyCodexGenerationEndpoint(root: string): CodexGenerationEndpoint;
 export declare function readCodexGenerationLedger(root: string): CodexGenerationLedger;
+export type CodexGenerationRotation = Readonly<{
+    previous: CodexGenerationEndpoint;
+    current: CodexGenerationEndpoint;
+}>;
 export declare function ensureCodexCurrentGeneration(root: string, start: (endpoint: CodexGenerationEndpoint) => Promise<void>): Promise<CodexGenerationEndpoint>;
+export declare function rotateCodexCurrentGeneration(root: string, start: (endpoint: CodexGenerationEndpoint) => Promise<void>): Promise<CodexGenerationRotation>;
 export declare function bindCodexGeneration(root: string, sessionId: string, threadId: string, generationId: string | null): void;
 export declare function prepareCodexGenerationRegistration(root: string, sessionId: string, threadId: string, generationId: string): void;
 export declare function commitCodexGenerationRegistration(root: string, sessionId: string, threadId: string, generationId: string): void;

package/node_modules/@spexcode/spec-cli/dist/codex-runtime-generations.js

@@ -497,6 +497,118 @@ export async function ensureCodexCurrentGeneration(root, start) {
         return publishPendingGeneration(root, action.endpoint);
     }
 }
+// An operator can move NEW traffic off a current root that is still exactly identifiable but unhealthy. This is
+// deliberately not a restart: bindings remain on the old endpoint, which keeps serving them as draining until
+// its ordinary zero-reference reclamation proof succeeds.
+async function publishRotatedGeneration(root, endpoint) {
+    return withLedgerLock(root, async () => {
+        let previous = readCodexGenerationLedger(root);
+        if (previous.pending !== endpoint.id || !endpointIdentity(endpoint))
+            throw new Error('Codex generation rotation CAS lost or candidate identity changed before publication');
+        const previousId = previous.current;
+        const old = previousId ? previous.generations[previousId] : null;
+        if (!previousId || !old || old.state !== 'current')
+            throw new Error('canonical Codex generation changed during rotation; retry');
+        if (!endpointIdentity(old.endpoint)) {
+            // A root proven gone during the finite start window is safe to retire. Ambiguity remains a refusal: a
+            // ready candidate stays durably pending for a later explicit retry, rather than guessing at ownership.
+            const retired = retireGoneGenerationLocked(root, previous, previousId);
+            if (!retired)
+                throw new Error('canonical Codex generation became unproven during rotation; refusing to switch traffic');
+            previous = retired;
+        }
+        const generations = {
+            ...previous.generations,
+            [endpoint.id]: { state: 'current', endpoint },
+        };
+        if (previous.current)
+            generations[previous.current] = { state: 'draining', endpoint: old.endpoint };
+        writeLedger(root, previous, { current: endpoint.id, pending: null, generations, bindings: previous.bindings });
+        return { previous: old.endpoint, current: endpoint };
+    });
+}
+export async function rotateCodexCurrentGeneration(root, start) {
+    const deadline = Date.now() + 30_000;
+    for (;;) {
+        const action = await withLedgerLock(root, async () => {
+            let previous = readCodexGenerationLedger(root);
+            if (previous.revision === 0 && !existsSync(ledgerPath(root))) {
+                const bootstrapped = bootstrapLedger(root);
+                previous = writeLedger(root, previous, bootstrapped);
+            }
+            const current = previous.current ? previous.generations[previous.current] : null;
+            if (!current || current.state !== 'current')
+                throw new Error('there is no proven canonical app-server generation to switch; launch a Codex session first');
+            if (!endpointIdentity(current.endpoint)) {
+                if (goneGeneration(current.endpoint))
+                    throw new Error('canonical Codex generation is already dead; a normal Codex launch will replace it');
+                throw new Error('canonical app-server generation is unproven; refusing to switch traffic');
+            }
+            if (previous.pending) {
+                const pending = previous.generations[previous.pending];
+                if (!pending || pending.state !== 'starting')
+                    throw new Error('Codex generation ledger pending rotation is malformed');
+                // A prior coordinator may have completed the detached spawn but crashed before the pointer CAS.
+                if (endpointIdentity(pending.endpoint))
+                    return { kind: 'publish', endpoint: pending.endpoint };
+                if (pending.reservation && processStartToken(pending.reservation.pid) === pending.reservation.startToken)
+                    return { kind: 'wait' };
+                const generations = { ...previous.generations };
+                delete generations[pending.endpoint.id];
+                writeLedger(root, previous, { current: previous.current, pending: null, generations, bindings: previous.bindings });
+                return { kind: 'retry' };
+            }
+            const endpoint = newEndpoint(root);
+            const startToken = processStartToken(process.pid);
+            if (!startToken)
+                throw new Error('cannot prove coordinator process identity for Codex generation rotation reservation');
+            mkdirSync(dirname(endpoint.pidFile), { recursive: true, mode: 0o700 });
+            writeLedger(root, previous, {
+                current: previous.current,
+                pending: endpoint.id,
+                generations: { ...previous.generations, [endpoint.id]: { state: 'starting', endpoint, reservation: { pid: process.pid, startToken } } },
+                bindings: previous.bindings,
+            });
+            return { kind: 'start', endpoint };
+        });
+        if (action.kind === 'publish')
+            return publishRotatedGeneration(root, action.endpoint);
+        if (action.kind === 'retry')
+            continue;
+        if (action.kind === 'wait') {
+            if (Date.now() >= deadline)
+                throw new Error('Codex generation rotation reservation owner is still live but did not publish; retry after it exits');
+            await sleep(50);
+            continue;
+        }
+        try {
+            await start(action.endpoint);
+        }
+        catch (error) {
+            await withLedgerLock(root, async () => {
+                const previous = readCodexGenerationLedger(root);
+                if (previous.pending !== action.endpoint.id || endpointIdentity(action.endpoint))
+                    return;
+                const generations = { ...previous.generations };
+                delete generations[action.endpoint.id];
+                writeLedger(root, previous, { current: previous.current, pending: null, generations, bindings: previous.bindings });
+            });
+            throw error;
+        }
+        if (!await waitForEndpoint(action.endpoint)) {
+            await withLedgerLock(root, async () => {
+                const previous = readCodexGenerationLedger(root);
+                if (previous.pending !== action.endpoint.id || endpointIdentity(action.endpoint))
+                    return;
+                const generations = { ...previous.generations };
+                delete generations[action.endpoint.id];
+                writeLedger(root, previous, { current: previous.current, pending: null, generations, bindings: previous.bindings });
+            });
+            throw new Error(`candidate Codex generation ${action.endpoint.id} did not prove a live detached endpoint; current pointer was not switched`);
+        }
+        return publishRotatedGeneration(root, action.endpoint);
+    }
+}
 export function bindCodexGeneration(root, sessionId, threadId, generationId) {
     withLedgerLockSync(root, () => {
         const previous = readCodexGenerationLedger(root);

package/node_modules/@spexcode/spec-cli/dist/doctor.js

@@ -518,7 +518,9 @@ function usage() {
     console.error(`spex doctor — diagnose spec health and how the SpexCode workflow reaches your agent
   (bare)         spec-health findings + delivery report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint
   --contract     print the surface:system contract text (hand it to any agent)
-  --conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)`);
+  --conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)
+  repair app-server [--launcher <name>]
+                  prove a fresh app-server, then switch new sessions to it without moving existing sessions`);
     return 0;
 }
 export async function runDoctor(args) {
@@ -530,6 +532,10 @@ export async function runDoctor(args) {
         return contract();
     if (args.includes('--conflicts'))
         return await conflicts();
+    if (args[0] === 'repair') {
+        const { runDoctorRepairAppServer } = await import('./runtime-rotate.js');
+        return await runDoctorRepairAppServer(args);
+    }
     switch (args[0]) {
         case undefined: return await doctor();
         case 'contract':

package/node_modules/@spexcode/spec-cli/dist/gateway-hub.js

@@ -327,11 +327,13 @@ export function startHubGateway(opts) {
         socket.once('close', () => upstream.destroy());
         upstream.once('close', () => socket.destroy());
     });
-    const onListen = () => {
-        const scheme = secure ? 'https' : 'http';
-        console.log(`[hub] multi-project gateway on ${scheme}://${opts.host ?? '0.0.0.0'}:${port} — /projects + /p/:projectId/*`);
-    };
-    listenOrExit(server, port, { host: opts.host, label: opts.label ?? 'hub gateway', cleanup: opts.onBindFail, onListen });
+    const scheme = secure ? 'https' : 'http';
+    listenOrExit(server, port, {
+        host: opts.host,
+        label: opts.label ?? 'hub gateway',
+        cleanup: opts.onBindFail,
+        ready: `[hub] multi-project gateway on ${scheme}://${opts.host ?? '0.0.0.0'}:${port} — /projects + /p/:projectId/*`,
+    });
     return server;
 }
 // replay an upgrade's headers with the Cookie header rewritten to exclude the gateway's own cookies.

package/node_modules/@spexcode/spec-cli/dist/gateway.d.ts

@@ -22,6 +22,7 @@ export type GatewayOpts = {
     label?: string;
     onBindFail?: () => void;
     projectRoot?: string;
+    readyLines?: string[];
 };
 export declare function startGateway(opts: GatewayOpts): void;
 export declare function rawHeaders(req: http.IncomingMessage): string;

package/node_modules/@spexcode/spec-cli/dist/gateway.js

@@ -178,17 +178,15 @@ export function startGateway(opts) {
     // narrows the public gateway's reach. The gate note keys on LOOPBACK, not on host-being-explicit:
     // an ungated loopback bind is normal, an ungated wide bind is announced — never silent.
     const isLoopback = opts.host === '127.0.0.1' || opts.host === 'localhost' || opts.host === '::1';
-    const onListen = () => {
-        const scheme = secure ? 'https' : 'http';
-        const label = opts.label ?? 'public mode';
-        const gate = isLoopback ? '' : ` — ${gated ? 'password-gated' : 'OPEN (no password)'}`;
-        console.log(`[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`);
-        if (!secure && !isLoopback && !opts.host)
-            console.log('[gateway] (TLS off — --http)');
-    };
+    const scheme = secure ? 'https' : 'http';
+    const label = opts.label ?? 'public mode';
+    const gate = isLoopback ? '' : ` — ${gated ? 'password-gated' : 'OPEN (no password)'}`;
+    const ready = [...(opts.readyLines ?? []), `[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`];
+    if (!secure && !isLoopback && !opts.host)
+        ready.push('[gateway] (TLS off — --http)');
     // a busy public port is a hard, loud, non-zero exit — the SAME contract as the supervisor's proxy
     // (see [[spec-cli]] / listen.ts), so `spex serve` and `spex serve ui` fail a port clash identically.
-    listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, onListen });
+    listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, ready });
 }
 // re-serialize an upgrade request's headers for replay against the upstream (exported for the host
 // gateway's per-project WS pipe, which replays the same way).
@@ -223,6 +221,16 @@ function doLogin(req, res, password, setCookie) {
 // and would fight Range requests.
 const COMPRESSIBLE = /^(text\/|application\/(json|javascript|xml)|image\/svg)/;
 const wantsGzip = (req) => /\bgzip\b/.test(String(req.headers['accept-encoding'] || ''));
+// zlib's larger default table can be counterproductive for minified text: memLevel 5 both compresses it
+// further and lowers each stream's working memory. One policy drives buffered and streamed gzip.
+const GZIP_OPTIONS = { level: 9, memLevel: 5 };
+function appendVary(current, token) {
+    const values = (Array.isArray(current) ? current : [current ?? ''])
+        .flatMap((value) => value.split(',')).map((value) => value.trim()).filter(Boolean);
+    if (!values.some((value) => value === '*' || value.toLowerCase() === token.toLowerCase()))
+        values.push(token);
+    return values.join(', ');
+}
 // reverse-proxy an /api request to the loopback supervisor (which forwards to the live child) —
 // stream-gzipping compressible bodies (measured: the board JSON rides down at under a third).
 // `path` and `headers` optionally override routing inputs (the host gateway strips its /p/:projectId
@@ -322,16 +330,19 @@ export function proxyHttp(req, res, upstreamPort, path, headers = req.headers, u
         received.once('close', () => { if (!received.complete)
             failFromUpstream(); });
         const type = String(received.headers['content-type'] || '');
-        const skip = !wantsGzip(req) || received.headers['content-encoding'] || !COMPRESSIBLE.test(type) || type.startsWith('text/event-stream');
-        if (skip) {
-            res.writeHead(received.statusCode || 502, received.headers);
+        const eligible = !received.headers['content-encoding'] && COMPRESSIBLE.test(type) && !type.startsWith('text/event-stream');
+        const responseHeaders = eligible
+            ? { ...received.headers, vary: appendVary(received.headers.vary, 'Accept-Encoding') }
+            : received.headers;
+        if (!eligible || !wantsGzip(req)) {
+            res.writeHead(received.statusCode || 502, responseHeaders);
             received.pipe(res);
             return;
         }
-        const headers = { ...received.headers, 'content-encoding': 'gzip', vary: 'Accept-Encoding' };
+        const headers = { ...responseHeaders, 'content-encoding': 'gzip' };
         delete headers['content-length']; // streamed; the encoded length isn't knowable up front
         res.writeHead(received.statusCode || 502, headers);
-        transform = createGzip();
+        transform = createGzip(GZIP_OPTIONS);
         transform.once('error', failFromUpstream);
         received.pipe(transform).pipe(res);
     });
@@ -473,17 +484,21 @@ export function serveStatic(req, res, distDir, urlPath) {
     const type = MIME[extname(file)] || 'application/octet-stream';
     const cacheControl = /[\\/]assets[\\/]/.test(file) ? 'public, max-age=31536000, immutable' : 'no-cache';
     const raw = readFileSync(file);
-    if (wantsGzip(req) && COMPRESSIBLE.test(type)) {
+    const compressible = COMPRESSIBLE.test(type);
+    const headers = { 'Content-Type': type, 'Cache-Control': cacheControl };
+    if (compressible)
+        headers.Vary = appendVary(undefined, 'Accept-Encoding');
+    if (wantsGzip(req) && compressible) {
         const mtime = statSync(file).mtimeMs;
         let hit = gzMemo.get(file);
         if (!hit || hit.mtime !== mtime) {
-            hit = { mtime, gz: gzipSync(raw) };
+            hit = { mtime, gz: gzipSync(raw, GZIP_OPTIONS) };
             gzMemo.set(file, hit);
         }
-        res.writeHead(200, { 'Content-Type': type, 'Content-Encoding': 'gzip', Vary: 'Accept-Encoding', 'Cache-Control': cacheControl });
+        res.writeHead(200, { ...headers, 'Content-Encoding': 'gzip' });
         return res.end(hit.gz);
     }
-    res.writeHead(200, { 'Content-Type': type, 'Cache-Control': cacheControl });
+    res.writeHead(200, headers);
     res.end(raw);
 }
 function sendHtml(res, status, html) {
@@ -498,6 +513,15 @@ function sendHtml(res, status, html) {
 // installed user has no source tree for). See [[packaging]].
 export function serveDashboardLocal(opts) {
     const distDir = resolveDistDir();
-    console.log(`[dashboard] serving ${distDir}, /api → backend :${opts.apiPort}`);
-    startGateway({ host: opts.host ?? '127.0.0.1', publicPort: opts.port, upstreamPort: opts.apiPort, password: '', tls: null, distDir, label: 'dashboard', projectRoot: opts.projectRoot });
+    startGateway({
+        host: opts.host ?? '127.0.0.1',
+        publicPort: opts.port,
+        upstreamPort: opts.apiPort,
+        password: '',
+        tls: null,
+        distDir,
+        label: 'dashboard',
+        projectRoot: opts.projectRoot,
+        readyLines: [`[dashboard] serving ${distDir}, /api → backend :${opts.apiPort}`],
+    });
 }

package/node_modules/@spexcode/spec-cli/dist/graphCache.js

@@ -3,7 +3,7 @@ import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { rebasePublishedSessions } from '@spexcode/spec-core';
 import { buildBoard, spliceSessions } from './graphSnapshot.js';
-import { headSha, repoRoot, withGitAbortSignal } from '@spexcode/spec-core';
+import { headSha, repoRoot, requireGitWorkspace, withGitAbortSignal } from '@spexcode/spec-core';
 import { listSessionIds, mainBranch, mainCheckout, readPublicRecordEntry, sessionArtifactPath, sessionRecordPath } from '@spexcode/spec-core';
 import { boardThreads } from './issues.js';
 import { resolveForgeHost } from '@spexcode/spec-forge/drivers';
@@ -162,6 +162,7 @@ function sessionInputRevision() {
 }
 function boardInputRevision(board) {
     const root = repoRoot();
+    requireGitWorkspace(root);
     const session = sessionInputRevision();
     // Durable active records are the current root set; a cached ordinary row may be stale and must not replace
     // them. The one projection-only addition is explicit: listSessions republishes an archived-runtime hazard

package/node_modules/@spexcode/spec-cli/dist/graphSnapshot.js

@@ -1,4 +1,4 @@
-import { loadSpecs } from '@spexcode/spec-core';
+import { loadSpecs, requireGitWorkspace } from '@spexcode/spec-core';
 import { resolveLayout } from '@spexcode/spec-core';
 import { listSessions } from './sessions.js';
 import { driftIndex, historyIndex, repoRoot } from '@spexcode/spec-core';
@@ -12,6 +12,7 @@ import { sessionEvalProjections } from '@spexcode/spec-eval/sessioneval';
 // The application adapter is the sole reader of runtime/forge state. graph.ts only receives this result.
 export async function boardSnapshot() {
     const root = repoRoot();
+    requireGitWorkspace(root);
     const [specs, sessions] = await Promise.all([loadSpecs(), listSessions()]);
     const layout = await resolveLayout({ activeSessionIds: sessions.map((session) => session.id) });
     const nodeIds = [...new Set([

package/node_modules/@spexcode/spec-cli/dist/harness.d.ts

@@ -24,6 +24,14 @@ export type FailureSubscription = {
     close(): void;
     readonly closed: Promise<string | null>;
 };
+export type DeliveryTransportState = {
+    kind: 'reachable';
+} | {
+    kind: 'unproven';
+} | {
+    kind: 'unreachable';
+    reason: string;
+};
 export type ProcTable = Map<number, {
     ppid: number;
     comm: string;
@@ -137,10 +145,12 @@ export interface Harness {
     slashCommands(): SlashCommand[];
     liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline';
     launchReady?(current: () => HarnessLaunchReadyRecord | null, deadline: number): Promise<HarnessLaunchReadinessFence | null>;
-    leafOwnerNeedle?(rec: HarnessLivenessRecord & {
+    launchPayloadProof?: true;
+    exactNativeTargetId(rec: HarnessLivenessRecord & {
         harnessSessionId?: string | null;
     }): string | null;
     deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>;
+    deliveryTransport?(rec: HarnessDeliveryRecord): Promise<DeliveryTransportState>;
     observeTurnFailures?(rec: HarnessDeliveryRecord, onFailure: (failure: TurnFailure) => void): FailureSubscription;
     interrupt?(rec: HarnessDeliveryRecord): Promise<DispatchResult>;
     cleanupRuntime(rec: HarnessLivenessRecord): Promise<void>;
@@ -185,7 +195,7 @@ export interface Harness {
     resumeArg(rec: {
         session: string;
         harnessSessionId?: string | null;
-    }): string;
+    }, pendingLaunchPayload?: string | null): string;
 }
 export type DispatchResult = {
     ok: boolean;
@@ -193,6 +203,8 @@ export type DispatchResult = {
 };
 export type HarnessDeliveryRecord = {
     session: string;
+    stopped?: boolean;
+    archived?: boolean;
     worktreePath?: string;
     harnessSessionId?: string | null;
     runtimeDir?: string;
@@ -205,6 +217,7 @@ export type HarnessArtifacts = {
 };
 export declare const legacyRvSock: (id: string) => string;
 export declare const scopedRvSock: (id: string, dir?: string) => string;
+export declare function assertRvSockPath(id: string, dir?: string): string;
 export declare const rvSock: (id: string) => string;
 export declare function stampRvSock(id: string, dir?: string): string;
 export type ListenerProbe = 'live' | 'dead' | 'unproven';