fix: run postcreate hook before tmux startup

Author: centdix

README.md

@@ -171,12 +171,12 @@ lifecycleHooks:
 | `startupEnvs.<KEY>` | string or boolean | no | Extra env vars materialized into worktree runtime env |
 | `auto_name.model` | string | no | Model used to generate the branch name when the branch field is left empty; supports Anthropic (`claude-*`), Gemini (`gemini-*`), and OpenAI (`gpt-*`, `chatgpt-*`, `o*`) models |
 | `auto_name.system_prompt` | string | no | System prompt sent to the auto-name model |
-| `lifecycleHooks.postCreate` | string | no | Shell command run after a managed worktree is created and its session is materialized |
+| `lifecycleHooks.postCreate` | string | no | Shell command run after a managed worktree is created and its runtime env is materialized, but before the tmux session/panes are started |
 | `lifecycleHooks.preRemove` | string | no | Shell command run before a managed worktree is removed |
 
 </details>
 
-Lifecycle hooks run with the worktree as `cwd` and receive the same computed runtime env as the managed panes, including `startupEnvs`, allocated service ports, and `WEBMUX_*` metadata.
+Lifecycle hooks run with the worktree as `cwd` and receive the same computed runtime env that the managed panes will use, including `startupEnvs`, allocated service ports, and `WEBMUX_*` metadata.
 
 When `auto_name` is enabled, `webmux` calls the provider API directly with structured output and uses `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `OPENAI_API_KEY` based on the configured model.
 

backend/src/__tests__/lifecycle-service.test.ts

@@ -109,11 +109,16 @@ class FakePortProbe implements PortProbe {
 class FakeHookRunner implements LifecycleHookRunner {
   readonly calls: RunLifecycleHookInput[] = [];
 
+  constructor(
+    private readonly onRun?: (input: RunLifecycleHookInput) => void,
+  ) {}
+
   async run(input: RunLifecycleHookInput): Promise<void> {
     this.calls.push({
       ...input,
       env: { ...input.env },
     });
+    this.onRun?.(input);
   }
 }
 
@@ -277,7 +282,9 @@ describe("LifecycleService", () => {
     const repoRoot = await initRepo();
     const runtime = new ProjectRuntime();
     const tmux = new FakeTmuxGateway();
-    const hooks = new FakeHookRunner();
+    const hooks = new FakeHookRunner(() => {
+      expect(tmux.listWindows()).toEqual([]);
+    });
     const lifecycle = makeLifecycleService(repoRoot, tmux, runtime, new FakeDockerGateway(), hooks);
 
     const created = await lifecycle.createWorktree({

backend/src/services/lifecycle-service.ts

@@ -126,6 +126,13 @@ export class LifecycleService {
         worktreePath,
       });
 
+      await this.runLifecycleHook({
+        name: "postCreate",
+        command: this.deps.config.lifecycleHooks.postCreate,
+        meta: initialized.meta,
+        worktreePath,
+      });
+
       await this.materializeRuntimeSession({
         branch,
         profile,
@@ -135,13 +142,6 @@ export class LifecycleService {
         prompt: input.prompt,
       });
 
-      await this.runLifecycleHook({
-        name: "postCreate",
-        command: this.deps.config.lifecycleHooks.postCreate,
-        meta: initialized.meta,
-        worktreePath,
-      });
-
       await this.deps.reconciliation.reconcile(this.deps.projectRoot);
 
       return {