@xdelivered/emberflow 0.2.0 → 0.5.0

package/bin/commands.ts

@@ -14,6 +14,7 @@ export interface ParsedArgs {
   noSkills?: boolean;
   scope?: 'global' | 'repo';
   noLaunch?: boolean;
+  noGit?: boolean;
   mock?: boolean;
   js?: boolean;
   ts?: boolean;
@@ -42,6 +43,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
     else if (a === '--global') out.scope = 'global';
     else if (a === '--local') out.scope = 'repo';
     else if (a === '--no-launch') out.noLaunch = true;
+    else if (a === '--no-git') out.noGit = true;
     else if (a === '--mock') out.mock = true;
     else if (a === '--js') out.js = true;
     else if (a === '--ts') out.ts = true;
@@ -243,17 +245,19 @@ export async function runCommand(p: ParsedArgs, ctx: RuntimeContext = defaultCtx
               skills?: false | { scope: 'repo' | 'global'; home: string };
               packageRoot?: string;
               language?: 'javascript' | 'typescript';
+              git?: boolean;
             }
           ) => Promise<number>;
           tsxResolvable: (cwd: string) => boolean;
         };
         const scope = p.scope ?? (await promptScope());
         const language = p.js ? 'javascript' : p.ts ? 'typescript' : await promptLanguage();
+        const git = !p.noGit;
         const code = await mod.runInit(
           process.cwd(),
           p.noSkills
-            ? { skills: false, packageRoot: pkgRoot, language }
-            : { skills: { scope, home: homedir() }, packageRoot: pkgRoot, language }
+            ? { skills: false, packageRoot: pkgRoot, language, git }
+            : { skills: { scope, home: homedir() }, packageRoot: pkgRoot, language, git }
         );
         if (code !== 0) return code;
 
@@ -297,7 +301,7 @@ export async function runCommand(p: ParsedArgs, ctx: RuntimeContext = defaultCtx
     }
     default:
       console.log(
-        'Usage: emberflow <dev|serve|mcp|init|run|test|doctor|list-nodes|node-schema|list-workflows|get-workflow|list-environments|login-environment|set-environment-auth|serving|validate|publish|save|create|delete|rename|samples> [--port N] [--project DIR] [--scenario NAME] [--no-skills] [--global|--local] [--no-launch] [--mock] [--js|--ts]\n' +
+        'Usage: emberflow <dev|serve|mcp|init|run|test|doctor|list-nodes|node-schema|list-workflows|get-workflow|list-environments|login-environment|set-environment-auth|serving|validate|publish|save|create|delete|rename|samples> [--port N] [--project DIR] [--scenario NAME] [--no-skills] [--global|--local] [--no-launch] [--no-git] [--mock] [--js|--ts]\n' +
           '  test [opId] [--environment NAME] [--json]   Run scenario expectations in-process (no runner) — exit 0/1/2\n' +
           '  doctor [opId] [--fix]                       Diagnose operation(s) in-process (no runner); --fix seeds param defaults — exit 0/1/2'
       );

package/bin/init.test.ts

@@ -1,10 +1,21 @@
 // bin/init.test.ts
+import { execFileSync } from 'node:child_process';
 import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { runInit, tsxResolvable } from './init';
 
+/** Run git in `dir`, returning trimmed stdout. Pins an identity so commits work
+ *  on a machine/CI with no global git config. */
+function git(dir: string, args: string[]): string {
+  return execFileSync(
+    'git',
+    ['-c', 'user.name=Test', '-c', 'user.email=test@example.com', ...args],
+    { cwd: dir, encoding: 'utf8' },
+  ).trim();
+}
+
 const dirs: string[] = [];
 function scratch(): string { const d = mkdtempSync(join(tmpdir(), 'ef-init-')); dirs.push(d); return d; }
 afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }); });
@@ -152,6 +163,89 @@ describe('runInit', () => {
   });
 });
 
+describe('runInit git bootstrap', () => {
+  it('git-inits the folder and makes the load-bearing initial commit', async () => {
+    const d = scratch();
+    await runInit(d, { skills: false });
+    expect(existsSync(join(d, '.git'))).toBe(true);
+    // Exactly one commit, the scaffold commit — the snapshot/diff/revert safety
+    // net needs a real HEAD to diff against (an unborn HEAD can't be reverted).
+    expect(git(d, ['rev-list', '--count', 'HEAD'])).toBe('1');
+    expect(git(d, ['log', '--oneline'])).toContain('chore: emberflow init');
+  });
+
+  it('commits ONLY init-scaffolded files, never the user’s pre-existing code', async () => {
+    const d = scratch();
+    // A fresh dir may already hold the user's own uncommitted app code.
+    writeFileSync(join(d, 'app.js'), 'console.log("mine");\n');
+    await runInit(d, { skills: false });
+
+    const tracked = git(d, ['ls-tree', '-r', 'HEAD', '--name-only']).split('\n');
+    expect(tracked).toContain('emberflow.config.mjs');
+    expect(tracked).toContain('emberflow/apis/default/hello.json');
+    expect(tracked).toContain('.gitignore');
+    // The user's file was NOT swept into the commit (no `git add -A`).
+    expect(tracked).not.toContain('app.js');
+    // It's still there, just untracked.
+    expect(git(d, ['status', '--porcelain'])).toContain('?? app.js');
+  });
+
+  it('--no-git (git: false) skips repo creation entirely', async () => {
+    const d = scratch();
+    await runInit(d, { skills: false, git: false });
+    expect(existsSync(join(d, '.git'))).toBe(false);
+  });
+
+  it('leaves a pre-existing repo untouched — no nested repo, no extra commit', async () => {
+    const d = scratch();
+    git(d, ['init']);
+    writeFileSync(join(d, 'README.md'), '# mine\n');
+    git(d, ['add', '-A']);
+    git(d, ['commit', '-m', 'user commit']);
+    const before = git(d, ['rev-list', '--count', 'HEAD']);
+
+    await runInit(d, { skills: false });
+
+    // `d` is still the repo root — init did not nest a new repo under it
+    // (--show-cdup is empty only when cwd IS the toplevel).
+    expect(git(d, ['rev-parse', '--show-cdup'])).toBe('');
+    expect(existsSync(join(d, 'emberflow', 'apis', 'default'))).toBe(true);
+    // init added no commit of its own.
+    expect(git(d, ['rev-list', '--count', 'HEAD'])).toBe(before);
+    // The scaffold is present but uncommitted — the user commits on their terms.
+    expect(git(d, ['status', '--porcelain'])).toContain('emberflow.config.mjs');
+  });
+
+  it('re-running init on an already-scaffolded, non-git dir makes an empty anchor commit (no unborn HEAD)', async () => {
+    const d = scratch();
+    // Pre-scaffold everything init would normally write, as if a prior
+    // `emberflow init --no-git` (or a non-interactive run) already wrote it
+    // and the directory is still not a git repo — exactly what the
+    // checklist's copyable skills command produces.
+    await runInit(d, { skills: false, git: false });
+    expect(existsSync(join(d, '.git'))).toBe(false);
+
+    await runInit(d, { skills: false });
+
+    expect(existsSync(join(d, '.git'))).toBe(true);
+    // HEAD must resolve — an unborn HEAD (git init with zero commits) makes
+    // snapshot.head null downstream, which the agent snapshot/diff/revert
+    // safety net treats as "unrevertable".
+    expect(() => git(d, ['rev-parse', 'HEAD'])).not.toThrow();
+    expect(git(d, ['rev-list', '--count', 'HEAD'])).toBe('1');
+    expect(git(d, ['log', '--oneline'])).toContain('chore: emberflow init (anchor)');
+  });
+
+  it('folds repo-scope skill files into the same init commit as the rest of the scaffold', async () => {
+    const d = scratch();
+    await runInit(d, { skills: { scope: 'repo', home: join(d, '.home-unused') } });
+
+    const tracked = git(d, ['ls-tree', '-r', 'HEAD', '--name-only']).split('\n');
+    expect(tracked).toContain('emberflow.config.mjs');
+    expect(tracked).toContain('.claude/skills/emberflow-basics/SKILL.md');
+  });
+});
+
 describe('tsxResolvable', () => {
   it('returns true when tsx resolves from a project (this repo has it as a devDependency)', () => {
     expect(tsxResolvable(process.cwd())).toBe(true);

package/bin/init.ts

@@ -1,7 +1,8 @@
+import { execFileSync } from 'node:child_process';
 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 { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { detectHarnesses, resolveSkillDirs } from './skillTargets';
 
@@ -148,6 +149,87 @@ function writeFileIfAbsent(path: string, content: string, log: string[]): void {
   log.push(path);
 }
 
+/** Same notion as server/agents/gitScope.ts's isGitRepo: is `cwd` inside a git
+ *  work tree? A plain rev-parse probe — we only need the yes/no. */
+function isInsideGitRepo(cwd: string): boolean {
+  try {
+    return (
+      execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim() === 'true'
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every agent feature is gated on git: AgentRunManager snapshots the tree with
+ * git so changes can be reviewed and reverted (server/agents/runManager.ts).
+ * Nothing else creates the repo, so a freshly-`init`ed folder that isn't already
+ * inside a repo gets one here, with an initial commit of ONLY the files init
+ * scaffolded — never `git add -A`, since a fresh dir may already hold the user's
+ * own uncommitted app code.
+ *
+ * The initial commit is load-bearing, not cosmetic: gitScope restores tracked
+ * files by checking them out of the snapshot commit, and an unborn HEAD (a repo
+ * with zero commits) leaves `snapshot.head` null — so agent edits to any
+ * pre-existing tracked file could not be reverted. The commit gives the safety
+ * net something to diff/revert against.
+ *
+ * Never nests a repo or commits when already inside one. Returns a one-line
+ * human summary of what happened, or null when nothing was done.
+ */
+function initGitRepo(cwd: string, scaffolded: string[]): string | null {
+  if (isInsideGitRepo(cwd)) return null; // pre-existing repo — never nest, never commit
+
+  const git = (args: string[]): void => {
+    execFileSync('git', args, { cwd, stdio: ['ignore', 'ignore', 'pipe'] });
+  };
+
+  git(['init']);
+
+  // Commit ONLY init's own scaffold, by explicit relative path — not `-A`.
+  const paths = [
+    ...new Set(
+      scaffolded
+        .map((p) => relative(cwd, p.replace(/\/+$/, '')))
+        .filter((p) => p.length > 0 && existsSync(join(cwd, p))),
+    ),
+  ];
+  if (paths.length === 0) {
+    // No scaffolded files to commit — most likely a re-run of init on a
+    // directory it already scaffolded (e.g. the checklist's copyable skills
+    // command, run non-interactively, against an existing project). `git init`
+    // alone leaves HEAD unborn, which breaks the agent snapshot safety net
+    // (gitScope reads snapshot.head as null and treats all later edits as
+    // unrevertable) while the git checklist row reports green. An empty anchor
+    // commit gives HEAD a real target with zero files tracked.
+    const commitEmpty = (extra: string[]): void =>
+      git([...extra, 'commit', '--allow-empty', '-m', 'chore: emberflow init (anchor)']);
+    try {
+      commitEmpty([]);
+    } catch {
+      commitEmpty(['-c', 'user.name=Emberflow', '-c', 'user.email=emberflow@localhost']);
+    }
+    return 'initialized a git repository with an empty anchor commit (no scaffolded files to commit)';
+  }
+
+  git(['add', '--', ...paths]);
+  const commit = (extra: string[]): void => git([...extra, 'commit', '-m', 'chore: emberflow init']);
+  try {
+    commit([]);
+  } catch {
+    // No user.name/user.email configured (fresh machine, CI) — the commit is
+    // load-bearing for the agent snapshot safety net, so fall back to a one-off
+    // identity for THIS commit only rather than fail init.
+    commit(['-c', 'user.name=Emberflow', '-c', 'user.email=emberflow@localhost']);
+  }
+  return 'initialized a git repository and committed the scaffold (chore: emberflow init)';
+}
+
 export async function runInit(
   cwd: string,
   opts?: {
@@ -159,6 +241,10 @@ export async function runInit(
     /** Which language to scaffold the config/nodes in. Defaults to javascript
      *  (matches the non-TTY prompt default in bin/commands.ts). */
     language?: 'javascript' | 'typescript';
+    /** Create a git repo + initial commit when the target isn't already inside
+     *  one (agent features need it — see initGitRepo). Defaults to true; the
+     *  `--no-git` flag threads through as false. */
+    git?: boolean;
   }
 ): Promise<number> {
   const written: string[] = [];
@@ -265,6 +351,10 @@ export async function runInit(
     console.log(`[emberflow] created ${path}`);
   }
 
+  // Skills are copied BEFORE the git init/commit below so repo-scope skill
+  // files (e.g. .claude/skills/emberflow-basics/SKILL.md) land in the same
+  // scaffold commit instead of being left untracked.
+  let skillsWritten: string[] = [];
   const skillsOpt = opts?.skills === undefined ? { scope: 'repo' as const, home: homedir() } : opts.skills;
   if (skillsOpt !== false) {
     const pkgRoot = opts?.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -272,7 +362,6 @@ export async function runInit(
     if (existsSync(skillsSrc)) {
       const presence = detectHarnesses(cwd, skillsOpt.home);
       const skillDirs = resolveSkillDirs(presence, skillsOpt.scope, cwd, skillsOpt.home);
-      const skillsWritten: string[] = [];
       for (const dir of skillDirs) {
         copySkillsRecursive(skillsSrc, dir, skillsWritten);
       }
@@ -293,5 +382,22 @@ export async function runInit(
     console.log(JSON.stringify(MCP_SNIPPET, null, 2));
   }
 
+  // Agent features (snapshot/diff/revert) require git — create the repo + an
+  // initial commit of just the scaffold unless the user opted out or is already
+  // inside a repo. Best-effort: a git failure must never fail `init` itself.
+  if (opts?.git !== false) {
+    try {
+      // A `--global` skills install writes into the user's homedir, not the
+      // project — only fold in skill paths that actually live under cwd.
+      const repoScopeSkills = skillsWritten.filter((p) => !relative(cwd, p).startsWith('..'));
+      const summary = initGitRepo(cwd, [...written, ...repoScopeSkills]);
+      if (summary) console.log(`[emberflow] ${summary}`);
+    } catch (err) {
+      console.warn(
+        `[emberflow] could not initialize git (agent features need a repo — run \`git init && git add -A && git commit -m "initial"\`): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
   return 0;
 }

package/dist/bin/commands.d.ts

@@ -6,6 +6,7 @@ export interface ParsedArgs {
     noSkills?: boolean;
     scope?: 'global' | 'repo';
     noLaunch?: boolean;
+    noGit?: boolean;
     mock?: boolean;
     js?: boolean;
     ts?: boolean;

package/dist/bin/commands.js

@@ -24,6 +24,8 @@ export function parseArgs(argv) {
             out.scope = 'repo';
         else if (a === '--no-launch')
             out.noLaunch = true;
+        else if (a === '--no-git')
+            out.noGit = true;
         else if (a === '--mock')
             out.mock = true;
         else if (a === '--js')
@@ -203,9 +205,10 @@ export async function runCommand(p, ctx = defaultCtx) {
                 const mod = (await import('./init.js'));
                 const scope = p.scope ?? (await promptScope());
                 const language = p.js ? 'javascript' : p.ts ? 'typescript' : await promptLanguage();
+                const git = !p.noGit;
                 const code = await mod.runInit(process.cwd(), p.noSkills
-                    ? { skills: false, packageRoot: pkgRoot, language }
-                    : { skills: { scope, home: homedir() }, packageRoot: pkgRoot, language });
+                    ? { skills: false, packageRoot: pkgRoot, language, git }
+                    : { skills: { scope, home: homedir() }, packageRoot: pkgRoot, language, git });
                 if (code !== 0)
                     return code;
                 console.log('');
@@ -244,7 +247,7 @@ export async function runCommand(p, ctx = defaultCtx) {
             }
         }
         default:
-            console.log('Usage: emberflow <dev|serve|mcp|init|run|test|doctor|list-nodes|node-schema|list-workflows|get-workflow|list-environments|login-environment|set-environment-auth|serving|validate|publish|save|create|delete|rename|samples> [--port N] [--project DIR] [--scenario NAME] [--no-skills] [--global|--local] [--no-launch] [--mock] [--js|--ts]\n' +
+            console.log('Usage: emberflow <dev|serve|mcp|init|run|test|doctor|list-nodes|node-schema|list-workflows|get-workflow|list-environments|login-environment|set-environment-auth|serving|validate|publish|save|create|delete|rename|samples> [--port N] [--project DIR] [--scenario NAME] [--no-skills] [--global|--local] [--no-launch] [--no-git] [--mock] [--js|--ts]\n' +
                 '  test [opId] [--environment NAME] [--json]   Run scenario expectations in-process (no runner) — exit 0/1/2\n' +
                 '  doctor [opId] [--fix]                       Diagnose operation(s) in-process (no runner); --fix seeds param defaults — exit 0/1/2');
             return 0;

package/dist/bin/init.d.ts

@@ -14,4 +14,8 @@ export declare function runInit(cwd: string, opts?: {
     /** Which language to scaffold the config/nodes in. Defaults to javascript
      *  (matches the non-TTY prompt default in bin/commands.ts). */
     language?: 'javascript' | 'typescript';
+    /** Create a git repo + initial commit when the target isn't already inside
+     *  one (agent features need it — see initGitRepo). Defaults to true; the
+     *  `--no-git` flag threads through as false. */
+    git?: boolean;
 }): Promise<number>;

package/dist/bin/init.js

@@ -1,7 +1,8 @@
+import { execFileSync } from 'node:child_process';
 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 { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { detectHarnesses, resolveSkillDirs } from './skillTargets.js';
 const MCP_SNIPPET = {
@@ -133,6 +134,80 @@ function writeFileIfAbsent(path, content, log) {
     writeFileSync(path, content);
     log.push(path);
 }
+/** Same notion as server/agents/gitScope.ts's isGitRepo: is `cwd` inside a git
+ *  work tree? A plain rev-parse probe — we only need the yes/no. */
+function isInsideGitRepo(cwd) {
+    try {
+        return (execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim() === 'true');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every agent feature is gated on git: AgentRunManager snapshots the tree with
+ * git so changes can be reviewed and reverted (server/agents/runManager.ts).
+ * Nothing else creates the repo, so a freshly-`init`ed folder that isn't already
+ * inside a repo gets one here, with an initial commit of ONLY the files init
+ * scaffolded — never `git add -A`, since a fresh dir may already hold the user's
+ * own uncommitted app code.
+ *
+ * The initial commit is load-bearing, not cosmetic: gitScope restores tracked
+ * files by checking them out of the snapshot commit, and an unborn HEAD (a repo
+ * with zero commits) leaves `snapshot.head` null — so agent edits to any
+ * pre-existing tracked file could not be reverted. The commit gives the safety
+ * net something to diff/revert against.
+ *
+ * Never nests a repo or commits when already inside one. Returns a one-line
+ * human summary of what happened, or null when nothing was done.
+ */
+function initGitRepo(cwd, scaffolded) {
+    if (isInsideGitRepo(cwd))
+        return null; // pre-existing repo — never nest, never commit
+    const git = (args) => {
+        execFileSync('git', args, { cwd, stdio: ['ignore', 'ignore', 'pipe'] });
+    };
+    git(['init']);
+    // Commit ONLY init's own scaffold, by explicit relative path — not `-A`.
+    const paths = [
+        ...new Set(scaffolded
+            .map((p) => relative(cwd, p.replace(/\/+$/, '')))
+            .filter((p) => p.length > 0 && existsSync(join(cwd, p)))),
+    ];
+    if (paths.length === 0) {
+        // No scaffolded files to commit — most likely a re-run of init on a
+        // directory it already scaffolded (e.g. the checklist's copyable skills
+        // command, run non-interactively, against an existing project). `git init`
+        // alone leaves HEAD unborn, which breaks the agent snapshot safety net
+        // (gitScope reads snapshot.head as null and treats all later edits as
+        // unrevertable) while the git checklist row reports green. An empty anchor
+        // commit gives HEAD a real target with zero files tracked.
+        const commitEmpty = (extra) => git([...extra, 'commit', '--allow-empty', '-m', 'chore: emberflow init (anchor)']);
+        try {
+            commitEmpty([]);
+        }
+        catch {
+            commitEmpty(['-c', 'user.name=Emberflow', '-c', 'user.email=emberflow@localhost']);
+        }
+        return 'initialized a git repository with an empty anchor commit (no scaffolded files to commit)';
+    }
+    git(['add', '--', ...paths]);
+    const commit = (extra) => git([...extra, 'commit', '-m', 'chore: emberflow init']);
+    try {
+        commit([]);
+    }
+    catch {
+        // No user.name/user.email configured (fresh machine, CI) — the commit is
+        // load-bearing for the agent snapshot safety net, so fall back to a one-off
+        // identity for THIS commit only rather than fail init.
+        commit(['-c', 'user.name=Emberflow', '-c', 'user.email=emberflow@localhost']);
+    }
+    return 'initialized a git repository and committed the scaffold (chore: emberflow init)';
+}
 export async function runInit(cwd, opts) {
     const written = [];
     const language = opts?.language ?? 'javascript';
@@ -216,6 +291,10 @@ export async function runInit(cwd, opts) {
     for (const path of written) {
         console.log(`[emberflow] created ${path}`);
     }
+    // Skills are copied BEFORE the git init/commit below so repo-scope skill
+    // files (e.g. .claude/skills/emberflow-basics/SKILL.md) land in the same
+    // scaffold commit instead of being left untracked.
+    let skillsWritten = [];
     const skillsOpt = opts?.skills === undefined ? { scope: 'repo', home: homedir() } : opts.skills;
     if (skillsOpt !== false) {
         const pkgRoot = opts?.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -223,7 +302,6 @@ export async function runInit(cwd, opts) {
         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);
             }
@@ -237,5 +315,21 @@ export async function runInit(cwd, opts) {
         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));
     }
+    // Agent features (snapshot/diff/revert) require git — create the repo + an
+    // initial commit of just the scaffold unless the user opted out or is already
+    // inside a repo. Best-effort: a git failure must never fail `init` itself.
+    if (opts?.git !== false) {
+        try {
+            // A `--global` skills install writes into the user's homedir, not the
+            // project — only fold in skill paths that actually live under cwd.
+            const repoScopeSkills = skillsWritten.filter((p) => !relative(cwd, p).startsWith('..'));
+            const summary = initGitRepo(cwd, [...written, ...repoScopeSkills]);
+            if (summary)
+                console.log(`[emberflow] ${summary}`);
+        }
+        catch (err) {
+            console.warn(`[emberflow] could not initialize git (agent features need a repo — run \`git init && git add -A && git commit -m "initial"\`): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     return 0;
 }

package/dist/server/agents/codexParse.js

@@ -1,3 +1,4 @@
+import { modelRejectionHint } from './modelRejectionHint.js';
 /** Map a codex mcp_tool_call item → an 'mcp' AgentEvent, tolerating shape drift. */
 function mcpEventFrom(item) {
     const server = item.server ?? item.invocation?.server ?? 'mcp';
@@ -6,6 +7,23 @@ function mcpEventFrom(item) {
     const output = raw === undefined ? undefined : typeof raw === 'string' ? raw : JSON.stringify(raw, null, 2);
     return { type: 'mcp', mcpServer: server, mcpTool: tool, mcpStatus: item.status, ...(output !== undefined ? { output } : {}) };
 }
+/**
+ * Codex wraps API failures as JSON-in-a-string: `turn.failed`'s error.message
+ * (and top-level `error`'s message) is often itself a serialized
+ * `{"type":"error","status":400,"error":{"message":"…"}}` payload. Dig out the
+ * innermost human-readable message, falling back to the raw string.
+ */
+function extractCodexErrorMessage(raw) {
+    if (!raw)
+        return 'codex turn failed';
+    try {
+        const inner = JSON.parse(raw);
+        return inner.error?.message ?? inner.message ?? raw;
+    }
+    catch {
+        return raw;
+    }
+}
 export function parseCodexLine(line) {
     const trimmed = line.trim();
     if (!trimmed)
@@ -68,6 +86,19 @@ export function parseCodexLine(line) {
         }
         case 'turn.completed':
             return { type: 'done', usage: parsed.usage };
+        // The turn itself failed (e.g. the API rejected the request) — this IS the
+        // run failing, unlike an `error` ITEM above. Codex exits 1 after emitting
+        // it; without handling it here the adapter can only synthesize a generic
+        // "codex exited with code 1" and the real cause stays buried.
+        case 'turn.failed': {
+            const text = extractCodexErrorMessage(parsed.error?.message);
+            const hint = modelRejectionHint('codex', text);
+            return { type: 'error', text: hint ? `${text} (${hint})` : text };
+        }
+        // Top-level `error` lines precede turn.failed with the same payload —
+        // surface as a visible diagnostic, let turn.failed be the terminal event.
+        case 'error':
+            return { type: 'message', text: `⚠ ${extractCodexErrorMessage(parsed.message)}` };
         default:
             return null;
     }

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

@@ -2,22 +2,32 @@ import type { AgentKind } from './types.js';
 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 declare function probe(bin: string): {
     version: string | null;
 } | undefined;
+/** 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 declare function newer(a: string | null, b: string | null): boolean;
 /**
- * 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 declare function detectAgents(probeBin?: (bin: string) => {
     version: string | null;
 } | undefined): DetectedAgent[];
+/** Cached detection — the newest binary per kind, refreshed every 30s. */
+export declare function detectAgentsCached(): DetectedAgent[];
+/** The concrete binary path spawns should use for `kind` — the newest found. */
+export declare function resolveAgentBin(kind: AgentKind): string | undefined;