@xdelivered/emberflow 0.2.0 → 0.5.0

package/server/agents/detect.ts

@@ -1,20 +1,40 @@
 import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import type { AgentKind } from './types';
 
-const CANDIDATES: AgentKind[] = ['codex', 'claude'];
-
 const VERSION_RE = /\d+\.\d+\.\d+/;
 
+/**
+ * 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: Record<AgentKind, string[]> = {
+  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'],
+};
+
 export interface DetectedAgent {
   kind: AgentKind;
   version: string | null;
+  /** The concrete binary the newest version was found at — what spawns should use. */
+  bin: string;
 }
 
 /**
- * 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.
+ * 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: string): { version: string | null } | undefined {
   const result = spawnSync(bin, ['--version'], {
@@ -27,17 +47,65 @@ export function probe(bin: string): { version: string | null } | undefined {
   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: string | null, b: string | null): boolean {
+  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: (bin: string) => { version: string | null } | undefined = probe): DetectedAgent[] {
+export function detectAgents(
+  probeBin: (bin: string) => { version: string | null } | undefined = probe,
+): DetectedAgent[] {
   const found: DetectedAgent[] = [];
-  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) as AgentKind[]) {
+    let best: DetectedAgent | undefined;
+    const seen = new Set<string>();
+    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: DetectedAgent[] | null = null;
+
+/** Cached detection — the newest binary per kind, refreshed every 30s. */
+export function detectAgentsCached(): DetectedAgent[] {
+  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: AgentKind): string | undefined {
+  return detectAgentsCached().find((a) => a.kind === kind)?.bin;
+}

package/server/agents/modelRejectionHint.ts

@@ -1,6 +1,7 @@
 import type { AgentKind } from './types';
 
-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`,

package/server/agents/prompt.test.ts

@@ -484,6 +484,15 @@ describe('buildPrompt', () => {
       expect(prompt).toMatch(/open questions/i);
     });
 
+    it('supports amending an existing manifest in place for targeted add/remove/correct instructions', () => {
+      const prompt = buildPrompt(scout, apisDir, relPath);
+      expect(prompt).toMatch(/AMENDMENT vs FULL RESCAN/);
+      expect(prompt).toMatch(/UPDATE that file in place/i);
+      expect(prompt).toMatch(/preserve every item you were not asked to change/i);
+      expect(prompt).toMatch(/bump "scannedAt"/);
+      expect(prompt).toMatch(/FULL RESCAN.*remains the default/i);
+    });
+
     it('does NOT get the doctor rule, the mocks guidance, or the traceKind nudge (it edits no operation)', () => {
       const prompt = buildPrompt(scout, apisDir, relPath);
       expect(prompt).not.toMatch(/run doctor/i);
@@ -504,6 +513,125 @@ describe('buildPrompt', () => {
     });
   });
 
+  describe('guided-setup', () => {
+    const guided: AgentIntent = {
+      action: 'guided-setup',
+      instruction: 'I want dev and prod environments.',
+    };
+
+    it('includes the user notes verbatim and orchestrates the steps IN ORDER, reading state first + skipping done work', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath);
+      expect(prompt).toContain(guided.instruction);
+      expect(prompt).toMatch(/IN ORDER/);
+      expect(prompt).toMatch(/READ THE GROUND TRUTH FIRST/);
+      expect(prompt).toMatch(/skip(ping)? .*(done|already satisfied)/i);
+    });
+
+    it('explicitly PERMITS exploration (unlike setup-environments) — it may read the project like the scout', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath);
+      expect(prompt).toMatch(/MAY read the project/i);
+      expect(prompt).toMatch(/the way the infrastructure scout does/i);
+      // Names the setup-environments no-explore rule it is inverting.
+      expect(prompt).toMatch(/setup-environments/);
+    });
+
+    it('covers greenfield vs brownfield judgment and writes the infrastructure manifest', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath);
+      expect(prompt).toMatch(/GREENFIELD/);
+      expect(prompt).toMatch(/BROWNFIELD/);
+      expect(prompt).toMatch(/emberflow\/infrastructure\.json/);
+      expect(prompt).toMatch(/"greenfield": true/);
+    });
+
+    it('installs skills via the in-process bin with the project-language flag (--ts for a TS project)', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath, [], 'typescript');
+      expect(prompt).toMatch(/emberflow\.mjs init --local --no-launch --no-git --ts/);
+    });
+
+    it('installs skills with --js for a javascript project', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath, [], 'javascript');
+      expect(prompt).toMatch(/emberflow\.mjs init --local --no-launch --no-git --js/);
+    });
+
+    // With a runner-verified snapshot, the prompt states KNOWN facts and
+    // forbids re-probing them — no wasted first turn of CLI checks.
+    it('injects the runner-verified state as KNOWN facts instead of a probe step', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath, [], 'typescript', null, {
+        gitRepo: true,
+        skillsInstalled: true,
+        environmentsConfigured: false,
+        infrastructurePresent: false,
+        opCount: 1,
+        onlyHello: true,
+      });
+      expect(prompt).toMatch(/KNOWN PROJECT STATE/);
+      expect(prompt).toMatch(/TRUST it, do not re-check/);
+      expect(prompt).toMatch(/git repository: yes/);
+      expect(prompt).toMatch(/only the default hello example/);
+      expect(prompt).not.toMatch(/READ THE GROUND TRUTH FIRST/);
+    });
+
+    it('missing git in the snapshot carries the stop-and-tell-user instruction', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath, [], 'typescript', null, {
+        gitRepo: false,
+        skillsInstalled: false,
+        environmentsConfigured: false,
+        infrastructurePresent: false,
+        opCount: 1,
+        onlyHello: true,
+      });
+      expect(prompt).toMatch(/There is NO git repository: STOP/);
+    });
+
+    it('without a snapshot, falls back to the self-probe ground-truth step', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath);
+      expect(prompt).toMatch(/READ THE GROUND TRUTH FIRST/);
+    });
+
+    it('runs the environments interview and ENDS with numbered questions', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath);
+      expect(prompt).toMatch(/ENVIRONMENTS INTERVIEW/);
+      expect(prompt).toMatch(/emberflow\.environments\.json/);
+      // The interview is a staged, structured form: ask BEFORE writing, via
+      // the emberflow-questions block the studio renders interactively —
+      // and skipping it is called out as failing the step.
+      expect(prompt).toMatch(/ask FIRST \(on the very first turn/i);
+      // Turn-shape contract: questions land immediately, work happens after.
+      expect(prompt).toMatch(/TURN SHAPE/);
+      expect(prompt).toMatch(/run NO commands and write NO files first/);
+      expect(prompt).toMatch(/emberflow-questions/);
+      expect(prompt).toMatch(/asks nothing has FAILED/i);
+      // Terse-output contract + the closing first-build question with the
+      // look-around escape hatch.
+      expect(prompt).toMatch(/Be TERSE/);
+      expect(prompt).toMatch(/What do you want to build first\?/);
+      expect(prompt).toMatch(/"action":"finish"/);
+    });
+
+    it('never writes secret VALUES and states the connection-proof + wrap-up summary', () => {
+      const prompt = buildPrompt(guided, apisDir, relPath);
+      expect(prompt).toMatch(/NEVER write secret or credential VALUES/i);
+      expect(prompt).toMatch(/CONNECTION PROOF/);
+      expect(prompt).toMatch(/no model ids/i);
+      expect(prompt).toMatch(/WRAP-UP \+ FIRST BUILD/);
+      expect(prompt).toMatch(/One line per completed step/);
+    });
+
+    it('does NOT get the doctor rule, mocks guidance, or the known-infrastructure preamble (it writes the manifest)', () => {
+      const manifest = {
+        version: 1,
+        greenfield: false,
+        items: [
+          { id: 'pg', kind: 'database' as const, name: 'Postgres', evidence: [], suggestedSecretRefs: ['DATABASE_URL'], suggestedVars: [] },
+        ],
+      };
+      const prompt = buildPrompt(guided, apisDir, relPath, [], 'typescript', manifest);
+      expect(prompt).not.toMatch(/run doctor/i);
+      expect(prompt).not.toMatch(/"mocks"/);
+      expect(prompt).not.toMatch(/Known project infrastructure \(from/);
+    });
+  });
+
   describe('known-infrastructure preamble injection', () => {
     const editFlow: AgentIntent = { action: 'edit-flow', flowId: 'hello', instruction: 'x' };
     const manifest = {

package/server/agents/prompt.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { InfrastructureManifest } from '../infrastructure';
@@ -5,8 +6,17 @@ import type { InfrastructureManifest } from '../infrastructure';
 /** 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');
+ *  sandbox blocks; this bin runs the CLI in-process under tsx's register API.
+ *
+ *  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 type AgentIntent =
   | { action: 'new-scenario'; flowId: string; instruction: string }
@@ -16,6 +26,7 @@ export type AgentIntent =
   | { action: 'setup-auth'; environment: string; instruction: string }
   | { action: 'setup-environments'; instruction: string }
   | { action: 'scout-infrastructure'; instruction: string }
+  | { action: 'guided-setup'; instruction: string }
   | { action: 'cover-operation'; flowId: string; instruction: string }
   | { action: 'ask'; flowId?: string; instruction: string };
 
@@ -60,6 +71,18 @@ 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.
  */
+/** 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 function buildPrompt(
   intent: AgentIntent,
   apisDir: string,
@@ -67,6 +90,7 @@ export function buildPrompt(
   availableNodes: AvailableNode[] = [],
   projectLanguage: 'javascript' | 'typescript' = 'typescript',
   infrastructure: InfrastructureManifest | null = null,
+  guidedState: GuidedSetupState | null = null,
 ): string {
   const lines: string[] = [];
 
@@ -120,7 +144,7 @@ export function buildPrompt(
   // 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):');
@@ -420,6 +444,10 @@ export function buildPrompt(
         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:`,
       );
@@ -496,6 +524,77 @@ export function buildPrompt(
       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/server/agents/runManager.test.ts

@@ -127,6 +127,15 @@ describe('AgentRunManager', () => {
     await collectUntilDone(manager, id);
   });
 
+  it('shutdown cancels the active run (and no-ops when idle)', async () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    expect(() => manager.shutdown()).not.toThrow(); // idle: nothing active
+    const id = manager.start(intent);
+    expect(() => manager.shutdown()).not.toThrow();
+    // The cancelled run must still reach a terminal state — no hung adapter.
+    await collectUntilDone(manager, id);
+  });
+
   it('rejects a flowId that tries to escape flowsDir', () => {
     const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
     const badIntent: AgentIntent = { action: 'edit-flow', flowId: '../../etc/passwd', instruction: 'x' };

package/server/agents/runManager.ts

@@ -1,9 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { changedFiles, diffSince, isGitRepo, revert as gitRevert, snapshot, type GitSnapshot } from './gitScope';
-import { buildPrompt, type AgentIntent, type AvailableNode } from './prompt';
+import { buildPrompt, type AgentIntent, type AvailableNode, type GuidedSetupState } from './prompt';
 import type { InfrastructureManifest } from '../infrastructure';
 import { spawnCodex, type SpawnedAgent } from './codexAdapter';
 import { spawnClaude } from './claudeAdapter';
+import { resolveAgentBin } from './detect';
 import type { AgentEvent, AgentKind } from './types';
 import { isPathWithin } from '../pathSafety';
 
@@ -102,6 +103,12 @@ export class AgentRunManager {
      * so agents REUSE known infrastructure instead of inventing parallel config.
      */
     private readonly infrastructure: () => InfrastructureManifest | null = () => 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.
+     */
+    private readonly guidedState: () => GuidedSetupState | null = () => null,
   ) {}
 
   /** Validates the project + flow, snapshots git, spawns the adapter, and returns the new run's id. */
@@ -110,7 +117,10 @@ 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
@@ -128,11 +138,13 @@ 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') {
       // `ask`'s flowId is optional: with one, resolve the op's relPath like
@@ -171,17 +183,21 @@ export class AgentRunManager {
       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();
@@ -266,6 +282,20 @@ export class AgentRunManager {
     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(): void {
+    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/server/client.ts

@@ -10,15 +10,21 @@ import type { ApiTree, FolderNode, ApiNode, OpSummary } from './apiStore';
 
 export type { ApiTree, FolderNode, ApiNode, OpSummary } from './apiStore';
 
-const DEFAULT_BASE_URL = 'http://127.0.0.1:8092';
-
 function baseUrl(): string {
-  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}`
+  );
 }
 
 /** SSE-shaped events emitted on GET /runs/:id/events — mirrors server/runRegistry.ts RunEvent. */
 export type RunEvent =
-  | { type: 'nodeState'; nodeId: string; state: NodeRunState }
+  | { type: 'nodeState'; workflowId: string; nodeId: string; state: NodeRunState }
   | { type: 'log'; line: LogLine }
   | { type: 'finished'; run: WorkflowRun };