@gaia-ai/addon-herdr 0.6.2 → 0.6.3

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. */
@@ -68,7 +91,13 @@ export declare class HerdrWorkspace implements GaiaWorkspace {
      * Returns the ref when it exists, else undefined so the caller falls back.
      */
     private verifyRemoteRef;
-    ensure(_identifier: string, branch?: string, baseRefOverride?: string): Promise<EnsuredWorkspace>;
+    /**
+     * 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(identifier: string, branch?: string, baseRefOverride?: string): Promise<EnsuredWorkspace>;
 }
 export declare function herdrWorkspace(opts?: {
     /**
@@ -81,5 +110,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 = {
@@ -82,7 +98,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,7 +167,13 @@ export class HerdrWorkspace {
             return undefined;
         }
     }
-    async ensure(_identifier, branch, baseRefOverride) {
+    /**
+     * 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`.
+     */
+    async ensure(identifier, branch, baseRefOverride) {
         if (branch === undefined) {
             throw new Error('herdr workspace requires a branch name');
         }
@@ -214,26 +237,33 @@ 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-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)');
+        }
         // 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 };
@@ -244,7 +274,10 @@ export function herdrWorkspace(opts = {}) {
         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 +287,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.3",
   "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.3"
   },
   "peerDependencies": {
-    "@gaia-ai/conductor": "^0.6.2",
-    "@gaia-ai/core": "^0.6.2"
+    "@gaia-ai/conductor": "^0.6.3",
+    "@gaia-ai/core": "^0.6.3"
   }
 }