@xdelivered/emberflow 0.2.0 → 0.4.0

package/dist/server/agents/detect.js

@@ -1,11 +1,29 @@
 import { spawnSync } from 'node:child_process';
-const CANDIDATES = ['codex', 'claude'];
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 const VERSION_RE = /\d+\.\d+\.\d+/;
 /**
- * Real PATH probe: runs `<bin> --version` and parses the first semver-ish
- * token out of stdout. Returns `undefined` when the binary isn't present/
- * runnable (spawn error, timeout, or nonzero exit); `null` version when it
- * ran but produced no parseable version string.
+ * Where each agent CLI may live, beyond whatever PATH resolves. PATH shims can
+ * pin an OLD version (e.g. a superset-managed ~/.superset/bin/codex frozen at
+ * a release the API no longer accepts) while a newer binary sits elsewhere —
+ * so we probe every known location and pick the NEWEST, never just the first.
+ */
+const CANDIDATE_BINS = {
+    codex: [
+        'codex', // PATH resolution (may be a pinned shim)
+        join(homedir(), '.local', 'bin', 'codex'),
+        '/opt/homebrew/bin/codex',
+        '/usr/local/bin/codex',
+        // The ChatGPT desktop app bundles its own codex, updated with the app.
+        '/Applications/ChatGPT.app/Contents/Resources/codex',
+    ],
+    claude: ['claude', join(homedir(), '.local', 'bin', 'claude'), '/opt/homebrew/bin/claude', '/usr/local/bin/claude'],
+};
+/**
+ * Real probe: runs `<bin> --version` and parses the first semver-ish token out
+ * of stdout. Returns `undefined` when the binary isn't present/runnable (spawn
+ * error, timeout, or nonzero exit); `null` version when it ran but produced no
+ * parseable version string.
  */
 export function probe(bin) {
     const result = spawnSync(bin, ['--version'], {
@@ -18,18 +36,65 @@ export function probe(bin) {
     const match = result.stdout?.match(VERSION_RE);
     return { version: match ? match[0] : null };
 }
+/** Numeric segment compare; a parseable version always beats null.
+ *  Shared: agent-CLI detection here, and the package update check
+ *  (server/updateCheck.ts) both rank semver-ish strings with it. */
+export function newer(a, b) {
+    if (a === null)
+        return false;
+    if (b === null)
+        return true;
+    const as = a.split('.').map(Number);
+    const bs = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+        const d = (as[i] ?? 0) - (bs[i] ?? 0);
+        if (d !== 0)
+            return d > 0;
+    }
+    return false;
+}
 /**
- * Detects which coding-agent CLIs are available on PATH, and the version
- * each reports (null when present but unparseable). `probeBin` is
- * injectable so tests can stub PATH presence/version without shelling out
- * for real binaries.
+ * Detects which coding-agent CLIs are available — probing PATH plus the known
+ * install locations for each kind — and keeps the NEWEST version found per
+ * kind, with the binary path it came from. `probeBin` is injectable so tests
+ * can stub presence/version per location without shelling out.
  */
 export function detectAgents(probeBin = probe) {
     const found = [];
-    for (const kind of CANDIDATES) {
-        const result = probeBin(kind);
-        if (result)
-            found.push({ kind, version: result.version });
+    for (const kind of Object.keys(CANDIDATE_BINS)) {
+        let best;
+        const seen = new Set();
+        for (const bin of CANDIDATE_BINS[kind]) {
+            if (seen.has(bin))
+                continue;
+            seen.add(bin);
+            const result = probeBin(bin);
+            if (!result)
+                continue;
+            if (!best || newer(result.version, best.version)) {
+                best = { kind, version: result.version, bin };
+            }
+        }
+        if (best)
+            found.push(best);
     }
     return found;
 }
+// Probing every candidate spawns several subprocesses; /setup-status and
+// /agent/available are polled by the studio, so cache briefly.
+const RESOLVE_TTL_MS = 30_000;
+let cachedAt = 0;
+let cached = null;
+/** Cached detection — the newest binary per kind, refreshed every 30s. */
+export function detectAgentsCached() {
+    const now = Date.now();
+    if (!cached || now - cachedAt > RESOLVE_TTL_MS) {
+        cached = detectAgents();
+        cachedAt = now;
+    }
+    return cached;
+}
+/** The concrete binary path spawns should use for `kind` — the newest found. */
+export function resolveAgentBin(kind) {
+    return detectAgentsCached().find((a) => a.kind === kind)?.bin;
+}

package/dist/server/agents/modelRejectionHint.js

@@ -1,4 +1,4 @@
-const MODEL_REJECTION_RE = /unknown model|unsupported model|invalid model|model.*not.*(found|supported)/i;
+const MODEL_REJECTION_RE = /unknown model|unsupported model|invalid model|model.*not.*(found|supported)|model requires a newer version/i;
 /**
  * When an agent CLI exits nonzero without ever emitting a terminal `done`,
  * inspect its buffered stderr tail for known model-rejection shapes (a stale

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

@@ -27,6 +27,9 @@ export type AgentIntent = {
 } | {
     action: 'scout-infrastructure';
     instruction: string;
+} | {
+    action: 'guided-setup';
+    instruction: string;
 } | {
     action: 'cover-operation';
     flowId: string;
@@ -76,4 +79,15 @@ export interface AvailableNode {
  * instead of inventing parallel config. The `scout-infrastructure` intent
  * itself is what WRITES this manifest, so it does not receive the block.
  */
-export declare function buildPrompt(intent: AgentIntent, apisDir: string, relPath: string, availableNodes?: AvailableNode[], projectLanguage?: 'javascript' | 'typescript', infrastructure?: InfrastructureManifest | null): string;
+/** Ground truth the RUNNER already verified — injected into the guided-setup
+ *  prompt so the agent starts from known facts instead of burning its first
+ *  turn re-deriving them with CLI probes and file reads. */
+export interface GuidedSetupState {
+    gitRepo: boolean;
+    skillsInstalled: boolean;
+    environmentsConfigured: boolean;
+    infrastructurePresent: boolean;
+    opCount: number;
+    onlyHello: boolean;
+}
+export declare function buildPrompt(intent: AgentIntent, apisDir: string, relPath: string, availableNodes?: AvailableNode[], projectLanguage?: 'javascript' | 'typescript', infrastructure?: InfrastructureManifest | null, guidedState?: GuidedSetupState | null): string;

package/dist/server/agents/prompt.js

@@ -1,45 +1,21 @@
+import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /** Absolute path to the register-API CLI bin (`node <this> <cmd>`), resolved
  *  from this file's location. This exact invocation is the ONLY sandbox-safe
  *  way to run the CLI: `npx emberflow` / `tsx` spawn a tsx IPC pipe the codex
- *  sandbox blocks; this bin runs the CLI in-process under tsx's register API. */
-const EMBERFLOW_BIN = resolve(dirname(fileURLToPath(import.meta.url)), '../../bin/emberflow.mjs');
-/**
- * Builds a natural-language prompt for a coding agent (Codex/Claude) that
- * turns a studio `AgentIntent` into skill-aware instructions for editing
- * Emberflow flow files. Pure and deterministic: same inputs always produce
- * the same prompt string.
+ *  sandbox blocks; this bin runs the CLI in-process under tsx's register API.
  *
- * `relPath` is the operation's on-disk relative path under `apisDir` (e.g.
- * `default/triage`) — NOT necessarily the same as `intent.flowId` (the
- * in-file `id`), since operations are keyed by id but stored by path. For
- * `new-operation` there is no existing flow yet, so `relPath` instead carries
- * the *resolved target directory* under `apisDir` (e.g. `billing` or
- * `default`) that the new operation file should be created inside.
- *
- * `availableNodes` is the full, consumer-specific set of registered node
- * types (domain nodes like `ValidateCredentials`/`FetchUser` plus built-ins
- * like `Input`/`Result`/`Response`/`requireAuth`). It is injected so the agent
- * knows what it can REUSE — but nodes are real code it can also author. The
- * prompt encourages inventing a node (registering its implementation) when no
- * existing one fits; the single guardrail is that a referenced `type` must be
- * registered in the same change, so a made-up type with no implementation
- * (e.g. a bare `CurrentServerTime`) can't slip through validation.
- *
- * `projectLanguage` is the target project's authored language (from its
- * `ProjectConfig.language`, explicit-or-inferred). Defaults to 'typescript' —
- * the Emberflow repo itself, when this function is called without a loaded
- * consumer project.
- *
- * `infrastructure` is the loaded `emberflow/infrastructure.json` manifest (or
- * `null` when the project hasn't been scouted / the file is malformed). When
- * present, a preamble block after the node palette lists what the project
- * already uses so the agent REUSES it (same secretRef names, same systems)
- * instead of inventing parallel config. The `scout-infrastructure` intent
- * itself is what WRITES this manifest, so it does not receive the block.
- */
-export function buildPrompt(intent, apisDir, relPath, availableNodes = [], projectLanguage = 'typescript', infrastructure = null) {
+ *  Two layouts: in the source repo this file is server/agents/prompt.ts and
+ *  bin/ is two levels up; in the shipped package it runs from
+ *  dist/server/agents/prompt.js while bin/ stays at the package ROOT — three
+ *  levels up. Probe both so consumer installs don't hand agents a dead path. */
+const EMBERFLOW_BIN = (() => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [resolve(here, '../../bin/emberflow.mjs'), resolve(here, '../../../bin/emberflow.mjs')];
+    return candidates.find((p) => existsSync(p)) ?? candidates[0];
+})();
+export function buildPrompt(intent, apisDir, relPath, availableNodes = [], projectLanguage = 'typescript', infrastructure = null, guidedState = null) {
     const lines = [];
     /** Shared invariant for every flow-mutating intent: doctor is the mechanical
      *  checker (missing param defaults, uncovered path params, missing expects),
@@ -80,7 +56,7 @@ export function buildPrompt(intent, apisDir, relPath, availableNodes = [], proje
     // REUSES it instead of inventing parallel config. Omitted for the scout
     // intent — it's the one that WRITES the manifest, so priming it with the
     // manifest's own contents would be circular.
-    if (intent.action !== 'scout-infrastructure') {
+    if (intent.action !== 'scout-infrastructure' && intent.action !== 'guided-setup') {
         const INFRASTRUCTURE_ITEM_CAP = 30;
         if (infrastructure && infrastructure.items.length > 0) {
             lines.push('Known project infrastructure (from emberflow/infrastructure.json — what this project already uses):');
@@ -291,6 +267,8 @@ export function buildPrompt(intent, apisDir, relPath, availableNodes = [], proje
                 lines.push(`User instruction (verbatim): ${intent.instruction}`);
                 lines.push('');
             }
+            lines.push(`AMENDMENT vs FULL RESCAN: if the instruction above asks for an amendment to the existing manifest — add, remove, or correct SPECIFIC items — and emberflow/infrastructure.json already exists, UPDATE that file in place: preserve every item you were not asked to change, apply only the requested change, and bump "scannedAt" to the current timestamp. Do NOT regenerate the whole manifest from scratch for a targeted amendment. A FULL RESCAN (rebuild the manifest from the whole project) remains the default when the instruction is empty or asks to re-scan/refresh generally.`);
+            lines.push('');
             lines.push(`Investigate broadly — enumerate what the project already depends on and talks to:`);
             lines.push(`  • Dependencies: package.json + lockfiles, requirements.txt / pyproject.toml, go.mod, Gemfile, composer.json, etc.`);
             lines.push(`  • Config files: docker-compose.yml, Dockerfile, .env.example / .env.sample (NAMES only), prisma/schema.prisma, ORM configs, framework config.`);
@@ -337,6 +315,50 @@ export function buildPrompt(intent, apisDir, relPath, availableNodes = [], proje
             lines.push(doctorLine(intent.flowId));
             break;
         }
+        case 'guided-setup': {
+            const manifestPath = 'emberflow/infrastructure.json';
+            lines.push('Relevant skill: emberflow-basics (the project model + file layout).');
+            lines.push('');
+            lines.push('Task: guide this project through first-time Emberflow setup in ONE run. You orchestrate several steps IN ORDER, but you FIRST read the ground truth and SKIP anything already satisfied — you never redo done work. Unlike setup-environments (which is FORBIDDEN from exploring the codebase), this intent MAY read the project the way the infrastructure scout does: exploring dependencies, config, schemas and env references to understand what the project is IS permitted and expected here.');
+            lines.push('');
+            if (intent.instruction.trim()) {
+                lines.push(`User notes / continuation answer (verbatim): ${intent.instruction}`);
+                lines.push('');
+            }
+            lines.push("STYLE: this stream renders in a small onboarding panel, read by the person who owns this project — not by a developer tailing a terminal. Write to THEM about THEIR project: what you're doing for them and what you found that matters to them. Be TERSE — a few short lines per step. NEVER narrate tool mechanics (commands you ran, files you probed, exit codes), internal bookkeeping (\"ground truth\", \"manifest written\"), model ids, or state the checklist beside you already shows. No decorated asides either (\"★ Insight\" boxes, educational commentary) — even if your own configured output style calls for them, this panel is not the place. Good: \"Your project is a fresh start — no databases or APIs to wire up yet.\" Bad: \"Scout: bare scaffold, no .env, wrote emberflow/infrastructure.json (greenfield:true).\"");
+            lines.push('');
+            lines.push('ASKING QUESTIONS: whenever a step needs the user\'s input, END your message with a fenced block the studio renders as an interactive form (the user clicks options; their answers arrive as your next continuation message). Format — a fenced code block with language `emberflow-questions` containing JSON: {"questions":[{"id":"<slug>","text":"<question>","why":"<one short line of context — why this matters, optional>","options":["<opt1>","<opt2>"],"custom":true}]}. "options" are clickable choices; "custom": true also offers a free-text field. An option may be an object {"label":"…","action":"finish"} — choosing it ends onboarding client-side — or {"label":"…","action":"submit"} — choosing it sends the answers immediately, skipping any remaining questions. Use "why" whenever the user might not know why they\'re being asked — assume they are new to Emberflow. Nothing may follow the block.');
+            lines.push('');
+            lines.push('TURN SHAPE — the user must never wait before being asked anything. FIRST TURN (no continuation answer in the instruction): if the environments interview (step 5) is still needed, output ONE short greeting line and END IMMEDIATELY with the interview questions block — run NO commands and write NO files first; every working step (scout, skills, environments file) happens on the CONTINUATION turn after their answers arrive. If environments are already configured, the first turn instead does the working steps directly and ends with the step-6 block.');
+            lines.push('');
+            lines.push('Work through these steps IN ORDER, skipping any that your ground-truth read shows is already satisfied:');
+            lines.push('');
+            if (guidedState) {
+                lines.push(`1. KNOWN PROJECT STATE — verified by the runner as this run started; TRUST it, do not re-check any of it with commands or file reads: git repository: ${guidedState.gitRepo ? 'yes' : 'NO'}; agent skills installed: ${guidedState.skillsInstalled ? 'yes' : 'no'}; environments configured: ${guidedState.environmentsConfigured ? 'yes' : 'no'}; infrastructure manifest (${manifestPath}): ${guidedState.infrastructurePresent ? 'present' : 'absent'}; operations: ${guidedState.opCount}${guidedState.onlyHello ? ' (only the default hello example)' : ''}. Skip every step this state already satisfies.${guidedState.gitRepo ? '' : ' There is NO git repository: STOP and tell the user to run `git init && git add -A && git commit -m "initial"` — nothing else can proceed without it.'}`);
+            }
+            else {
+                lines.push('1. READ THE GROUND TRUTH FIRST. Before acting, inspect what already exists so you can skip done work: whether this is a git repo, whether the agent skills are installed (.claude/skills/emberflow-basics or the codex/home equivalents), whether emberflow.environments.json exists, whether ' +
+                    manifestPath +
+                    ' exists, and whether the project has operations beyond the default hello example (list-workflows). If there is NO git repository, STOP and tell the user the exact command to run — `git init && git add -A && git commit -m "initial"` — because every later step depends on git snapshotting and nothing here can proceed without it.');
+            }
+            lines.push('');
+            lines.push(`2. GREENFIELD JUDGMENT + SCOUT. If ${manifestPath} is already present, SKIP this step (say so). Otherwise inspect the project the way the infrastructure scout does — dependencies (package.json + lockfiles, requirements.txt / pyproject.toml, go.mod, Gemfile, composer.json), config (docker-compose.yml, Dockerfile, .env.example NAMES only, prisma/schema.prisma, ORM/framework config), ORM schemas / migrations, env-var REFERENCES in source (process.env.X — NAMES only), HTTP clients / SDKs, and the project's own routes. If the project has real infrastructure (BROWNFIELD), run the full scout and WRITE ${manifestPath} describing it (version, scannedAt, greenfield:false, summary, items[] each with kind, name, evidence file+note, suggestedSecretRefs env-var NAMES only). If it is a bare scaffold (GREENFIELD — no databases, external APIs or providers), WRITE ${manifestPath} with "greenfield": true, empty items, and a one-line summary saying so — do NOT invent items to fill space. Manifest kinds: database, http-api, queue, cache, email, llm, auth, framework, storage, other.`);
+            lines.push('');
+            lines.push(`3. SKILLS. If the agent skills are already installed (from your ground-truth read), SKIP this step. Otherwise install them by running the init CLI — it is idempotent and, because this project already has a config, adds ONLY the skills (and any missing .gitignore lines), leaving your config and operations untouched:`);
+            lines.push(`     node ${EMBERFLOW_BIN} init --local --no-launch --no-git ${projectLanguage === 'javascript' ? '--js' : '--ts'}`);
+            lines.push(`   Report which skill files it created. The ${projectLanguage === 'javascript' ? '--js' : '--ts'} flag matches this project's language so init doesn't refuse to run against the existing config. If init CANNOT install them (the command errors), emit the exact command for the user to run themselves and move on — don't fail the whole run over skills.`);
+            lines.push('');
+            lines.push('4. CONNECTION PROOF. This run itself proves the agent CLI works end-to-end — you ARE that agent. No separate action, no model ids: one plain sentence at wrap-up like "Connection verified — I\'m running against your project."');
+            lines.push('');
+            lines.push(`5. ENVIRONMENTS INTERVIEW — ask FIRST (on the very first turn, before any other work; see TURN SHAPE), write after. If emberflow.environments.json already configures environments, SKIP (you may still refine on request). Otherwise end the FIRST turn with an emberflow-questions block whose FIRST question is whether to set environments up now at all: text like "Set up your environments now?", why like "Environments tell Emberflow where runs point — mock data now, your real dev or prod systems later. Takes a minute, and you can change it any time.", options ["Set up now",{"label":"Later — I'll do it from the setup checklist","action":"submit"}] (action "submit" sends the answer immediately, skipping the remaining questions). If they choose later: on the continuation turn do steps 2–4 only, then step 6, noting they can return via the Environments step in the setup checklist. If now: the SAME block also carries the detail questions (each with a one-line "why"): which environments (options like "dev + prod", "dev + staging + prod", custom), which is the default, which are production-like (protected), and their base URLs (custom text) — the form is a one-at-a-time wizard, so later answers simply arrive alongside; if they chose "Later" the other answers are ignored. A guided setup that decides everything itself and asks nothing has FAILED this step. CONTINUATION turn (answers arrive as your instruction): NOW do the working steps 2–4 (scout, skills, connection) and write emberflow.environments.json (STRUCTURE ONLY) from their answers — "defaultEnvironment" plus entries under "environments" (kebab/lower-case names); "secrets" is a LIST of key NAMES, never a value map; base URLs and non-secret config under "vars"; production-like environments get "protected": true (forces studio safe mode). Unknown values → clearly-named placeholders (e.g. "baseUrl": "https://CHANGE-ME.example.com"). Mention once that the file is gitignored. Then finish with step 6.`);
+            lines.push('');
+            lines.push('NEVER write secret or credential VALUES anywhere — not in emberflow.environments.json (which holds key NAMES only), not in ' +
+                manifestPath +
+                " (env-var NAMES only), and not in your output. Environment auth is set only via set-environment-auth (refs/names, never values); manifests carry names only. When auth or API keys are involved, scaffold at most the secret key NAMES and tell the user to enter the actual secret values in the studio's Manage Environment dialog — never in this chat.");
+            lines.push('');
+            lines.push('6. WRAP-UP + FIRST BUILD. One line per completed step (done/skipped) plus anything that genuinely needs the user (secret values to enter) — no prose report. Then END with a final emberflow-questions block: {"id":"first-build","text":"What do you want to build first?","options":[{"label":"Just look around","action":"finish"}],"custom":true}. If the user answers with a description, scaffold that operation in a continuation turn — create the operation file(s) following the emberflow-new-workflow skill (runnable in mock mode, scenarios included) and say which operation to open.');
+            break;
+        }
         case 'ask': {
             lines.push('Relevant skill: emberflow-basics (how the project is structured) — read it only if answering needs it.');
             lines.push('');

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

@@ -1,4 +1,4 @@
-import { type AgentIntent, type AvailableNode } from './prompt.js';
+import { type AgentIntent, type AvailableNode, type GuidedSetupState } from './prompt.js';
 import type { InfrastructureManifest } from '../infrastructure.js';
 import type { AgentEvent, AgentKind } from './types.js';
 export interface StartAgentOptions {
@@ -41,6 +41,12 @@ export declare class AgentRunManager {
      * so agents REUSE known infrastructure instead of inventing parallel config.
      */
     private readonly infrastructure;
+    /**
+     * Getter for the runner-verified setup snapshot injected into guided-setup
+     * prompts as KNOWN state — so the agent doesn't burn its first turn
+     * re-deriving facts (git? skills? envs? ops?) the server already computed.
+     */
+    private readonly guidedState;
     private readonly runs;
     private activeRunId;
     constructor(projectDir: string, apisDir: string, pathOf: (id: string) => string | undefined, 
@@ -62,7 +68,13 @@ export declare class AgentRunManager {
      * hasn't been scouted or the file is malformed. Injected as a prompt preamble
      * so agents REUSE known infrastructure instead of inventing parallel config.
      */
-    infrastructure?: () => InfrastructureManifest | null);
+    infrastructure?: () => InfrastructureManifest | null, 
+    /**
+     * Getter for the runner-verified setup snapshot injected into guided-setup
+     * prompts as KNOWN state — so the agent doesn't burn its first turn
+     * re-deriving facts (git? skills? envs? ops?) the server already computed.
+     */
+    guidedState?: () => GuidedSetupState | null);
     /** Validates the project + flow, snapshots git, spawns the adapter, and returns the new run's id. */
     start(intent: AgentIntent, opts?: StartAgentOptions): string;
     /** Drains the adapter's events into the run's buffer, fanning each out to live subscribers. */
@@ -79,6 +91,15 @@ export declare class AgentRunManager {
         reverted: string[];
     } | undefined;
     cancel(id: string): boolean;
+    /**
+     * Kills the active agent run's process tree, if any. Agent CLIs are spawned
+     * DETACHED (their own process group, so cancel can tree-kill their
+     * subprocesses) — which also means they survive the runner dying unless the
+     * shutdown path explicitly cancels them. An orphaned agent keeps editing the
+     * project long after the studio is gone; call this from the server's
+     * SIGINT/SIGTERM handlers.
+     */
+    shutdown(): void;
     /**
      * Evicts oldest terminal (done|error) runs beyond MAX_TERMINAL_RUNS so the
      * `runs` map — and each run's full event buffer — doesn't grow unbounded

package/dist/server/agents/runManager.js

@@ -3,6 +3,7 @@ import { changedFiles, diffSince, isGitRepo, revert as gitRevert, snapshot } fro
 import { buildPrompt } from './prompt.js';
 import { spawnCodex } from './codexAdapter.js';
 import { spawnClaude } from './claudeAdapter.js';
+import { resolveAgentBin } from './detect.js';
 import { isPathWithin } from '../pathSafety.js';
 /** Thrown by `start()`; `status` maps directly onto the HTTP status the endpoint should return. */
 export class AgentStartError extends Error {
@@ -57,6 +58,7 @@ export class AgentRunManager {
     availableNodes;
     projectLanguage;
     infrastructure;
+    guidedState;
     runs = new Map();
     activeRunId = null;
     constructor(projectDir, apisDir, pathOf, 
@@ -78,13 +80,20 @@ export class AgentRunManager {
      * hasn't been scouted or the file is malformed. Injected as a prompt preamble
      * so agents REUSE known infrastructure instead of inventing parallel config.
      */
-    infrastructure = () => null) {
+    infrastructure = () => null, 
+    /**
+     * Getter for the runner-verified setup snapshot injected into guided-setup
+     * prompts as KNOWN state — so the agent doesn't burn its first turn
+     * re-deriving facts (git? skills? envs? ops?) the server already computed.
+     */
+    guidedState = () => null) {
         this.projectDir = projectDir;
         this.apisDir = apisDir;
         this.pathOf = pathOf;
         this.availableNodes = availableNodes;
         this.projectLanguage = projectLanguage;
         this.infrastructure = infrastructure;
+        this.guidedState = guidedState;
     }
     /** Validates the project + flow, snapshots git, spawns the adapter, and returns the new run's id. */
     start(intent, opts = {}) {
@@ -92,7 +101,7 @@ export class AgentRunManager {
             throw new AgentStartError('An agent run is already active for this project', 409);
         }
         if (!isGitRepo(this.projectDir)) {
-            throw new AgentStartError(`${this.projectDir} is not a git repository`, 400);
+            throw new AgentStartError(`${this.projectDir} is not a git repository — Emberflow snapshots agent changes with git so you can review and revert them. Run: git init && git add -A && git commit -m "initial" — then retry.`, 400);
         }
         // `new-operation` creates a brand-new flow, so there's no existing
         // flowId to validate against pathOf — it validates `location` instead.
@@ -109,10 +118,12 @@ export class AgentRunManager {
         }
         else if (intent.action === 'setup-auth' ||
             intent.action === 'setup-environments' ||
-            intent.action === 'scout-infrastructure') {
+            intent.action === 'scout-infrastructure' ||
+            intent.action === 'guided-setup') {
             // No flow file: setup-auth targets an environment, setup-environments the
-            // environments file, and scout-infrastructure reads the whole project and
-            // writes emberflow/infrastructure.json — none has a relPath to resolve.
+            // environments file, scout-infrastructure reads the whole project and
+            // writes emberflow/infrastructure.json, and guided-setup orchestrates all
+            // of setup across project-root files — none has a relPath to resolve.
             relPath = '';
         }
         else if (intent.action === 'ask') {
@@ -145,16 +156,19 @@ export class AgentRunManager {
         }
         this.pruneTerminalRuns();
         const snap = snapshot(this.projectDir);
-        const prompt = buildPrompt(intent, this.apisDir, relPath, this.availableNodes(), this.projectLanguage, this.infrastructure());
+        const prompt = buildPrompt(intent, this.apisDir, relPath, this.availableNodes(), this.projectLanguage, this.infrastructure(), intent.action === 'guided-setup' ? this.guidedState() : null);
+        // Env override wins (tests stub agents this way); otherwise use the NEWEST
+        // binary detection found across PATH + known install locations — a PATH
+        // shim pinned to a stale release must not shadow a newer install elsewhere.
         const adapter = opts.agent === 'claude'
             ? spawnClaude(prompt, this.projectDir, {
                 model: opts.model,
-                bin: process.env.EMBERFLOW_CLAUDE_BIN,
+                bin: process.env.EMBERFLOW_CLAUDE_BIN ?? resolveAgentBin('claude'),
             })
             : spawnCodex(prompt, this.projectDir, {
                 model: opts.model,
                 reasoning: opts.reasoning ?? 'medium',
-                bin: process.env.EMBERFLOW_CODEX_BIN,
+                bin: process.env.EMBERFLOW_CODEX_BIN ?? resolveAgentBin('codex'),
             });
         const id = randomUUID();
         const run = { id, snapshot: snap, adapter, buffer: [], listeners: new Set(), status: 'running' };
@@ -237,6 +251,20 @@ export class AgentRunManager {
         run.adapter.cancel();
         return true;
     }
+    /**
+     * Kills the active agent run's process tree, if any. Agent CLIs are spawned
+     * DETACHED (their own process group, so cancel can tree-kill their
+     * subprocesses) — which also means they survive the runner dying unless the
+     * shutdown path explicitly cancels them. An orphaned agent keeps editing the
+     * project long after the studio is gone; call this from the server's
+     * SIGINT/SIGTERM handlers.
+     */
+    shutdown() {
+        if (!this.activeRunId)
+            return;
+        const run = this.runs.get(this.activeRunId);
+        run?.adapter.cancel();
+    }
     /**
      * Evicts oldest terminal (done|error) runs beyond MAX_TERMINAL_RUNS so the
      * `runs` map — and each run's full event buffer — doesn't grow unbounded

package/dist/server/client.d.ts

@@ -4,6 +4,7 @@ export type { ApiTree, FolderNode, ApiNode, OpSummary } from './apiStore.js';
 /** SSE-shaped events emitted on GET /runs/:id/events — mirrors server/runRegistry.ts RunEvent. */
 export type RunEvent = {
     type: 'nodeState';
+    workflowId: string;
     nodeId: string;
     state: NodeRunState;
 } | {

package/dist/server/client.js

@@ -1,6 +1,11 @@
-const DEFAULT_BASE_URL = 'http://127.0.0.1:8092';
 function baseUrl() {
-    return process.env.EMBERFLOW_RUNNER_URL ?? DEFAULT_BASE_URL;
+    // EMBERFLOW_RUNNER_PORT is how the runner itself is launched on a custom
+    // port (bin/commands.ts sets it for `emberflow dev --port`), and child
+    // processes — including agent runs invoking this CLI — inherit it. Without
+    // honoring it here, an agent spawned by a runner on :8095 would call back
+    // to the default :8092 and report the runner down.
+    return (process.env.EMBERFLOW_RUNNER_URL ??
+        `http://127.0.0.1:${process.env.EMBERFLOW_RUNNER_PORT ?? 8092}`);
 }
 /** Thrown when the runner cannot be reached at all (connection refused, DNS, etc). */
 export class RunnerUnreachableError extends Error {