@xdelivered/emberflow 0.2.0

package/dist/bin/init.js

@@ -0,0 +1,241 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, copyFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectHarnesses, resolveSkillDirs } from './skillTargets.js';
+const MCP_SNIPPET = {
+    mcpServers: {
+        emberflow: { command: 'npx', args: ['emberflow', 'mcp'] },
+    },
+};
+function copySkillsRecursive(src, dest, log) {
+    mkdirSync(dest, { recursive: true });
+    for (const entry of readdirSync(src)) {
+        const srcPath = join(src, entry);
+        const destPath = join(dest, entry);
+        if (statSync(srcPath).isDirectory()) {
+            copySkillsRecursive(srcPath, destPath, log);
+        }
+        else if (!existsSync(destPath)) {
+            copyFileSync(srcPath, destPath);
+            log.push(destPath);
+        }
+    }
+}
+const JS_CONFIG_CONTENT = "import { defineConfig } from '@xdelivered/emberflow';\n\n" +
+    'export default defineConfig({\n' +
+    "  language: 'javascript',\n" +
+    '  // Anchor only: this path is never created and holds no files. It just tells\n' +
+    '  // Emberflow where your project root is — operations always live in the\n' +
+    '  // SIBLING apis/ tree next to it:\n' +
+    '  //   emberflow/apis/<api>/<folder…>/<op>.json — each op id = its path under apis/.\n' +
+    "  flowsDir: 'emberflow/flows',\n" +
+    '  // Author your nodes here: registry.register(definition, async (ctx) => output).\n' +
+    "  /** @param {import('@xdelivered/emberflow').NodeRegistry} registry */\n" +
+    '  registerNodes(registry) {\n' +
+    '    /* register your nodes */\n' +
+    '  },\n' +
+    '});\n';
+const TS_CONFIG_CONTENT = "import { defineConfig } from '@xdelivered/emberflow';\n" +
+    "import type { NodeRegistry } from '@xdelivered/emberflow';\n\n" +
+    'export default defineConfig({\n' +
+    "  language: 'typescript',\n" +
+    '  // Anchor only: this path is never created and holds no files. It just tells\n' +
+    '  // Emberflow where your project root is — operations always live in the\n' +
+    '  // SIBLING apis/ tree next to it:\n' +
+    '  //   emberflow/apis/<api>/<folder…>/<op>.json — each op id = its path under apis/.\n' +
+    "  flowsDir: 'emberflow/flows',\n" +
+    '  // Author your nodes here: registry.register(definition, async (ctx) => output).\n' +
+    '  registerNodes(registry: NodeRegistry) {\n' +
+    '    /* register your nodes */\n' +
+    '  },\n' +
+    '});\n';
+// Minimal — the consumer only needs their config + nodes typechecked, not a full
+// project tsconfig. `noEmit` because emberflow.config.ts runs via tsx, never tsc.
+const TSCONFIG_CONTENT = JSON.stringify({
+    compilerOptions: {
+        target: 'es2022',
+        module: 'nodenext',
+        moduleResolution: 'nodenext',
+        strict: true,
+        skipLibCheck: true,
+        esModuleInterop: true,
+        resolveJsonModule: true,
+        noEmit: true,
+    },
+    include: ['emberflow.config.ts', 'emberflow/**/*'],
+}, null, 2) + '\n';
+/** Whether `tsx` resolves from the project's own node_modules (peer dep — optional).
+ *  Exported so bin/commands.ts can reuse it when deciding whether `init --ts` can
+ *  launch dev immediately after scaffolding, or must defer to the user. */
+export function tsxResolvable(cwd) {
+    try {
+        createRequire(join(cwd, 'package.json')).resolve('tsx');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// The example HTTP operation: GET /hello, Input({params,query,body,headers}) →
+// Response({status,body}). Its `id` equals its path under the apis dir.
+const HELLO_OP = {
+    id: 'default/hello',
+    name: 'Hello',
+    version: 1,
+    http: { method: 'GET', path: '/hello' },
+    nodes: [
+        {
+            id: 'input',
+            type: 'Input',
+            label: 'Request',
+            position: { x: 0, y: 0 },
+            config: {
+                fields: [
+                    { name: 'params', type: 'object' },
+                    { name: 'query', type: 'object' },
+                    { name: 'body', type: 'object' },
+                    { name: 'headers', type: 'object' },
+                ],
+                defaults: { query: { name: 'world' } },
+            },
+        },
+        {
+            id: 'response',
+            type: 'Response',
+            label: 'Response',
+            position: { x: 300, y: 0 },
+            config: {},
+            inputMap: {
+                body: { sourceNodeId: 'input', sourceField: 'query' },
+            },
+        },
+    ],
+    edges: [{ id: 'e0', source: 'input', target: 'response', targetHandle: 'body' }],
+    createdAt: '2026-07-05T00:00:00Z',
+    updatedAt: '2026-07-05T00:00:00Z',
+};
+const HELLO_OP_SCENARIOS = [{ id: 's-hi', name: 'greet', input: { query: { name: 'Ember' } } }];
+// Emberflow infra that is machine-local, generated, or secret — never committed.
+// NOTE: emberflow.config.mjs and emberflow/ (apis + scenarios) are deliberately
+// NOT here — those are the value and SHOULD be checked in.
+const GITIGNORE_HEADER = '# Emberflow (local infra — emberflow.config.mjs and emberflow/apis ARE committed)';
+const GITIGNORE_LINES = [
+    'node_modules/',
+    'studio-dist/',
+    'emberflow.secrets.json',
+    'emberflow.environments.json',
+];
+function writeFileIfAbsent(path, content, log) {
+    if (existsSync(path))
+        return;
+    writeFileSync(path, content);
+    log.push(path);
+}
+export async function runInit(cwd, opts) {
+    const written = [];
+    const language = opts?.language ?? 'javascript';
+    // Refuse to scaffold a SECOND config in another extension: the loader probes
+    // .mjs before .js before .ts, so a new config of a different flavor would sit
+    // dead on disk while init claims success. Language switching is a manual
+    // migration (rename/port the existing config), not a re-init.
+    const existingOther = ['emberflow.config.mjs', 'emberflow.config.js', 'emberflow.config.ts']
+        .filter((name) => (language === 'typescript' ? !name.endsWith('.ts') : name.endsWith('.ts')))
+        .find((name) => existsSync(join(cwd, name)));
+    if (existingOther) {
+        console.error(`[emberflow] this project already has ${existingOther} — refusing to scaffold a ${language} config alongside it. ` +
+            `To switch languages, port ${existingOther} manually and delete it.`);
+        return 1;
+    }
+    if (language === 'typescript') {
+        writeFileIfAbsent(join(cwd, 'emberflow.config.ts'), TS_CONFIG_CONTENT, written);
+        writeFileIfAbsent(join(cwd, 'tsconfig.json'), TSCONFIG_CONTENT, written);
+        if (!tsxResolvable(cwd)) {
+            console.log('[emberflow] TypeScript config needs tsx to run this project.');
+            console.log('  npm i -D tsx typescript');
+        }
+    }
+    else {
+        writeFileIfAbsent(join(cwd, 'emberflow.config.mjs'), JS_CONFIG_CONTENT, written);
+    }
+    // Scaffold the apis/ tree with an example HTTP operation so the API host has a
+    // routed endpoint the moment the project boots. The operation's `id`
+    // ("default/hello") equals its path under the apis dir.
+    const apisDefaultDir = join(cwd, 'emberflow', 'apis', 'default');
+    const apisDefaultDirExisted = existsSync(apisDefaultDir);
+    mkdirSync(apisDefaultDir, { recursive: true });
+    if (!apisDefaultDirExisted)
+        written.push(apisDefaultDir + '/');
+    writeFileIfAbsent(join(apisDefaultDir, 'hello.json'), JSON.stringify(HELLO_OP, null, 2) + '\n', written);
+    writeFileIfAbsent(join(apisDefaultDir, 'hello.scenarios.json'), JSON.stringify(HELLO_OP_SCENARIOS, null, 2) + '\n', written);
+    const pkgPath = join(cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        let pkgDirty = false;
+        if (!pkg.scripts)
+            pkg.scripts = {};
+        if (!pkg.scripts.emberflow) {
+            pkg.scripts.emberflow = 'emberflow dev';
+            pkgDirty = true;
+        }
+        // A TypeScript project MUST load as ESM: `emberflow` is an ESM-only package,
+        // and under a CommonJS package.json tsx transpiles emberflow.config.ts to CJS
+        // and then require()s the ESM `emberflow` — which Node rejects with
+        // ERR_REQUIRE_CYCLE_MODULE. Stamp "type":"module" when the project hasn't
+        // declared one. (JS scaffolds a .mjs config, which is ESM regardless.)
+        if (language === 'typescript') {
+            if (pkg.type === undefined) {
+                pkg.type = 'module';
+                pkgDirty = true;
+                console.warn('[emberflow] set "type": "module" in package.json — required for emberflow.config.ts; ' +
+                    'if this project has existing CommonJS .js files, audit them (they are now parsed as ESM)');
+            }
+            else if (pkg.type !== 'module') {
+                console.warn(`[emberflow] warning: package.json has "type": "${pkg.type}", but a TypeScript ` +
+                    'emberflow.config.ts must load as ESM. Set "type": "module" or the runner will fail ' +
+                    'to load your config.');
+            }
+        }
+        if (pkgDirty) {
+            writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+            written.push(pkgPath);
+        }
+    }
+    const gitignorePath = join(cwd, '.gitignore');
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
+    const missing = GITIGNORE_LINES.filter((line) => !existing.includes(line));
+    if (missing.length > 0) {
+        // Create .gitignore if absent, or append only the lines not already present.
+        const header = existing.includes(GITIGNORE_HEADER) ? '' : `${GITIGNORE_HEADER}\n`;
+        const sep = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+        const block = (existing.length > 0 ? '\n' : '') + header + missing.join('\n') + '\n';
+        writeFileSync(gitignorePath, existing + sep + block);
+        written.push(gitignorePath);
+    }
+    for (const path of written) {
+        console.log(`[emberflow] created ${path}`);
+    }
+    const skillsOpt = opts?.skills === undefined ? { scope: 'repo', home: homedir() } : opts.skills;
+    if (skillsOpt !== false) {
+        const pkgRoot = opts?.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..');
+        const skillsSrc = join(pkgRoot, 'templates', 'skills');
+        if (existsSync(skillsSrc)) {
+            const presence = detectHarnesses(cwd, skillsOpt.home);
+            const skillDirs = resolveSkillDirs(presence, skillsOpt.scope, cwd, skillsOpt.home);
+            const skillsWritten = [];
+            for (const dir of skillDirs) {
+                copySkillsRecursive(skillsSrc, dir, skillsWritten);
+            }
+            for (const path of skillsWritten) {
+                console.log(`[emberflow] created ${path}`);
+            }
+        }
+        console.log('');
+        console.log('[emberflow] To let your agent drive Emberflow directly, register the emberflow MCP server:');
+        console.log("  - Claude Code: add the snippet below to .mcp.json at your project root.");
+        console.log("  - Other agents: add it to your agent's MCP server config (name/location varies by tool).");
+        console.log(JSON.stringify(MCP_SNIPPET, null, 2));
+    }
+    return 0;
+}

package/dist/bin/runtime.d.mts

@@ -0,0 +1,39 @@
+/** The emberflow.config.* basename present in `dir`, or undefined. Local probe
+ *  of the same basenames server/projectConfig.ts#configPathFor checks. */
+export function configBasenameFor(dir: any, fsExists?: typeof existsSync): string | undefined;
+/** Resolve the project directory the same way the commands do, in the binding
+ *  order EMBERFLOW_PROJECT → --project → cwd. Values are resolved against cwd. */
+export function resolveProjectDir(argv: any, env: any, cwd: any): any;
+/**
+ * Decide how to run.
+ *
+ * @param packageRoot absolute path to the package root (dir above bin/).
+ * @param projectDir  resolved project dir (see resolveProjectDir).
+ * @param env         process.env-shaped object.
+ * @param fsExists    existsSync-shaped probe (injectable for tests).
+ *
+ * Returns:
+ *   needsTsx    – register tsx and spawn the runner under tsx.
+ *   runnerMode  – 'node' (spawn `node dist/server/*.js`) or 'tsx' (spawn tsx source).
+ *   useDist     – import the compiled `dist/bin/commands.js` rather than source.
+ *   sourceMode  – repo checkout (dev loop) rather than an installed package.
+ *   configBasename / reason – for the EMBERFLOW_DEBUG_RUNTIME trace.
+ */
+export function decideRuntime({ packageRoot, projectDir, env, fsExists }: {
+    packageRoot: any;
+    projectDir: any;
+    env?: {} | undefined;
+    fsExists?: typeof existsSync | undefined;
+}): {
+    needsTsx: boolean;
+    runnerMode: string;
+    useDist: boolean;
+    sourceMode: boolean;
+    hasDist: boolean;
+    configBasename: string | undefined;
+    reason: string;
+};
+/** Actionable message shown when a `.ts` config / source mode needs tsx but it
+ *  isn't installed. Exported so both the bin and its tests reference one string. */
+export const TSX_MISSING_MESSAGE: string;
+import { existsSync } from 'node:fs';

package/dist/bin/runtime.mjs

@@ -0,0 +1,96 @@
+// Runtime-mode decision for the Emberflow bin.
+//
+// The bin must decide — BEFORE loading any TypeScript — whether this invocation
+// needs the tsx loader (source checkout, a `.ts` project config, or an explicit
+// override) or can run on plain Node against the compiled `dist/`. A JS consumer
+// with a `.mjs`/`.js` config runs entirely on `node` with NO tsx: no tsx child
+// IPC, so the agent in-process CLI works inside the codex sandbox.
+//
+// This module is plain JS on purpose — it imports NO server/TS code, so probing
+// it never triggers the tsx requirement it is trying to decide about. Everything
+// here is pure and injectable (fsExists/env) so the decision matrix is unit
+// testable without touching a real filesystem.
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+// Mirrors server/projectConfig.ts CONFIG_BASENAMES. Kept as a tiny local copy
+// (not imported) because that module is TypeScript and pulls in server code.
+const CONFIG_BASENAMES = ['emberflow.config.mjs', 'emberflow.config.js', 'emberflow.config.ts'];
+/** Actionable message shown when a `.ts` config / source mode needs tsx but it
+ *  isn't installed. Exported so both the bin and its tests reference one string. */
+export const TSX_MISSING_MESSAGE = '[emberflow] This project needs tsx to run, but tsx is not installed.\n' +
+    '  Either a TypeScript config (emberflow.config.ts) or source mode requires the tsx loader.\n' +
+    '  Fix: install it as a dev dependency —  npm i -D tsx\n' +
+    '  Or:  rename emberflow.config.ts to emberflow.config.mjs (plain JS) so Emberflow runs on plain Node.';
+/** The emberflow.config.* basename present in `dir`, or undefined. Local probe
+ *  of the same basenames server/projectConfig.ts#configPathFor checks. */
+export function configBasenameFor(dir, fsExists = existsSync) {
+    const root = resolve(dir);
+    return CONFIG_BASENAMES.find((b) => fsExists(join(root, b)));
+}
+/** Resolve the project directory the same way the commands do, in the binding
+ *  order EMBERFLOW_PROJECT → --project → cwd. Values are resolved against cwd. */
+export function resolveProjectDir(argv, env, cwd) {
+    const fromEnv = env.EMBERFLOW_PROJECT;
+    if (fromEnv)
+        return isAbsolute(fromEnv) ? fromEnv : resolve(cwd, fromEnv);
+    const i = argv.indexOf('--project');
+    if (i !== -1 && argv[i + 1])
+        return resolve(cwd, argv[i + 1]);
+    return cwd;
+}
+/**
+ * Decide how to run.
+ *
+ * @param packageRoot absolute path to the package root (dir above bin/).
+ * @param projectDir  resolved project dir (see resolveProjectDir).
+ * @param env         process.env-shaped object.
+ * @param fsExists    existsSync-shaped probe (injectable for tests).
+ *
+ * Returns:
+ *   needsTsx    – register tsx and spawn the runner under tsx.
+ *   runnerMode  – 'node' (spawn `node dist/server/*.js`) or 'tsx' (spawn tsx source).
+ *   useDist     – import the compiled `dist/bin/commands.js` rather than source.
+ *   sourceMode  – repo checkout (dev loop) rather than an installed package.
+ *   configBasename / reason – for the EMBERFLOW_DEBUG_RUNTIME trace.
+ */
+export function decideRuntime({ packageRoot, projectDir, env = {}, fsExists = existsSync }) {
+    const hasDist = fsExists(join(packageRoot, 'dist'));
+    const hasSrc = fsExists(join(packageRoot, 'src'));
+    const underNodeModules = packageRoot.split(sep).includes('node_modules');
+    // source-mode = repo checkout, where we always run the TypeScript sources under
+    // tsx (the dev loop). `dist/` may EXIST in the repo after `build:lib`, so its
+    // presence can't be the signal. Heuristic: src/ exists AND we're not installed
+    // under node_modules. EMBERFLOW_SOURCE is an explicit escape hatch either way.
+    let sourceMode;
+    if (env.EMBERFLOW_SOURCE === '1')
+        sourceMode = true;
+    else if (env.EMBERFLOW_SOURCE === '0')
+        sourceMode = false;
+    else
+        sourceMode = hasSrc && !underNodeModules;
+    const configBasename = configBasenameFor(projectDir, fsExists);
+    const tsConfig = configBasename?.endsWith('.ts') ?? false;
+    const forced = env.EMBERFLOW_FORCE_TSX === '1';
+    // Import compiled commands only when we have a dist AND we're not in the source
+    // dev loop. Otherwise fall back to the TypeScript source (which requires tsx —
+    // and needsTsx is already true whenever sourceMode is).
+    const useDist = hasDist && !sourceMode;
+    // INVARIANT: importing TypeScript source requires tsx. When there is no dist
+    // to fall back on (`!useDist`), the launcher will import ./commands.ts, so tsx
+    // is required even if nothing else demanded it — otherwise plain node dies
+    // with a cryptic ERR_UNKNOWN_FILE_EXTENSION instead of TSX_MISSING_MESSAGE.
+    const needsTsx = sourceMode || forced || tsConfig || !useDist;
+    // A node-mode runner needs the compiled server; if there's no dist we can't run
+    // plain node, so fall back to tsx even when nothing else demanded it.
+    const runnerMode = !needsTsx && hasDist ? 'node' : 'tsx';
+    const reason = sourceMode
+        ? 'source-mode (repo checkout)'
+        : forced
+            ? 'EMBERFLOW_FORCE_TSX=1'
+            : tsConfig
+                ? `ts-config (${configBasename})`
+                : runnerMode === 'node'
+                    ? 'js-consumer (plain node)'
+                    : 'no-dist fallback';
+    return { needsTsx, runnerMode, useDist, sourceMode, hasDist, configBasename, reason };
+}

package/dist/bin/skillTargets.d.ts

@@ -0,0 +1,13 @@
+export type Harness = 'claude' | 'codex';
+export interface HarnessPresence {
+    claude: boolean;
+    codex: boolean;
+}
+/** Detect which harnesses the project/user uses: a harness counts as present if
+ *  its repo dir (<cwd>/.claude or /.codex) OR its home dir (<home>/.claude or /.codex) exists. */
+export declare function detectHarnesses(cwd: string, home: string): HarnessPresence;
+/** The skills destination dirs to install into. For each PRESENT harness, choose
+ *  the repo root (<cwd>/.<harness>/skills) when scope='repo', else the home root
+ *  (<home>/.<harness>/skills). If NEITHER harness is present, default to Claude Code
+ *  at the chosen scope (so a fresh project still gets skills). Returns absolute dirs. */
+export declare function resolveSkillDirs(presence: HarnessPresence, scope: 'repo' | 'global', cwd: string, home: string): string[];

package/dist/bin/skillTargets.js

@@ -0,0 +1,22 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const HARNESSES = ['claude', 'codex'];
+/** Detect which harnesses the project/user uses: a harness counts as present if
+ *  its repo dir (<cwd>/.claude or /.codex) OR its home dir (<home>/.claude or /.codex) exists. */
+export function detectHarnesses(cwd, home) {
+    const presence = {};
+    for (const h of HARNESSES) {
+        presence[h] = existsSync(join(cwd, `.${h}`)) || existsSync(join(home, `.${h}`));
+    }
+    return presence;
+}
+/** The skills destination dirs to install into. For each PRESENT harness, choose
+ *  the repo root (<cwd>/.<harness>/skills) when scope='repo', else the home root
+ *  (<home>/.<harness>/skills). If NEITHER harness is present, default to Claude Code
+ *  at the chosen scope (so a fresh project still gets skills). Returns absolute dirs. */
+export function resolveSkillDirs(presence, scope, cwd, home) {
+    const root = scope === 'repo' ? cwd : home;
+    const present = HARNESSES.filter((h) => presence[h]);
+    const targets = present.length > 0 ? present : ['claude'];
+    return targets.map((h) => join(root, `.${h}`, 'skills'));
+}

package/dist/server/agents/claudeAdapter.d.ts

@@ -0,0 +1,8 @@
+import type { SpawnedAgent } from './codexAdapter.js';
+export interface ClaudeOptions {
+    model?: string;
+    bin?: string;
+    /** Grace period (ms) between SIGTERM and the SIGKILL escalation in cancel(). Test hook. */
+    killGraceMs?: number;
+}
+export declare function spawnClaude(prompt: string, projectDir: string, opts?: ClaudeOptions): SpawnedAgent;

package/dist/server/agents/claudeAdapter.js

@@ -0,0 +1,190 @@
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+import { parseClaudeLine } from './claudeParse.js';
+import { modelRejectionHint } from './modelRejectionHint.js';
+const STDERR_TAIL_BYTES = 2048;
+export function spawnClaude(prompt, projectDir, opts = {}) {
+    const bin = opts.bin ?? 'claude';
+    const args = [
+        '-p',
+        prompt,
+        '--output-format',
+        'stream-json',
+        '--verbose',
+        // Never ask for per-call approval — the studio runs claude non-interactively
+        // (-p + SSE panel), so an approval prompt has no one to answer it and the
+        // command simply fails ("This command requires approval"), which broke even
+        // our own CLI calls (list-environments). Mirrors the codex adapter's
+        // never-ask contract; the --add-dir working-directory sandbox still fences
+        // file reads/edits to the project.
+        '--permission-mode',
+        'bypassPermissions',
+        '--add-dir',
+        projectDir,
+        ...(opts.model ? ['--model', opts.model] : []),
+    ];
+    // detached: give claude its own process group so cancel() can tree-kill any
+    // subprocesses it spawns, not just the top-level process.
+    // stdio ['ignore','pipe','pipe'] → stdin is null, stdout/stderr are Readable.
+    const child = bin.endsWith('.mjs')
+        ? spawn(process.execPath, [bin, ...args], { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], detached: true })
+        : spawn(bin, args, { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+    // Buffer only the last ~2KB of stderr — non-fatal in general, but useful as
+    // a diagnostic tail when the process dies without a terminal event (see
+    // maybeFinalize below).
+    let stderrTail = '';
+    child.stderr.on('data', (chunk) => {
+        stderrTail = (stderrTail + chunk.toString('utf8')).slice(-STDERR_TAIL_BYTES);
+    });
+    const queue = [];
+    const resolvers = [];
+    let done = false;
+    let sawTerminal = false;
+    function push(event) {
+        queue.push(event);
+        const resolve = resolvers.shift();
+        if (resolve)
+            resolve();
+    }
+    function finish() {
+        done = true;
+        while (resolvers.length) {
+            const resolve = resolvers.shift();
+            if (resolve)
+                resolve();
+        }
+    }
+    // Tracks in-flight Bash commands by their tool_use id, so that when the
+    // matching tool_result (a separate 'user' stream-json line) arrives we can
+    // recover the original command text — the tool_result line only carries the
+    // id + output, not the command. AgentConsole dedups an in_progress command
+    // event with a later completed one by matching `command` text, so the
+    // completed event we emit here must reuse the same text.
+    const pendingCommands = new Map();
+    const rl = readline.createInterface({ input: child.stdout });
+    rl.on('line', (line) => {
+        for (const event of parseClaudeLine(line)) {
+            if (event.type === 'done' || event.type === 'error')
+                sawTerminal = true;
+            if (event.type === 'command' && event.commandStatus === 'in_progress' && event.toolUseId && event.command) {
+                pendingCommands.set(event.toolUseId, event.command);
+                push(event);
+                continue;
+            }
+            if (event.type === 'command' && event.commandStatus !== 'in_progress' && event.toolUseId) {
+                // A tool_result — only surface it if it corresponds to a Bash command
+                // we're tracking; skip gracefully otherwise (e.g. a non-Bash tool).
+                const command = pendingCommands.get(event.toolUseId);
+                if (!command)
+                    continue;
+                pendingCommands.delete(event.toolUseId);
+                push({ ...event, command });
+                continue;
+            }
+            push(event);
+        }
+    });
+    // Finalize only once BOTH the stdout stream is fully drained (readline 'close')
+    // AND the process has exited ('close', which fires after all stdio is flushed —
+    // unlike 'exit', which can fire while trailing stdout lines are still buffered).
+    let rlClosed = false;
+    let procClosed = false;
+    let exitCode = null;
+    let escalateTimer;
+    function clearEscalation() {
+        if (escalateTimer) {
+            clearTimeout(escalateTimer);
+            escalateTimer = undefined;
+        }
+    }
+    function maybeFinalize() {
+        if (!rlClosed || !procClosed)
+            return;
+        clearEscalation();
+        if (!sawTerminal) {
+            if (exitCode === 0) {
+                // Clean exit but the model never emitted a result event — synthesize a done.
+                push({ type: 'done' });
+            }
+            else {
+                const hint = modelRejectionHint('claude', stderrTail);
+                const text = hint ? `claude exited with code ${exitCode} (${hint})` : `claude exited with code ${exitCode}`;
+                push({ type: 'error', text });
+            }
+            sawTerminal = true;
+        }
+        finish();
+    }
+    rl.on('close', () => {
+        rlClosed = true;
+        maybeFinalize();
+    });
+    child.on('close', (code) => {
+        procClosed = true;
+        exitCode = code;
+        maybeFinalize();
+    });
+    // A failed spawn (missing binary, bad EMBERFLOW_*_BIN, permissions, ...) emits
+    // an 'error' event on the child instead of ever exiting/closing normally. Left
+    // unhandled, Node rethrows it and crashes the whole runner process — so we
+    // must handle it and finalize the stream ourselves. 'close' still fires after
+    // a spawn error (with code null), so guard against double-finalizing there.
+    let spawnFailed = false;
+    child.on('error', (err) => {
+        if (spawnFailed)
+            return;
+        spawnFailed = true;
+        clearEscalation();
+        push({ type: 'error', text: `failed to start claude: ${err.message}` });
+        sawTerminal = true;
+        rlClosed = true;
+        procClosed = true;
+        finish();
+    });
+    async function* generate() {
+        while (true) {
+            if (queue.length > 0) {
+                yield queue.shift();
+                continue;
+            }
+            if (done)
+                return;
+            await new Promise((resolve) => resolvers.push(resolve));
+        }
+    }
+    // Kill the whole process group (negative pid) so claude's own subprocesses die
+    // too; fall back to a plain kill if the group signal fails (e.g. already gone
+    // or no group). Used by both the initial SIGTERM and the SIGKILL escalation.
+    function killGroup(signal) {
+        try {
+            if (child.pid != null) {
+                process.kill(-child.pid, signal);
+                return;
+            }
+        }
+        catch {
+            // group kill failed — fall through to a direct kill
+        }
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // process already gone — nothing to do
+        }
+    }
+    return {
+        events: { [Symbol.asyncIterator]: generate },
+        cancel() {
+            killGroup('SIGTERM');
+            // If the process (or a stubborn grandchild/MCP server) ignores SIGTERM,
+            // escalate to SIGKILL after a grace period so a hung agent can't
+            // permanently lock the run slot. Cleared once close/error finalizes.
+            clearEscalation();
+            escalateTimer = setTimeout(() => {
+                escalateTimer = undefined;
+                killGroup('SIGKILL');
+            }, opts.killGraceMs ?? 3000);
+            escalateTimer.unref?.();
+        },
+    };
+}

package/dist/server/agents/claudeParse.d.ts

@@ -0,0 +1,2 @@
+import type { AgentEvent } from './types.js';
+export declare function parseClaudeLine(line: string): AgentEvent[];