@gaia-ai/addon-herdr 0.6.3 → 0.6.4

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutorCapabilities, ExecutorPlugin, GaiaExecutor, HookContext, HookName, SpawnedSession, SpawnRunInput } from '@gaia-ai/conductor/contract';
+import type { ExecutorCapabilities, ExecutorPlugin, GaiaExecutor, HookContext, HookName, HookResult, SpawnedSession, SpawnRunInput } from '@gaia-ai/conductor/contract';
 import type { ConductorLogger } from '@gaia-ai/core';
 import { type HerdrExecutorOptions } from './config.js';
 import { type HerdrExec } from './pane-layout.js';
@@ -26,8 +26,14 @@ export declare class HerdrExecutor implements GaiaExecutor {
      * silent no-op. A failing command → log loudly (hook + worktree + ticket +
      * err) and return. NEVER throws, so a hook failure can't abort dispatch or
      * wedge a run.
+     *
+     * GAIA-237: it also RETURNS what happened ({@link HookResult}). Not throwing
+     * kept a hook from wedging a run, but swallowing the outcome entirely left the
+     * caller unable to tell a provisioned worktree from a broken one — so an agent
+     * was dispatched into a worktree whose bootstrap had aborted, with nothing but
+     * a log line (which, on a TTY, went nowhere) to say so.
      */
-    runHook(name: HookName, cwd: string, ctx: HookContext, env?: Record<string, string>): Promise<void>;
+    runHook(name: HookName, cwd: string, ctx: HookContext, env?: Record<string, string>): Promise<HookResult>;
     /**
      * List worktrees, ALWAYS anchored to the configured parent repo root
      * (GAIA-211). `herdr worktree list` is machine-global, but run WITHOUT

package/dist/src/index.js

@@ -217,17 +217,25 @@ export class HerdrExecutor {
      * silent no-op. A failing command → log loudly (hook + worktree + ticket +
      * err) and return. NEVER throws, so a hook failure can't abort dispatch or
      * wedge a run.
+     *
+     * GAIA-237: it also RETURNS what happened ({@link HookResult}). Not throwing
+     * kept a hook from wedging a run, but swallowing the outcome entirely left the
+     * caller unable to tell a provisioned worktree from a broken one — so an agent
+     * was dispatched into a worktree whose bootstrap had aborted, with nothing but
+     * a log line (which, on a TTY, went nowhere) to say so.
      */
     async runHook(name, cwd, ctx, env) {
         const command = this.options.hooks?.[name];
         if (!command) {
-            return;
+            return { hook: name, ran: false, ok: true };
         }
         try {
             await this.runShell(command, cwd, env);
+            return { hook: name, ran: true, ok: true };
         }
         catch (err) {
             this.logger.error({ hook: name, worktree: cwd, ticket: ctx.ticket, err: String(err) }, 'lifecycle hook failed');
+            return { hook: name, ran: true, ok: false, error: String(err) };
         }
     }
     /**

package/dist/src/workspace.d.ts

@@ -71,6 +71,11 @@ export declare class HerdrWorkspace implements GaiaWorkspace {
     private readonly worktreeDir;
     private readonly open;
     private readonly logger;
+    /**
+     * Root pane ids captured by a FRESH `ensure` create, keyed by worktree path,
+     * awaiting {@link applyOpenLayout} (GAIA-237). One-shot: consumed on apply.
+     */
+    private readonly pendingRootPanes;
     /** Herdr-backed intent-level agent host for `gaia ui` (GAIA-190). */
     readonly agentHost: AgentLaunchHost;
     constructor(options: HerdrWorkspaceOptions);
@@ -92,12 +97,37 @@ export declare class HerdrWorkspace implements GaiaWorkspace {
      */
     private verifyRemoteRef;
     /**
-     * Ensure the branch's worktree + herdr workspace exist. `identifier` is the
-     * ticket's human id: it is NOT used to locate the worktree (the branch is),
-     * but it IS the value the open layout's `{identifier}` renders to (GAIA-234),
-     * which is why it is taken as-passed rather than parsed back out of `branch`.
+     * Ensure the branch's worktree + herdr workspace exist.
+     *
+     * `_identifier` is unused HERE: the worktree is located by branch, and since
+     * GAIA-237 the open layout — the one thing that consumed the identifier, to
+     * render `{identifier}` (GAIA-234) — is applied by {@link applyOpenLayout},
+     * which takes it on its own `ctx`. The parameter stays because it is the
+     * `GaiaWorkspace.ensure` contract position (the git workspace does use it).
+     * It is still taken as-passed rather than parsed back out of `branch`, which
+     * remains the reason the contract carries it at all.
+     */
+    ensure(_identifier: string, branch?: string, baseRefOverride?: string): Promise<EnsuredWorkspace>;
+    /**
+     * Apply the open layout to the root pane captured by the most recent
+     * {@link ensure} create for `path` — by default (GAIA-234) the ticket's
+     * `gaia ui` deep link, so the tab shows the ticket instead of a bare shell.
+     * The pane's cwd is the worktree checkout, passed explicitly on the splits
+     * (the root pane's cwd is already the checkout).
+     *
+     * NO stored pane ⇒ silent no-op. That is the reused-worktree case: `ensure`
+     * took the reuse branch, there is no fresh root pane, and re-applying would
+     * start a duplicate editor process on reattach (GAIA-139). The capture is
+     * one-shot — consumed here — so a repeat call cannot double-apply and the map
+     * cannot grow without bound.
+     *
+     * Best-effort — mirrors the `fetchBaseRef` pattern: a broken layout is logged
+     * and swallowed so a startup-command failure can NEVER wedge dispatch.
      */
-    ensure(identifier: string, branch?: string, baseRefOverride?: string): Promise<EnsuredWorkspace>;
+    applyOpenLayout(path: string, ctx: {
+        identifier: string;
+        branch: string;
+    }): Promise<void>;
 }
 export declare function herdrWorkspace(opts?: {
     /**

package/dist/src/workspace.js

@@ -90,6 +90,11 @@ export class HerdrWorkspace {
     worktreeDir;
     open;
     logger;
+    /**
+     * Root pane ids captured by a FRESH `ensure` create, keyed by worktree path,
+     * awaiting {@link applyOpenLayout} (GAIA-237). One-shot: consumed on apply.
+     */
+    pendingRootPanes = new Map();
     /** Herdr-backed intent-level agent host for `gaia ui` (GAIA-190). */
     agentHost;
     constructor(options) {
@@ -168,12 +173,17 @@ export class HerdrWorkspace {
         }
     }
     /**
-     * Ensure the branch's worktree + herdr workspace exist. `identifier` is the
-     * ticket's human id: it is NOT used to locate the worktree (the branch is),
-     * but it IS the value the open layout's `{identifier}` renders to (GAIA-234),
-     * which is why it is taken as-passed rather than parsed back out of `branch`.
+     * Ensure the branch's worktree + herdr workspace exist.
+     *
+     * `_identifier` is unused HERE: the worktree is located by branch, and since
+     * GAIA-237 the open layout — the one thing that consumed the identifier, to
+     * render `{identifier}` (GAIA-234) — is applied by {@link applyOpenLayout},
+     * which takes it on its own `ctx`. The parameter stays because it is the
+     * `GaiaWorkspace.ensure` contract position (the git workspace does use it).
+     * It is still taken as-passed rather than parsed back out of `branch`, which
+     * remains the reason the contract carries it at all.
      */
-    async ensure(identifier, branch, baseRefOverride) {
+    async ensure(_identifier, branch, baseRefOverride) {
         if (branch === undefined) {
             throw new Error('herdr workspace requires a branch name');
         }
@@ -237,37 +247,65 @@ export class HerdrWorkspace {
             '--json',
         ]);
         const path = parseWorktreePath(createOutput, 'worktree create');
-        // GAIA-139: on a FRESH create, apply the open layout to the initial root
-        // pane — by default (GAIA-234) the ticket's `gaia ui` deep link, so the tab
-        // shows the ticket instead of a bare shell. The pane's cwd is the worktree
-        // checkout, passed explicitly on the splits (the root pane's cwd is already
-        // the checkout). Best-effort — mirrors the `fetchBaseRef` pattern above: a
-        // broken layout is logged and swallowed so a startup-command failure can
-        // NEVER wedge worktree creation / run dispatch.
-        try {
-            const rootPaneId = parseWorktreeRootPane(createOutput);
-            if (rootPaneId) {
-                // Render the ROOT command here (spec D2). `applyPaneLayout` types its
-                // root command verbatim for the executor's brace-bearing env-prefixed
-                // agent command, so templating it there would corrupt that; the split
-                // commands it already renders from the same `vars`.
-                const vars = { identifier, branch, worktreePath: path };
-                const layout = {
-                    ...this.open,
-                    ...(this.open.command !== undefined
-                        ? { command: renderTemplate(this.open.command, vars) }
-                        : {}),
-                };
-                await applyPaneLayout(this.execHerdr, rootPaneId, layout, path, vars);
-            }
-        }
-        catch (err) {
-            this.logger.warn({ branch, worktree: path, err: String(err) }, 'herdr open-layout failed (best-effort, ignored)');
+        // GAIA-237: CAPTURE the fresh root pane here, but do NOT lay it out yet.
+        // The layout's startup command names the gaia CLI, which the `after_create`
+        // hook builds — and that hook runs after `ensure()` returns. Applying the
+        // layout here fired the command before its binary existed, which is why the
+        // pane command needed a sentinel wait loop. The conductor now calls
+        // `applyOpenLayout` after the hook; a create with no root pane in its output
+        // stores nothing, so the layout is a no-op exactly as before.
+        const rootPaneId = parseWorktreeRootPane(createOutput);
+        if (rootPaneId) {
+            this.pendingRootPanes.set(path, rootPaneId);
         }
         // The `after_create` hook is run by the executor (GAIA-84), not here — the
         // workspace only reports that it created a fresh worktree.
         return { path, instructions: loadInstructions(path), created: true };
     }
+    /**
+     * Apply the open layout to the root pane captured by the most recent
+     * {@link ensure} create for `path` — by default (GAIA-234) the ticket's
+     * `gaia ui` deep link, so the tab shows the ticket instead of a bare shell.
+     * The pane's cwd is the worktree checkout, passed explicitly on the splits
+     * (the root pane's cwd is already the checkout).
+     *
+     * NO stored pane ⇒ silent no-op. That is the reused-worktree case: `ensure`
+     * took the reuse branch, there is no fresh root pane, and re-applying would
+     * start a duplicate editor process on reattach (GAIA-139). The capture is
+     * one-shot — consumed here — so a repeat call cannot double-apply and the map
+     * cannot grow without bound.
+     *
+     * Best-effort — mirrors the `fetchBaseRef` pattern: a broken layout is logged
+     * and swallowed so a startup-command failure can NEVER wedge dispatch.
+     */
+    async applyOpenLayout(path, ctx) {
+        const rootPaneId = this.pendingRootPanes.get(path);
+        if (!rootPaneId) {
+            return;
+        }
+        this.pendingRootPanes.delete(path);
+        try {
+            // Render the ROOT command here (spec D2). `applyPaneLayout` types its
+            // root command verbatim for the executor's brace-bearing env-prefixed
+            // agent command, so templating it there would corrupt that; the split
+            // commands it already renders from the same `vars`.
+            const vars = {
+                identifier: ctx.identifier,
+                branch: ctx.branch,
+                worktreePath: path,
+            };
+            const layout = {
+                ...this.open,
+                ...(this.open.command !== undefined
+                    ? { command: renderTemplate(this.open.command, vars) }
+                    : {}),
+            };
+            await applyPaneLayout(this.execHerdr, rootPaneId, layout, path, vars);
+        }
+        catch (err) {
+            this.logger.warn({ branch: ctx.branch, worktree: path, err: String(err) }, 'herdr open-layout failed (best-effort, ignored)');
+        }
+    }
 }
 export function herdrWorkspace(opts = {}) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/addon-herdr",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "GAIA herdr integration: spawn executor + per-ticket worktree workspace.",
   "type": "module",
   "license": "MIT",
@@ -20,10 +20,10 @@
     "directory": "gaia-cli/addons/herdr"
   },
   "dependencies": {
-    "@gaia-ai/addon-workspace-git": "^0.6.3"
+    "@gaia-ai/addon-workspace-git": "^0.6.4"
   },
   "peerDependencies": {
-    "@gaia-ai/conductor": "^0.6.3",
-    "@gaia-ai/core": "^0.6.3"
+    "@gaia-ai/conductor": "^0.6.4",
+    "@gaia-ai/core": "^0.6.4"
   }
 }