@gaia-ai/conductor 0.6.2 → 0.6.4

package/dist/src/commands/conductor.js

@@ -192,7 +192,7 @@ async function cmdPoll(deps, log = {}) {
         return;
     const remote = await resolveRemote(deps, config);
     const executor = deps.executor ?? (await selectExecutor(config, logger));
-    const workspace = deps.workspace ?? (await selectWorkspace(config));
+    const workspace = deps.workspace ?? (await selectWorkspace(config, logger));
     const agents = deps.agents ?? (await selectAgents(config));
     const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot);
     await conductor.start();
@@ -206,7 +206,7 @@ async function cmdReap(deps, log = {}) {
         return;
     const remote = await resolveRemote(deps, config);
     const executor = deps.executor ?? (await selectExecutor(config, logger));
-    const workspace = deps.workspace ?? (await selectWorkspace(config));
+    const workspace = deps.workspace ?? (await selectWorkspace(config, logger));
     const agents = deps.agents ?? (await selectAgents(config));
     const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot);
     await conductor.reap();
@@ -219,7 +219,7 @@ async function cmdStartForeground(deps, log = {}) {
         return;
     const remote = await resolveRemote(deps, config);
     const executor = deps.executor ?? (await selectExecutor(config, logger));
-    const workspace = deps.workspace ?? (await selectWorkspace(config));
+    const workspace = deps.workspace ?? (await selectWorkspace(config, logger));
     const agents = deps.agents ?? (await selectAgents(config));
     const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot);
     await conductor.start();
@@ -383,13 +383,14 @@ export function createConductorCommand(deps) {
     const conductor = new Command('conductor')
         .description('node-agent lifecycle + local registry')
         .option('--log-level <level>', 'log verbosity: debug | info | warn | error (overrides GAIA_LOG_LEVEL)')
-        .option('--log-sink <sink>', 'log sink: stdout | file (overrides GAIA_CONDUCTOR_LOG)')
+        .option('--log-sink <sink>', 'log sink: stdout | file | both (overrides GAIA_CONDUCTOR_LOG)')
         .addHelpText('after', `
 Logging (precedence: CLI flag > env var > default):
   --log-level <level>  debug | info (default) | warn | error.
                        Set debug to see per-poll ticks, claims, and idle cycles.
-  --log-sink <sink>    stdout | file (writes <checkoutRoot>/log.txt).
-                       Default: stdout on a TTY, file otherwise.
+  --log-sink <sink>    stdout | file | both (file/both write <checkoutRoot>/log.txt).
+                       Default: both on a TTY, file otherwise (GAIA-237 — a run in a
+                       herdr pane is on a TTY, and its diagnostics must outlive the pane).
   GAIA_LOG_LEVEL       env fallback for --log-level.
   GAIA_CONDUCTOR_LOG   env fallback for --log-sink.
 

package/dist/src/contract.d.ts

@@ -1,5 +1,5 @@
 export { type AgentFootprint, emptyAgentFootprint, type GaiaAgent, } from './plugins/agent.js';
-export type { ExecutorCapabilities, GaiaExecutor, HookContext, HookName, SpawnedSession, SpawnRunInput, } from './plugins/executor.js';
+export type { ExecutorCapabilities, GaiaExecutor, HookContext, HookName, HookResult, SpawnedSession, SpawnRunInput, } from './plugins/executor.js';
 export type { AgentCandidate, AgentPlugin, ExecutorDeps, ExecutorPlugin, RemotePlugin, ResolvedAgent, WorkspacePlugin, } from './plugins/plugins.js';
 export { selectAgent, selectAgents, selectExecutor, selectRemote, selectWorkspace, } from './plugins/plugins.js';
 export { type ConductorAddonEntry, type ConductorContributions, narrowConductorContributions, type Preset, } from './plugins/preset.js';

package/dist/src/core/conductor.js

@@ -380,11 +380,53 @@ export class Conductor {
         }
         // Lifecycle hooks are executor-owned + best-effort (GAIA-84): runHook never
         // throws, so neither call can abort dispatch or wedge a run in `claimed`.
-        // after_create only on a freshly-created worktree; before_run always. Both
-        // get the resolved run env so a setup/pre hook sees the same vars (e.g. a DB
-        // DSN) the agent does (GAIA-99).
+        // Both get the resolved run env so a setup/pre hook sees the same vars (e.g.
+        // a DB DSN) the agent does (GAIA-99).
+        //
+        // GAIA-237: `after_create` runs on EVERY dispatch, not only when
+        // `ws.created`. `created` answers "was this worktree born just now?", which
+        // is not the question dispatch needs answered — a worktree whose bootstrap
+        // aborted, an interrupted earlier run, or a hand-made `git worktree add` all
+        // exist WITHOUT being provisioned, and under the creation gate they never got
+        // another chance. Provisioning is therefore convergent: run the hook and let
+        // the hook decide. Keeping the repeat cheap is the HOOK's job (gaia's
+        // `.ddev/worktree-post.sh` short-circuits on its own sentinel) — the
+        // conductor deliberately learns no project-specific "is it provisioned?"
+        // marker, which is exactly why the gate cannot live here.
+        const provisioning = await this.executor.runHook('after_create', ws.path, { ticket: t.identifier }, env);
+        // AC-6: an agent is never dispatched into a worktree whose bootstrap failed
+        // without that being visible. Dispatch is NOT withheld — runHook's
+        // never-throw contract exists so a hook cannot wedge a run, and withholding
+        // would re-introduce that wedge — so the failure is recorded against the run
+        // instead (ticket + run + hook + workspace + err) and the run proceeds.
+        // Boundedness stays with the existing circuit breaker.
+        if (!provisioning.ok) {
+            this.logger.error({
+                hook: provisioning.hook,
+                ticket: t.identifier,
+                run: run.runUuid,
+                workspace: ws.path,
+                err: provisioning.error,
+            }, 'lifecycle hook failed');
+        }
+        // GAIA-237: apply the workspace's open layout HERE — after `after_create`,
+        // before the run starts. The layout's startup command names the gaia CLI
+        // that `after_create` builds; applied inside `workspace.ensure()` (where it
+        // used to live) it necessarily fired first, so a self-hosting checkout had
+        // to paper over the ordering with a sentinel wait loop inside the pane
+        // command. Ordering the two correctly removes the need for any handshake.
+        //
+        // Gated on `ws.created` — DELIBERATELY narrower than the `after_create` gate
+        // right above it, which is convergent (a worktree can exist without ever
+        // having been provisioned). Only a fresh create has an initial pane to lay
+        // out; re-applying on reuse would start a duplicate editor on reattach.
+        // Optional on the contract, so a workspace with no layout concept is a
+        // no-op. Best-effort by contract: implementations swallow their own errors.
         if (ws.created) {
-            await this.executor.runHook('after_create', ws.path, { ticket: t.identifier }, env);
+            await this.workspace.applyOpenLayout?.(ws.path, {
+                identifier: t.identifier,
+                branch: t.branchName,
+            });
         }
         await this.executor.runHook('before_run', ws.path, { ticket: t.identifier }, env);
         // Clear a leftover tab for THIS run id in a reused workspace before

package/dist/src/plugins/executor.d.ts

@@ -34,6 +34,24 @@ export interface HookContext {
     /** The ticket identifier/uuid the hook is running for (log context). */
     ticket: string;
 }
+/**
+ * What a lifecycle hook invocation DID (GAIA-237). `runHook` still never throws,
+ * but it no longer swallows the outcome silently: it reports it, so a caller can
+ * record a failed provisioning hook against the run it is about to dispatch
+ * instead of relying on a log line to survive (AC-6). Reporting — rather than
+ * throwing — keeps the never-wedge property that the never-throw contract exists
+ * for; boundedness stays with the conductor's circuit breaker.
+ */
+export interface HookResult {
+    /** The hook slot that was invoked. */
+    hook: HookName;
+    /** false when no command is configured for the slot — nothing ran. */
+    ran: boolean;
+    /** false ONLY when a configured command actually failed. */
+    ok: boolean;
+    /** The stringified failure; present iff `ok` is false. */
+    error?: string;
+}
 export interface GaiaExecutor {
     id: string;
     capabilities(): ExecutorCapabilities;
@@ -47,13 +65,16 @@ export interface GaiaExecutor {
      *   `claimed`.
      * - The underlying shell command still fails honestly (a non-zero exit
      *   rejects); only the executor catches + logs + continues.
+     * - MUST report the outcome as a {@link HookResult} (GAIA-237): never throwing
+     *   is not the same as never telling. The caller decides what a failure means
+     *   for the run it is dispatching; the executor only refuses to abort.
      *
      * `env`, when given, is the run's resolved environment (per-ticket env_vars
      * merged with the core GAIA_* vars, GAIA-99), merged over the hook process's
      * inherited env. Values may be sensitive — implementations must never log
      * them (log key names only).
      */
-    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>;
     startRun(input: SpawnRunInput): Promise<SpawnedSession>;
     /**
      * Signal the run's agent to stop. Called by the conductor's run-finalise pass

package/dist/src/plugins/plugins.d.ts

@@ -26,7 +26,15 @@ export interface WorkspacePlugin extends DropSHPlugin {
     readonly kind: 'workspace';
     readonly id: string;
     readonly requiredModules: string[];
-    createWorkspace(config: ConductorFileConfig): Promise<GaiaWorkspace>;
+    /**
+     * GAIA-234: `deps` is **optional** so every existing workspace plugin
+     * (`addon-workspace-git`, `addon-fake`) keeps compiling untouched — a
+     * workspace that logs nothing simply ignores it. It reuses {@link ExecutorDeps}
+     * rather than minting a `WorkspaceDeps` alias: that interface is already the
+     * contract's name for "runtime deps handed to a plugin factory", and a second
+     * identical shape would be two names for one thing.
+     */
+    createWorkspace(config: ConductorFileConfig, deps?: ExecutorDeps): Promise<GaiaWorkspace>;
 }
 export interface AgentPlugin extends DropSHPlugin {
     readonly kind: 'agent';
@@ -38,8 +46,13 @@ export interface AgentPlugin extends DropSHPlugin {
 export declare function selectRemote(config: ConductorFileConfig): Promise<GaiaRemote>;
 /** Resolves the executor from its named config slot, injecting the logger. */
 export declare function selectExecutor(config: ConductorFileConfig, logger: ConductorLogger): Promise<GaiaExecutor>;
-/** Resolves the workspace from its named config slot. */
-export declare function selectWorkspace(config: ConductorFileConfig): Promise<GaiaWorkspace>;
+/**
+ * Resolves the workspace from its named config slot, injecting the logger when
+ * the caller has one — mirroring {@link selectExecutor}. Without it the herdr
+ * workspace's best-effort open-layout warn would land on a noop logger
+ * (GAIA-234).
+ */
+export declare function selectWorkspace(config: ConductorFileConfig, logger?: ConductorLogger): Promise<GaiaWorkspace>;
 /** A config-side agent choice: an agent plugin + an optional static priority over the ticket. */
 export interface AgentCandidate {
     agent: AgentPlugin;

package/dist/src/plugins/plugins.js

@@ -6,9 +6,14 @@ export async function selectRemote(config) {
 export async function selectExecutor(config, logger) {
     return config.executor.createExecutor(config, { logger });
 }
-/** Resolves the workspace from its named config slot. */
-export async function selectWorkspace(config) {
-    return config.workspace.createWorkspace(config);
+/**
+ * Resolves the workspace from its named config slot, injecting the logger when
+ * the caller has one — mirroring {@link selectExecutor}. Without it the herdr
+ * workspace's best-effort open-layout warn would land on a noop logger
+ * (GAIA-234).
+ */
+export async function selectWorkspace(config, logger) {
+    return config.workspace.createWorkspace(config, logger ? { logger } : undefined);
 }
 /** A missing `priority` scores strictly below any real number (AC-4). */
 const DEFAULT_PRIORITY = Number.NEGATIVE_INFINITY;

package/dist/src/plugins/workspace.d.ts

@@ -32,4 +32,34 @@ export interface GaiaWorkspace {
      * anymore — the executor owns all hooks (GAIA-84).
      */
     ensure(identifier: string, branch?: string, baseRef?: string): Promise<EnsuredWorkspace>;
+    /**
+     * Apply the workspace's "open" layout — for a hosted workspace, the startup
+     * command(s) of the freshly created workspace's initial pane.
+     *
+     * OPTIONAL: a workspace with no layout concept (git, fake) simply omits it and
+     * the conductor calls it with `?.`.
+     *
+     * GAIA-237 — why this is a SEPARATE call and not part of `ensure()`. The
+     * layout's startup command typically names the gaia CLI, which the
+     * `after_create` lifecycle hook builds. Applied inside `ensure()` it
+     * necessarily ran BEFORE that hook, so in a self-hosting checkout the command
+     * fired minutes before the binary it names existed. The only remedy available
+     * to a config author was a cross-process handshake — a sentinel wait loop
+     * inside the pane command itself. Splitting the call lets the conductor order
+     * the two correctly (`after_create` → `applyOpenLayout`), which removes the
+     * need for any handshake.
+     *
+     * The conductor calls this ONLY on a freshly created workspace
+     * ({@link EnsuredWorkspace.created}), because only a fresh create has an
+     * initial pane to lay out; re-applying on reuse would start a duplicate editor
+     * process on every reattach. Deliberately a NARROWER gate than the one on
+     * `after_create`, which is convergent and runs on every dispatch.
+     *
+     * Best-effort by contract: implementations log and swallow a failing layout so
+     * it can never wedge dispatch.
+     */
+    applyOpenLayout?(path: string, ctx: {
+        identifier: string;
+        branch: string;
+    }): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/conductor",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "GAIA conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "directory": "gaia-cli/conductor"
   },
   "dependencies": {
-    "@gaia-ai/core": "^0.6.2",
+    "@gaia-ai/core": "^0.6.4",
     "@dropsh/plugin-oauth2": "^0.5.7",
     "@dropsh/plugin-jsonapi-schema": "^0.5.8",
     "commander": "^12.1.0",