devharness 0.9.3 → 0.9.4

package/build/block-events.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Block event stream - one JSON line per new guard block, appended to
+ * .devharness/logs/blocks.jsonl.
+ *
+ * Guards only surface on the *next* tool call, so a session doing unrelated
+ * work never learns its dev server died until it happens to call a devharness
+ * tool again. This file is the push side of that: a Claude Code Monitor can
+ * `tail -f` it and get notified the moment a block appears.
+ *
+ * Deduplicated by key - a block that keeps firing on every subsequent tool call
+ * writes one line, not one per call. The active set clears once a call gets
+ * through all guards.
+ */
+export type BlockGuard = 'port' | 'breakpoint' | 'pendingStartup' | 'bug' | 'duplicateSession';
+/**
+ * Identity and summary of a block, attached to the BlockingResponse that
+ * carries it so index.ts can log it without re-deriving the reason.
+ */
+export interface BlockEventInfo {
+    guard: BlockGuard;
+    /** Dedupe identity - same key while the same block persists. */
+    key: string;
+    /** One-line summary of what is blocked. */
+    detail: string;
+    /** The call that clears it. */
+    resolve: string;
+}
+/**
+ * Append a block event if this block is new. No-op for a block already logged.
+ */
+export declare function recordBlockEvent(info: BlockEventInfo | undefined, tool: string): Promise<void>;
+/**
+ * Forget every active block. Called when a tool call clears all guards, so a
+ * block that recurs later gets logged again.
+ */
+export declare function clearBlockEvents(): void;
+/**
+ * Test/debug helper - which blocks are currently deduped out.
+ */
+export declare function getActiveBlockKeys(): string[];
+export declare function getBlockEventFilePath(): string;
+//# sourceMappingURL=block-events.d.ts.map

package/build/block-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-events.d.ts","sourceRoot":"","sources":["../src/block-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,YAAY,GACZ,gBAAgB,GAChB,KAAK,GACL,kBAAkB,CAAC;AAEvB;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAUD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,cAAc,GAAG,SAAS,EAChC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C"}

package/build/block-events.js

@@ -0,0 +1,67 @@
+/**
+ * Block event stream - one JSON line per new guard block, appended to
+ * .devharness/logs/blocks.jsonl.
+ *
+ * Guards only surface on the *next* tool call, so a session doing unrelated
+ * work never learns its dev server died until it happens to call a devharness
+ * tool again. This file is the push side of that: a Claude Code Monitor can
+ * `tail -f` it and get notified the moment a block appears.
+ *
+ * Deduplicated by key - a block that keeps firing on every subsequent tool call
+ * writes one line, not one per call. The active set clears once a call gets
+ * through all guards.
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { getOutputPath } from './helpers/paths.js';
+// Keys currently blocking. Written once per key, cleared when a tool call
+// passes every guard.
+const activeKeys = new Set();
+function getBlockFile() {
+    return join(getOutputPath('logs'), 'blocks.jsonl');
+}
+/**
+ * Append a block event if this block is new. No-op for a block already logged.
+ */
+export async function recordBlockEvent(info, tool) {
+    if (!info)
+        return;
+    const dedupeKey = `${info.guard}:${info.key}`;
+    if (activeKeys.has(dedupeKey)) {
+        return;
+    }
+    activeKeys.add(dedupeKey);
+    const line = JSON.stringify({
+        ts: new Date().toISOString(),
+        guard: info.guard,
+        tool,
+        detail: info.detail,
+        resolve: info.resolve,
+    });
+    try {
+        const dir = getOutputPath('logs');
+        await fs.mkdir(dir, { recursive: true });
+        await fs.appendFile(getBlockFile(), line + '\n');
+    }
+    catch (error) {
+        // Never let the event stream break the block itself
+        console.error(`[BlockEvents] Failed to write block event: ${error}`);
+    }
+}
+/**
+ * Forget every active block. Called when a tool call clears all guards, so a
+ * block that recurs later gets logged again.
+ */
+export function clearBlockEvents() {
+    activeKeys.clear();
+}
+/**
+ * Test/debug helper - which blocks are currently deduped out.
+ */
+export function getActiveBlockKeys() {
+    return [...activeKeys];
+}
+export function getBlockEventFilePath() {
+    return getBlockFile();
+}
+//# sourceMappingURL=block-events.js.map

package/build/block-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-events.js","sourceRoot":"","sources":["../src/block-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAuBnD,0EAA0E;AAC1E,sBAAsB;AACtB,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;AAErC,SAAS,YAAY;IACnB,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAgC,EAChC,IAAY;IAEZ,IAAI,CAAC,IAAI;QAAE,OAAO;IAElB,MAAM,SAAS,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IAC9C,IAAI,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAE1B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI;QACJ,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oDAAoD;QACpD,OAAO,CAAC,KAAK,CAAC,8CAA8C,KAAK,EAAE,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,UAAU,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,qBAAqB;IACnC,OAAO,YAAY,EAAE,CAAC;AACxB,CAAC"}

package/build/block-events.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=block-events.test.d.ts.map

package/build/block-events.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-events.test.d.ts","sourceRoot":"","sources":["../src/block-events.test.ts"],"names":[],"mappings":""}

package/build/block-events.test.js

@@ -0,0 +1,131 @@
+/**
+ * blocks.jsonl is what a Claude Code Monitor tails, so a notification storm is
+ * the failure mode that matters: guards re-fire on every subsequent tool call,
+ * and a naive append would emit one line per blocked call instead of one per
+ * block. These cover the dedupe, the clear-on-unblocked reset, and that each
+ * guard actually attaches the info the line is built from.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { initializePaths } from './helpers/paths.js';
+import { recordBlockEvent, clearBlockEvents, getBlockEventFilePath, } from './block-events.js';
+import { checkPortFailures, checkPendingStartups, checkDuplicateSession, } from './tool-response.js';
+let workDir;
+let originalCwd;
+let originalGlobalDir;
+const portBlock = {
+    guard: 'port',
+    key: '3000',
+    detail: 'Monitored port(s) down: 3000 (web)',
+    resolve: `server({ action: 'acknowledgePort', port: 3000 })`,
+};
+function lines() {
+    const path = getBlockEventFilePath();
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, 'utf-8')
+        .split('\n')
+        .filter(l => l.trim())
+        .map(l => JSON.parse(l));
+}
+beforeEach(() => {
+    originalCwd = process.cwd();
+    workDir = mkdtempSync(join(tmpdir(), 'cdp-block-events-test-'));
+    process.chdir(workDir);
+    originalGlobalDir = process.env.CDP_TOOLS_DIR;
+    process.env.CDP_TOOLS_DIR = join(workDir, 'global');
+    initializePaths();
+    clearBlockEvents();
+});
+afterEach(() => {
+    clearBlockEvents();
+    process.chdir(originalCwd);
+    if (originalGlobalDir === undefined)
+        delete process.env.CDP_TOOLS_DIR;
+    else
+        process.env.CDP_TOOLS_DIR = originalGlobalDir;
+    initializePaths();
+    rmSync(workDir, { recursive: true, force: true });
+});
+describe('block event stream', () => {
+    it('writes one line per block, not per blocked call', async () => {
+        await recordBlockEvent(portBlock, 'navigate');
+        await recordBlockEvent(portBlock, 'screenshot');
+        await recordBlockEvent(portBlock, 'content');
+        expect(lines()).toHaveLength(1);
+        expect(lines()[0]).toMatchObject({
+            guard: 'port',
+            tool: 'navigate',
+            detail: 'Monitored port(s) down: 3000 (web)',
+        });
+    });
+    it('logs the same block again after a call clears every guard', async () => {
+        await recordBlockEvent(portBlock, 'navigate');
+        clearBlockEvents();
+        await recordBlockEvent(portBlock, 'navigate');
+        expect(lines()).toHaveLength(2);
+    });
+    it('treats a different block as a new event while the first is still active', async () => {
+        await recordBlockEvent(portBlock, 'navigate');
+        await recordBlockEvent({ ...portBlock, key: '3000,5173', detail: 'Monitored port(s) down: 3000, 5173' }, 'navigate');
+        expect(lines()).toHaveLength(2);
+    });
+    it('separates guards that happen to share a key', async () => {
+        await recordBlockEvent({ ...portBlock, guard: 'port', key: 'web' }, 'navigate');
+        await recordBlockEvent({ ...portBlock, guard: 'pendingStartup', key: 'web' }, 'navigate');
+        expect(lines().map(l => l.guard)).toEqual(['port', 'pendingStartup']);
+    });
+    it('does nothing when a guard supplies no block info', async () => {
+        await recordBlockEvent(undefined, 'navigate');
+        expect(lines()).toHaveLength(0);
+    });
+});
+describe('guards attach block info', () => {
+    it('port failure', () => {
+        const failed = [
+            { port: 3000, level: 'block', failedAt: new Date('2026-01-01T00:00:00Z'), description: 'web' },
+        ];
+        const result = checkPortFailures(failed, 'navigate');
+        expect(result.blocked).toBe(true);
+        if (!result.blocked)
+            return;
+        expect(result.block?.guard).toBe('port');
+        expect(result.block?.key).toBe('3000');
+        expect(result.block?.resolve).toContain('acknowledgePort');
+    });
+    it('pending startup failure', () => {
+        const failures = [
+            { serverId: 'web', reason: 'died', startedAt: new Date('2026-01-01T00:00:00Z') },
+        ];
+        const result = checkPendingStartups(failures, 'navigate');
+        expect(result.blocked).toBe(true);
+        if (!result.blocked)
+            return;
+        expect(result.block?.guard).toBe('pendingStartup');
+        expect(result.block?.detail).toContain('died before port detected');
+        expect(result.block?.resolve).toContain('acknowledgeStartup');
+    });
+    it('duplicate session, from both sides', () => {
+        const base = {
+            sessionId: 'abc-123',
+            shortId: 'abc',
+            allPids: [10, 20],
+            allPpids: [100, 200],
+        };
+        const original = checkDuplicateSession({ ...base, currentPid: 10, currentPpid: 100 }, 'navigate');
+        expect(original.blocked).toBe(true);
+        if (original.blocked) {
+            expect(original.block?.key).toBe('original:abc-123');
+            expect(original.block?.resolve).toBe('kill 200');
+        }
+        const duplicate = checkDuplicateSession({ ...base, currentPid: 20, currentPpid: 200 }, 'navigate');
+        expect(duplicate.blocked).toBe(true);
+        if (duplicate.blocked) {
+            expect(duplicate.block?.key).toBe('duplicate:abc-123');
+            expect(duplicate.block?.resolve).toContain('--fork-session');
+        }
+    });
+});
+//# sourceMappingURL=block-events.test.js.map

package/build/block-events.test.js.map

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

package/build/index.js

@@ -55,6 +55,8 @@ import { ServerManager, detectAutoRestartCommand } from './server-manager.js';
 import { configManager } from './config.js';
 import { ToolError } from './tool-error.js';
 import { checkPortFailures, checkBreakpointPause, checkBugBlocking, checkPendingStartups, checkDuplicateSession, prependToResponse, appendToResponse, buildStatusSuffix } from './tool-response.js';
+import { recordBlockEvent, clearBlockEvents } from './block-events.js';
+import { createStartupGate } from './startup-gate.js';
 import { createSuccessResponse, createErrorResponse } from './messages.js';
 import { setChromeLauncher } from './error-helpers.js';
 import { createServer } from 'net';
@@ -83,6 +85,11 @@ const SERVER_VERSION = (() => {
         return '0.0.0';
     }
 })();
+/** Tool calls wait on this until serverManager.initialize() has restored state. */
+const startupGate = createStartupGate({
+    timeoutMs: 30_000,
+    onTimeout: (ms) => console.error(`[devharness] Startup recovery still running after ${ms}ms - serving tools anyway`),
+});
 /**
  * Which build is actually answering, so a session can tell whether the code it
  * is calling is the code it just compiled.
@@ -1356,6 +1363,15 @@ function registerToolHandlers(server) {
                 isError: true
             };
         }
+        // The transport starts serving before serverManager.initialize() has
+        // restored state, so a call landing in that window sees an empty world: a
+        // dead server's guard silently passes, and `acknowledgeStartup` in there
+        // acknowledges nothing and reverts as soon as recovery lands. Wait for it.
+        // `config` is exempt: it reads no server state, and `config restart` is the
+        // escape hatch you want available precisely when recovery is what's stuck.
+        if (toolName !== 'config') {
+            await startupGate.wait();
+        }
         // Check for tool dependency conflicts (blocks ALL tools except config)
         if (toolName !== 'config' && configManager.hasDependencyConflicts()) {
             const conflicts = configManager.getDependencyConflicts();
@@ -1399,31 +1415,38 @@ Edit ${configPath} to resolve, then restart the MCP server.`,
         const failedPorts = portMonitor.getFailedPorts();
         const portCheck = checkPortFailures(failedPorts, toolName);
         if (portCheck.blocked) {
+            await recordBlockEvent(portCheck.block, toolName);
             return portCheck.response;
         }
         // Check for breakpoint pauses (block tools until acknowledged or resumed)
         const allConnections = connectionManager.getAllConnections();
         const breakpointCheck = checkBreakpointPause(allConnections, toolName, (port) => serverManager.getPendingRestartByInspectorPort(port), validation.data?.action);
         if (breakpointCheck.blocked) {
+            await recordBlockEvent(breakpointCheck.block, toolName);
             return breakpointCheck.response;
         }
         // Check for pending startup failures (block tools until acknowledged)
         const pendingStartupFailures = serverManager.getPendingStartupFailures();
         const pendingStartupCheck = checkPendingStartups(pendingStartupFailures, toolName);
         if (pendingStartupCheck.blocked) {
+            await recordBlockEvent(pendingStartupCheck.block, toolName);
             return pendingStartupCheck.response;
         }
         // Check for blocking bugs from recordings
         const bugCheck = await checkBugBlocking(toolName, validation.data);
         if (bugCheck.blocked) {
+            await recordBlockEvent(bugCheck.block, toolName);
             return bugCheck.response;
         }
         // Check for duplicate session (multiple MCPs for same Claude session)
         const duplicateInfo = getDuplicateSessionInfo();
         const duplicateCheck = checkDuplicateSession(duplicateInfo, toolName);
         if (duplicateCheck.blocked) {
+            await recordBlockEvent(duplicateCheck.block, toolName);
             return duplicateCheck.response;
         }
+        // Every guard passed - a block that recurs later is a new event
+        clearBlockEvents();
         // Pass validated data to handler
         try {
             const result = await tool.handler(validation.data, extra?.signal);
@@ -1815,8 +1838,16 @@ async function main() {
     // session that has not registered yet is invisible to that question.
     serverClaims.collectDeadSessions();
     await serverClaims.registerSession(process.cwd());
-    // Initialize server manager - recover running servers and start auto-run servers
-    const serverInitResult = await serverManager.initialize();
+    // Initialize server manager - recover running servers and start auto-run servers.
+    // Tool calls queue behind this (see waitForStartupRecovery); release the gate
+    // even if recovery throws, or every later call would wait out the timeout.
+    let serverInitResult;
+    try {
+        serverInitResult = await serverManager.initialize();
+    }
+    finally {
+        startupGate.markComplete();
+    }
     if (serverInitResult.recovered.length > 0) {
         console.error(`[devharness] Recovered ${serverInitResult.recovered.length} running server(s): ${serverInitResult.recovered.join(', ')}`);
     }