@gaia-ai/addon-herdr 0.6.3 → 0.6.5

package/dist/src/agents.js

@@ -1,4 +1,4 @@
-import { envArgs, findTabIdByLabel, parsePaneInfo, parsePanesInTab, parseTabCreate, } from './panes.js';
+import { AGENT_SHELL_ENV, envArgs, findTabIdByLabel, parsePaneInfo, parsePanesInTab, parseTabCreate, } from './panes.js';
 /** The single tab that holds a group's agent panes. */
 const groupTabLabel = (group) => `gaia-agents:${group}`;
 export function herdrAgentHost(execHerdr) {
@@ -31,7 +31,11 @@ export function herdrAgentHost(execHerdr) {
     return {
         async launch({ group, cwd, command, env, label }) {
             await captureHome();
-            const e = env ?? {};
+            // Every pane this host opens holds an agent, so all of them carry the
+            // agent-shell marker (GAIA-64) — this is the pane a `gaia ui` user actually
+            // attaches to. The caller's own env wins on a key clash; the marker is
+            // merged in, never substituted for it.
+            const e = { ...AGENT_SHELL_ENV, ...(env ?? {}) };
             // Find the group's tab and split off a LIVE pane (newest-first; a stale
             // pane — a previous agent died/was closed — is skipped). None survive, or
             // no tab yet → create the group tab (its root pane is the agent).

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

@@ -3,6 +3,7 @@ import { exec, shellQuote, slugify } from '@gaia-ai/core';
 import { resolveStateConfig, } from './config.js';
 import { forceRemoveDir, restoreWritable } from './fs.js';
 import { applyPaneLayout, isRecord, parseJson, } from './pane-layout.js';
+import { AGENT_SHELL_ENV, envArgs } from './panes.js';
 import { deriveHerdrRoot } from './root-anchor.js';
 export { herdrAgentHost } from './agents.js';
 export { envArgs, findTabIdByLabel, parsePaneInfo, parsePanesInTab, parseTabCreate, } from './panes.js';
@@ -217,17 +218,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) };
         }
     }
     /**
@@ -579,7 +588,12 @@ export class HerdrExecutor {
             runUuid: input.run.uuid,
             workspacePath: input.workspacePath,
         };
-        // 3. Create tab — NO --json flag; label includes the run-id token
+        // 3. Create tab — NO --json flag; label includes the run-id token. The tab's
+        // root pane IS the agent pane, so it is created carrying the agent-shell
+        // marker: the interactive shell must see it at startup for the user's opt-in
+        // history isolation to fire (GAIA-64). The run's own env (GAIA-99) stays out
+        // of here — it travels as inline `KEY='value'` prefixes on the command, so no
+        // secret moves into the pane environment.
         const { paneId: rootPaneId, tabId } = parseTabCreate(await this.execHerdr([
             'tab',
             'create',
@@ -588,6 +602,7 @@ export class HerdrExecutor {
             '--label',
             `${input.ticket.identifier} · ${input.ticket.state} #${input.run.id}`,
             '--no-focus',
+            ...envArgs(AGENT_SHELL_ENV),
         ]));
         try {
             // 4+5. Run the agent command in the root pane, then split each configured
@@ -595,10 +610,16 @@ export class HerdrExecutor {
             // open pane). The root command embeds `KEY='value'` env prefixes whose
             // values may be secret (GAIA-99); pass a redactor so a failed pane-run
             // exec-log carries key names, never values (only when env is present).
+            // The layout panes belong to the run's tab too, so they are marked as
+            // agent shells as well — the executor opts in, the workspace's open-layout
+            // caller does not (GAIA-64).
             const hasEnv = Object.keys(input.env ?? {}).length > 0;
-            await applyPaneLayout(this.execHerdr, rootPaneId, { command: this.commandFor(input), panes: cfg.panes }, input.workspacePath, vars, hasEnv
-                ? { redactCommand: () => this.redactedCommandFor(input) }
-                : undefined);
+            await applyPaneLayout(this.execHerdr, rootPaneId, { command: this.commandFor(input), panes: cfg.panes }, input.workspacePath, vars, {
+                env: AGENT_SHELL_ENV,
+                ...(hasEnv
+                    ? { redactCommand: () => this.redactedCommandFor(input) }
+                    : {}),
+            });
             // 6. Return branch as sessionRef (for logging)
             return { sessionRef: branchName };
         }

package/dist/src/pane-layout.d.ts

@@ -31,7 +31,15 @@ export interface PaneLayout {
  * `redactArgs` scrubber is passed so a failed `pane run` exec-log never carries a
  * secret, while the command herdr actually runs stays real. An empty layout
  * (`{}`) issues no calls at all — the caller's unconfigured default is preserved.
+ *
+ * `opts.env` is forwarded to each split pane as `--env` args (GAIA_* only, see
+ * {@link envArgs}). It is deliberately per-CALLER rather than baked in: this
+ * primitive serves both the executor's agent tab and the workspace's own open
+ * pane, and only the former's panes are agent-owned (GAIA-64). The ROOT pane is
+ * not touched — it already exists when we get here, so its environment came from
+ * whoever created it. Omitted ⇒ no `--env` at all.
  */
 export declare function applyPaneLayout(execHerdr: HerdrExec, rootPaneId: string, layout: PaneLayout, cwd: string, vars: Record<string, string>, opts?: {
     redactCommand?: (command: string) => string;
+    env?: Record<string, string | undefined>;
 }): Promise<void>;

package/dist/src/pane-layout.js

@@ -1,4 +1,5 @@
 import { renderTemplate } from './config.js';
+import { envArgs } from './panes.js';
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -33,6 +34,13 @@ export function parsePaneSplit(output) {
  * `redactArgs` scrubber is passed so a failed `pane run` exec-log never carries a
  * secret, while the command herdr actually runs stays real. An empty layout
  * (`{}`) issues no calls at all — the caller's unconfigured default is preserved.
+ *
+ * `opts.env` is forwarded to each split pane as `--env` args (GAIA_* only, see
+ * {@link envArgs}). It is deliberately per-CALLER rather than baked in: this
+ * primitive serves both the executor's agent tab and the workspace's own open
+ * pane, and only the former's panes are agent-owned (GAIA-64). The ROOT pane is
+ * not touched — it already exists when we get here, so its environment came from
+ * whoever created it. Omitted ⇒ no `--env` at all.
  */
 export async function applyPaneLayout(execHerdr, rootPaneId, layout, cwd, vars, opts) {
     if (layout.command) {
@@ -58,6 +66,7 @@ export async function applyPaneLayout(execHerdr, rootPaneId, layout, cwd, vars,
             '--cwd',
             cwd,
             spec.focus ? '--focus' : '--no-focus',
+            ...envArgs(opts?.env ?? {}),
         ]));
         await execHerdr([
             'pane',

package/dist/src/panes.d.ts

@@ -7,6 +7,18 @@ export interface HerdrPaneRef {
 export interface HerdrPaneInfo extends HerdrPaneRef {
     label: string;
 }
+/**
+ * Marker exported into an AGENT pane's interactive shell, so a user's opt-in
+ * shell init can recognise an agent-run pane at startup and isolate its history
+ * (GAIA-64). It is a plain `GAIA_*` env entry on purpose: it rides {@link envArgs}
+ * like every other pane var instead of adding a second mechanism.
+ *
+ * AGENT panes only — the executor's per-run tab and its layout panes, plus the
+ * TUI-hosted agents. NOT the workspace's own open-layout pane: that one is the
+ * human's landing pane, and the opt-in unsets `HISTFILE`. See
+ * `docs/conductor/node.md` § Agent-pane shell marker.
+ */
+export declare const AGENT_SHELL_ENV: Record<string, string>;
 /** GAIA_* env vars as `--env KEY=VALUE` args (never dump the full environment). */
 export declare function envArgs(env: Record<string, string | undefined>): string[];
 /** `{ paneId, tabId }` from a `herdr tab create` envelope. */

package/dist/src/panes.js

@@ -4,6 +4,20 @@
 function isRecord(v) {
     return typeof v === 'object' && v !== null;
 }
+/**
+ * Marker exported into an AGENT pane's interactive shell, so a user's opt-in
+ * shell init can recognise an agent-run pane at startup and isolate its history
+ * (GAIA-64). It is a plain `GAIA_*` env entry on purpose: it rides {@link envArgs}
+ * like every other pane var instead of adding a second mechanism.
+ *
+ * AGENT panes only — the executor's per-run tab and its layout panes, plus the
+ * TUI-hosted agents. NOT the workspace's own open-layout pane: that one is the
+ * human's landing pane, and the opt-in unsets `HISTFILE`. See
+ * `docs/conductor/node.md` § Agent-pane shell marker.
+ */
+export const AGENT_SHELL_ENV = {
+    GAIA_AGENT_SHELL: '1',
+};
 /** GAIA_* env vars as `--env KEY=VALUE` args (never dump the full environment). */
 export function envArgs(env) {
     const out = [];

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.5",
   "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.5"
   },
   "peerDependencies": {
-    "@gaia-ai/conductor": "^0.6.3",
-    "@gaia-ai/core": "^0.6.3"
+    "@gaia-ai/conductor": "^0.6.5",
+    "@gaia-ai/core": "^0.6.5"
   }
 }