@gaia-ai/addon-herdr 0.6.2 → 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

@@ -1,7 +1,7 @@
 import type { EnsuredWorkspace, GaiaWorkspace, WorkspacePlugin } from '@gaia-ai/conductor/contract';
 import type { ConductorLogger } from '@gaia-ai/core';
 import type { AgentLaunchHost } from './agent-host.js';
-import type { PaneSpec } from './config.js';
+import { type PaneSpec } from './config.js';
 import { type RootGitExec } from './root-anchor.js';
 export type HerdrExec = (args: string[]) => Promise<string>;
 export type GitExec = (args: string[]) => Promise<string>;
@@ -10,13 +10,35 @@ export type GitExec = (args: string[]) => Promise<string>;
  * (GAIA-139): `command` launches a tool in the main pane (e.g. `spiceedit`) so
  * the human lands in an editor instead of a bare shell; `panes[]` are optional
  * splits off it. Same shape as the executor's per-state layout minus `tabLabel`
- * — there is only ONE open layout, not a per-ticket-state map. Unset → the bare
- * empty tab opens unchanged (the current good default).
+ * — there is only ONE open layout, not a per-ticket-state map.
+ *
+ * GAIA-234: `{identifier}`, `{branch}` and `{worktreePath}` expand in `command`
+ * **and** in every `panes[].command`. The root command is rendered here, by
+ * `ensure`, before the finished layout reaches `applyPaneLayout` — that shared
+ * helper types its root command VERBATIM on purpose, because its other caller
+ * (the executor) pre-assembles `KEY='value' <agent>` env prefixes whose values
+ * may legitimately contain braces (spec D2).
+ *
+ * Unset → {@link DEFAULT_OPEN_LAYOUT}, the ticket deep link. `{}` → the bare
+ * empty tab (`applyPaneLayout` issues no calls for an empty layout).
  */
 export interface OpenLayout {
     command?: string;
     panes?: PaneSpec[];
 }
+/**
+ * The shipped default open layout (GAIA-234): a fresh worktree's initial pane
+ * renders the ticket it belongs to instead of an anonymous shell prompt.
+ *
+ * It lives in **code, not config**, because a default each repo has to opt into
+ * would leave the defect in place for every other consumer of this addon; the
+ * addon already ships opinionated defaults of this kind (`BUILTIN_DEFAULTS` in
+ * `./config.js`), and `gaia ui` is a command of the very host that ships it.
+ *
+ * `open: {}` is the documented opt-out back to the pre-GAIA-234 bare tab, so
+ * the default is not a one-way door.
+ */
+export declare const DEFAULT_OPEN_LAYOUT: OpenLayout;
 export interface HerdrWorkspaceOptions {
     /** Main clone (a git repo): herdr `--cwd` target + worktree base. */
     root: string;
@@ -30,7 +52,8 @@ export interface HerdrWorkspaceOptions {
     baseBranch?: string;
     /**
      * Startup layout for the initial pane, applied on a FRESH worktree open only
-     * (GAIA-139). Unset → the bare empty tab is left unchanged.
+     * (GAIA-139). Unset → {@link DEFAULT_OPEN_LAYOUT} (`gaia ui --ticket <ID>`,
+     * GAIA-234); `{}` → the bare empty tab is left unchanged.
      */
     open?: OpenLayout;
     /** Overrideable herdr exec fn — defaults to the real `herdr` binary. */
@@ -48,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);
@@ -68,7 +96,38 @@ export declare class HerdrWorkspace implements GaiaWorkspace {
      * Returns the ref when it exists, else undefined so the caller falls back.
      */
     private verifyRemoteRef;
+    /**
+     * 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.
+     */
+    applyOpenLayout(path: string, ctx: {
+        identifier: string;
+        branch: string;
+    }): Promise<void>;
 }
 export declare function herdrWorkspace(opts?: {
     /**
@@ -81,5 +140,7 @@ export declare function herdrWorkspace(opts?: {
     open?: OpenLayout;
     /** Overrideable git exec for root derivation (tests). */
     execGit?: RootGitExec;
+    /** Overrideable herdr exec (tests) — sibling of `execGit`. */
+    execHerdr?: HerdrExec;
 }): WorkspacePlugin;
 export default herdrWorkspace;

package/dist/src/workspace.js

@@ -2,8 +2,24 @@ import { resolve } from 'node:path';
 import { loadInstructions } from '@gaia-ai/addon-workspace-git';
 import { exec } from '@gaia-ai/core';
 import { herdrAgentHost } from './agents.js';
+import { renderTemplate } from './config.js';
 import { applyPaneLayout, isRecord, parseJson } from './pane-layout.js';
 import { deriveHerdrRoot } from './root-anchor.js';
+/**
+ * The shipped default open layout (GAIA-234): a fresh worktree's initial pane
+ * renders the ticket it belongs to instead of an anonymous shell prompt.
+ *
+ * It lives in **code, not config**, because a default each repo has to opt into
+ * would leave the defect in place for every other consumer of this addon; the
+ * addon already ships opinionated defaults of this kind (`BUILTIN_DEFAULTS` in
+ * `./config.js`), and `gaia ui` is a command of the very host that ships it.
+ *
+ * `open: {}` is the documented opt-out back to the pre-GAIA-234 bare tab, so
+ * the default is not a one-way door.
+ */
+export const DEFAULT_OPEN_LAYOUT = {
+    command: 'gaia ui --ticket {identifier}',
+};
 const defaultExec = (args) => exec('herdr', args);
 const defaultGitExec = (args) => exec('git', args);
 const noopLogger = {
@@ -74,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) {
@@ -82,7 +103,8 @@ export class HerdrWorkspace {
         this.execGit = options.execGit ?? defaultGitExec;
         this.root = resolve(options.root);
         this.worktreeDir = options.worktreeDir ?? '.gaia-worktrees';
-        this.open = options.open;
+        // `??`, not `||`: an explicit `open: {}` must survive as the opt-out.
+        this.open = options.open ?? DEFAULT_OPEN_LAYOUT;
         this.logger = options.logger ?? noopLogger;
         this.agentHost = herdrAgentHost(this.execHerdr);
     }
@@ -150,6 +172,17 @@ export class HerdrWorkspace {
             return undefined;
         }
     }
+    /**
+     * 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) {
         if (branch === undefined) {
             throw new Error('herdr workspace requires a branch name');
@@ -214,37 +247,75 @@ export class HerdrWorkspace {
             '--json',
         ]);
         const path = parseWorktreePath(createOutput, 'worktree create');
-        // GAIA-139: on a FRESH create, apply the configured open layout to the
-        // initial root pane (launch e.g. `spiceedit` 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.
-        if (this.open) {
-            try {
-                const rootPaneId = parseWorktreeRootPane(createOutput);
-                if (rootPaneId) {
-                    await applyPaneLayout(this.execHerdr, rootPaneId, this.open, path, {
-                        branch,
-                        worktreePath: path,
-                    });
-                }
-            }
-            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 {
         kind: 'workspace',
         id: 'herdr',
         requiredModules: [],
-        async createWorkspace(config) {
+        // GAIA-234: `deps` carries the conductor logger, so the best-effort
+        // open-layout failure is actually logged instead of vanishing into the noop
+        // logger. Optional per the contract — absent, the noop default stays.
+        async createWorkspace(config, deps) {
             const root = await deriveHerdrRoot(config.config_path, {
                 ...(opts.root !== undefined ? { override: opts.root } : {}),
                 ...(opts.execGit ? { execGit: opts.execGit } : {}),
@@ -254,6 +325,8 @@ export function herdrWorkspace(opts = {}) {
                 ...(opts.worktreeDir ? { worktreeDir: opts.worktreeDir } : {}),
                 ...(opts.baseBranch ? { baseBranch: opts.baseBranch } : {}),
                 ...(opts.open ? { open: opts.open } : {}),
+                ...(opts.execHerdr ? { execHerdr: opts.execHerdr } : {}),
+                ...(deps?.logger ? { logger: deps.logger } : {}),
             });
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/addon-herdr",
-  "version": "0.6.2",
+  "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.2"
+    "@gaia-ai/addon-workspace-git": "^0.6.4"
   },
   "peerDependencies": {
-    "@gaia-ai/conductor": "^0.6.2",
-    "@gaia-ai/core": "^0.6.2"
+    "@gaia-ai/conductor": "^0.6.4",
+    "@gaia-ai/core": "^0.6.4"
   }
 }