baxian 1.2.21 → 1.2.23

package/dist/agent/manager.js

@@ -13,7 +13,7 @@ import { WorktreeManager } from './worktree.js';
 import { RepoStore, createRepoStoreCache } from './repo-store.js';
 import { PhaseSignalWatcher } from './phase-signal-watcher.js';
 import { ReviewTransport } from './review-transport.js';
-import { buildPromptInline, buildPostMergeCleanupPrompt, PromptSizeError, RequiredSkillsMissingError, MAX_PROMPT_BYTES_ROUTE_LIMIT, } from './prompt.js';
+import { buildPromptInline, buildGreetingPrompt, buildPostMergeCleanupPrompt, PromptSizeError, RequiredSkillsMissingError, MAX_PROMPT_BYTES_ROUTE_LIMIT, } from './prompt.js';
 import { ApiError } from '../errors.js';
 import { prepareConfig } from '../config/loader.js';
 export class EnsureSessionError extends Error {
@@ -53,7 +53,7 @@ export function buildLaunchCommand(agent) {
     const segments = [];
     switch (agent.runtime) {
         case 'claude-code':
-            segments.push('env CLAUDE_CODE_NO_FLICKER=1 claude --permission-mode bypassPermissions');
+            segments.push('env CLAUDE_CODE_NO_FLICKER=1 CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1 claude --permission-mode bypassPermissions');
             break;
         case 'codex':
             segments.push('codex --dangerously-bypass-approvals-and-sandbox');
@@ -123,10 +123,16 @@ function cancelPhaseDowngrades(prev, next) {
 // A prompt line still holding the typed `/clear` (e.g. `❯ /clear`, `› /clear`) = the Enter was swallowed,
 // so /clear was never submitted. After a real submission /clear wipes the screen and the composer is empty.
 const CLEAR_PENDING_IN_COMPOSER_RE = /(?:^|\n)[ \t]*[❯>›→][ \t]*\/clear\b/;
+// A greeting capability failure is NOT cleared by a plain Resume or by recover()'s auto-release:
+// the agent must re-prove it can signal (restart/retry re-runs the handshake). Auto-releasing it
+// would slip an unverified agent back to dispatchable, defeating the whole bootstrap gate.
+const REGREET_REQUIRED_HOLD_PHASES = new Set(['greeting_failed']);
 // Resume / recover 共用：决定 Held agent 的 binding 是否随状态恢复一起清掉。
 export function shouldReleaseHeldBinding(state, boundTask) {
     if (state.awaitingPhase != null && UNCLEARED_PANE_PHASES.has(state.awaitingPhase))
         return false;
+    if (state.awaitingPhase != null && REGREET_REQUIRED_HOLD_PHASES.has(state.awaitingPhase))
+        return false;
     const taskIsTerminal = !!boundTask && TERMINAL_STATUSES.includes(boundTask.status);
     const turnCompleted = state.awaitingPhase != null && TURN_COMPLETED_AWAITING_PHASES.has(state.awaitingPhase);
     return !boundTask || taskIsTerminal || turnCompleted;
@@ -167,6 +173,9 @@ export class AgentManager {
     platformRunner;
     imageStagingRoot;
     bootstrapTimeoutsMs;
+    // Bootstrap greeting handshake: total attempts before holding the agent, to absorb a
+    // single transient slow/garbled reply without failing a genuinely capable agent.
+    greetingMaxAttempts = 2;
     runtimeMenuWatchers = new Map();
     runtimeMenuPollIntervalMs = 10_000;
     compactIdleWaitMs = 5 * 60_000;
@@ -228,6 +237,7 @@ export class AgentManager {
         this.bootstrapTimeoutsMs = {
             trustDialog: deps.bootstrapTimeoutsMs?.trustDialog ?? 10_000,
             waitReplReady: deps.bootstrapTimeoutsMs?.waitReplReady ?? 30_000,
+            greeting: deps.bootstrapTimeoutsMs?.greeting ?? 120_000,
         };
     }
     withTaskLock(fn) {
@@ -583,6 +593,22 @@ export class AgentManager {
         };
         try {
             const result = await this.ensureSession(agentId, 'create');
+            // Capability gate: hold the agent until it proves (via the baxian-signals skill)
+            // that it can load skills and echo a valid greeting signal back through its pane.
+            // A non-greeting agent that reached 'ok' would silently hang on its first real signal.
+            if (!(await this.runGreetingHandshake(agentId, cfgAtStart, result.paneId))) {
+                // A newer create may have rotated creationToken during the (slow) greeting wait.
+                // Mirror the success token-mismatch path: kill the orphan session we created so the
+                // next generation's `create` doesn't trip on a pre-existing tmux session.
+                const current = await this.agentStore.get(agentId);
+                if (current && current.creationToken !== creationToken) {
+                    console.warn(`[bootstrap] ${agentId} creationToken changed during greeting — killing orphan session`);
+                    await tryKillOrphanSession('greeting-failure token mismatch');
+                    return;
+                }
+                await this.markGreetingFailed(agentId, creationToken);
+                return;
+            }
             let resolvedExisting = null;
             const now = new Date().toISOString();
             await this.agentStore.update(agentId, (existing) => {
@@ -635,10 +661,144 @@ export class AgentManager {
             await this.markBootstrapFailed(agentId, creationToken, message);
         }
     }
+    // Bootstrap capability handshake: inject the greeting prompt and wait for the agent to
+    // echo [bx:greeting:<token>] per the baxian-signals skill. Returns true on a verified
+    // echo, false on timeout / lost session across all attempts. No task binding exists yet,
+    // so this drives the low-level inject + the pane-scoped awaitOnce directly.
+    async runGreetingHandshake(agentId, agent, paneId) {
+        const watcher = this.phaseSignalWatcher;
+        if (!watcher)
+            return true; // no watcher wired (minimal harness) — nothing to gate on
+        const tmux = new TmuxManager(this.createRunnerFor(agent));
+        for (let attempt = 1; attempt <= this.greetingMaxAttempts; attempt++) {
+            const token = createSignalToken();
+            try {
+                // Inject FIRST, then arm the wait: if the paste fails the agent never sees the
+                // prompt and cannot echo, so skip the (default 120s) wait entirely and retry.
+                await this.injectAndAwaitAckSteps(tmux, paneId, buildGreetingPrompt(token, agent.runtime), agentId, agent.runtime);
+            }
+            catch (err) {
+                console.warn(`[bootstrap] greeting inject failed for ${agentId} (attempt ${attempt}):`, err);
+                // ack_unknown = injectAndAwaitAckSteps could NOT confirm the composer was cleared, so the
+                // next paste would land on a live/unconfirmed input stream. Hold rather than concatenate.
+                // A raw (non-ack_unknown) throw means the composer was already C-c'd → safe to retry.
+                if (err instanceof DispatchTerminalError && err.reason === 'ack_unknown')
+                    break;
+                continue;
+            }
+            const outcome = await watcher.awaitOnce({
+                agentId,
+                kind: 'greeting',
+                token,
+                timeoutMs: this.bootstrapTimeoutsMs.greeting,
+            });
+            if (outcome === 'matched')
+                return true;
+            console.warn(`[bootstrap] greeting attempt ${attempt}/${this.greetingMaxAttempts} for ${agentId}: ${outcome}`);
+            // 'no-agent' = config removed, unrecoverable. 'timeout'/'session-gone' (incl. a transient
+            // subscribe fault disguised as session-gone) keep the remaining retries — a one-off pane
+            // jitter must not fail a genuinely capable agent.
+            if (outcome === 'no-agent')
+                break;
+            // An ack-timeout paste returns acked:false and leaves the unsubmitted greeting prompt in the
+            // composer; the next injectPrompt would concatenate onto it. Clear it before retrying — if the
+            // composer can't be confirmed clean, hold rather than paste onto a dirty/unsafe one.
+            if (attempt < this.greetingMaxAttempts && !(await this.clearComposerForReuse(tmux, paneId, agentId))) {
+                break;
+            }
+        }
+        return false;
+    }
+    // Greeting failed: hold the agent for a human (awaiting_human → not dispatchable) with a
+    // reason that names the capability gap. Clearing creationToken drops the "starting" pill;
+    // the operator fixes the runtime and restarts (re-greets) or Resumes to override.
+    async markGreetingFailed(agentId, creationToken) {
+        const existing = await this.agentStore.get(agentId);
+        if (!existing)
+            return;
+        if (creationToken !== undefined && existing.creationToken !== creationToken)
+            return;
+        const now = new Date().toISOString();
+        const reason = 'Greeting capability check failed: the agent did not echo a valid [bx:greeting] signal ' +
+            'per the baxian-signals skill within the timeout. Its runtime/model may not meet baxian ' +
+            'requirements (skill loading or pane signalling). Fix the runtime, then restart-repl or ' +
+            'retry the agent to re-run the check (Resume will not clear it — capability must be re-proven).';
+        let wrote = false;
+        await this.agentStore.update(agentId, (fresh) => {
+            if (!fresh)
+                return AGENT_STORE_NOOP;
+            if (creationToken !== undefined && fresh.creationToken !== creationToken)
+                return AGENT_STORE_NOOP;
+            wrote = true;
+            return {
+                ...fresh,
+                creationToken: undefined,
+                status: 'awaiting_human',
+                awaitingPhase: 'greeting_failed',
+                awaitingReason: reason,
+                awaitingSince: now,
+                updatedAt: now,
+            };
+        });
+        if (!wrote)
+            return;
+        await this.safeEmit({
+            id: '',
+            type: 'human.intervention',
+            timestamp: now,
+            projectId: existing.projectId,
+            agentId,
+            data: { phase: 'greeting_failed', reason },
+        });
+    }
+    // Operator restart-repl/retry recovery for a greeting_failed agent: re-run the handshake on
+    // the freshly-restarted REPL. Only a passing greeting clears the hold; a failure re-holds it.
+    // Returns true when it took ownership of a greeting_failed agent (caller skips its normal clear).
+    async regreetHeldAgent(agentId) {
+        const agent = this.getAgentConfig(agentId);
+        if (!agent)
+            return false;
+        const state = await this.agentStore.get(agentId);
+        if (state?.awaitingPhase !== 'greeting_failed')
+            return false;
+        // Identity of THIS hold: a greeting_failed binding carries no creationToken, so a DELETE+recreate
+        // during the (slow, up to 2× timeout) handshake is detected via awaitingSince — a stale regreet
+        // must never write onto the recreated generation.
+        const guardSince = state.awaitingSince;
+        let paneId = state.paneId;
+        if (!paneId) {
+            try {
+                paneId = await new TmuxManager(this.createRunnerFor(agent)).getSinglePaneId(agentId);
+            }
+            catch (err) {
+                console.warn(`[regreet] cannot resolve pane for ${agentId}:`, err);
+                return true; // leave it held; operator can restart/retry again
+            }
+        }
+        if (!(await this.runGreetingHandshake(agentId, agent, paneId))) {
+            // Failed → leave the existing hold untouched. Do NOT re-write it: an unguarded write could land
+            // on a DELETE+recreated generation that reused this id. Operator can restart/retry again.
+            return true;
+        }
+        // Passed → clear the hold, but only if this exact greeting_failed generation is still present.
+        await this.agentStore.update(agentId, (fresh) => {
+            if (!fresh || fresh.awaitingPhase !== 'greeting_failed' || fresh.awaitingSince !== guardSince) {
+                return AGENT_STORE_NOOP;
+            }
+            const { status: _s, awaitingPhase: _ap, awaitingReason: _ar, awaitingSince: _as, ...ready } = fresh;
+            return { ...ready, updatedAt: new Date().toISOString() };
+        });
+        return true;
+    }
     async markDialogPending(agentId, creationToken, opts = {}) {
         const existing = await this.agentStore.get(agentId);
         if (!existing)
             return;
+        // A greeting capability failure must not be downgraded into a dialog-resolvable hold: doing so
+        // would let Resume release a never-re-greeted agent. Keep the greeting_failed hold; restart/retry
+        // re-runs the handshake.
+        if (existing.awaitingPhase != null && REGREET_REQUIRED_HOLD_PHASES.has(existing.awaitingPhase))
+            return;
         // runtime path snapshot 全空时直接拒绝——既无 paneId 也无 taskId 作 generation 证据，
         // 旧 callback 通过 guard 污染同样 idle 的新 agent 的风险无法排除。
         if (opts.runtimePath && opts.expectedPaneId === undefined && opts.expectedTaskId === undefined) {
@@ -676,6 +836,8 @@ export class AgentManager {
         await this.agentStore.update(agentId, (fresh) => {
             if (!fresh)
                 return AGENT_STORE_NOOP;
+            if (fresh.awaitingPhase != null && REGREET_REQUIRED_HOLD_PHASES.has(fresh.awaitingPhase))
+                return AGENT_STORE_NOOP;
             if (opts.runtimePath) {
                 if (fresh.creationToken !== undefined)
                     return AGENT_STORE_NOOP;
@@ -924,11 +1086,24 @@ export class AgentManager {
             // 推 failed）+ lock 在；ready 后切到 'agent_dialog_resolved_runtime' phase，让 resumeAgent 放行
             // 让 operator 显式确认。仍保留 awaiting_human + lock 防止"dialog ready 自动派下一 task 撞 pane"。
             const isBootstrapPath = creationToken !== undefined;
+            // A create bootstrap that was blocked on a startup dialog still owes the greeting gate:
+            // now that the dialog is dismissed and the REPL is ready, run it before clearing to 'ok',
+            // else a dialog-resolved agent would reach the dispatch pool without proving capability.
+            if (isBootstrapPath && !(await this.runGreetingHandshake(agentId, cfg, paneId))) {
+                await this.markGreetingFailed(agentId, creationToken);
+                return;
+            }
             await this.agentStore.update(agentId, (fresh) => {
                 if (!fresh)
                     return AGENT_STORE_NOOP;
                 if (generationMismatch(fresh))
                     return AGENT_STORE_NOOP;
+                // A greeting capability hold must not be downgraded to a dialog-resolvable phase here (the
+                // runtime branch would otherwise rewrite it to agent_dialog_resolved_runtime, which Resume
+                // then releases un-regreeted). Preserve it; restart/retry's regreet is its recovery path.
+                if (fresh.awaitingPhase != null && REGREET_REQUIRED_HOLD_PHASES.has(fresh.awaitingPhase)) {
+                    return AGENT_STORE_NOOP;
+                }
                 projectIdForEmit = fresh.projectId;
                 wrote = true;
                 if (isBootstrapPath) {
@@ -1423,16 +1598,17 @@ export class AgentManager {
         const result = await this.withTaskLock(async () => {
             const state = await this.agentStore.get(agentId);
             if (!state)
-                return { resumed: false, releasedBinding: false };
+                return { resumed: false, releasedBinding: false, reason: 'Agent state not found.' };
             if (state.status !== 'awaiting_human') {
-                return { resumed: false, releasedBinding: false };
+                return { resumed: false, releasedBinding: false, reason: 'Agent is not awaiting human; nothing to resume.' };
             }
             // creationToken 仍 set = bootstrap dialog 仍未解决。Resume 不能让它"继续"——
             // dialog 在 pane 里需要 operator 通过 web terminal 处理，slowPoll 解决后自动清状态。
             // 如果 operator 想放弃这个 agent，应该走 DELETE 路径。
             if (state.creationToken) {
-                console.warn(`[AgentManager] resumeAgent: agent ${agentId} still has creationToken (bootstrap dialog unresolved); refusing Resume — operator should resolve dialog via web terminal or DELETE the agent.`);
-                return { resumed: false, releasedBinding: false };
+                const reason = 'Bootstrap dialog still unresolved; resolve it via the web terminal or DELETE the agent.';
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} still has creationToken — ${reason}`);
+                return { resumed: false, releasedBinding: false, reason };
             }
             const boundTask = state.taskId ? await this.taskStore.get(state.taskId) : null;
             // "prompt 可能仍在 pane 中跑"类 phase + bound task 仍 active 时 refuse：Resume 让
@@ -1448,8 +1624,9 @@ export class AgentManager {
             if (state.awaitingPhase != null
                 && PROMPT_MAYBE_RUNNING_PHASES.has(state.awaitingPhase)
                 && boundTask && ACTIVE_TASK_STATUSES.has(boundTask.status)) {
-                console.warn(`[AgentManager] resumeAgent: agent ${agentId} ${state.awaitingPhase} with active task ${state.taskId} — prompt may still be running; refusing Resume until outcome arrives or operator cancels the task / deletes the agent.`);
-                return { resumed: false, releasedBinding: false };
+                const reason = `Prompt may still be running (${state.awaitingPhase}); Resume is blocked until the task outcome arrives. Cancel task ${state.taskId} or DELETE the agent to recover.`;
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} — ${reason}`);
+                return { resumed: false, releasedBinding: false, reason };
             }
             // agent_dialog_pending: pane 仍卡 startup dialog，REPL 未 ready。Resume 让
             // shouldReleaseHeldBinding 看 task terminal/missing 放行后会清 binding/lock，下一次
@@ -1458,8 +1635,9 @@ export class AgentManager {
             // agent_dialog_resolved_runtime（Resume 放行）或 bootstrap path 直接清 Held → status='ok'，
             // 或 DELETE agent。
             if (state.awaitingPhase === 'agent_dialog_pending') {
-                console.warn(`[AgentManager] resumeAgent: agent ${agentId} dialog still pending; refusing Resume — operator should dismiss dialog via web terminal (slowPoll will mark agent_dialog_resolved_runtime, then Resume) or DELETE the agent.`);
-                return { resumed: false, releasedBinding: false };
+                const reason = 'Startup dialog still pending; Resume cannot dismiss it. Dismiss the dialog via the web terminal (baxian will auto-resume) or DELETE the agent.';
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} — ${reason}`);
+                return { resumed: false, releasedBinding: false, reason };
             }
             // agent_dialog_resolved_runtime + active task：正常路径下 handleDialogPendingFromRuntime
             // 已 fail task → boundTask 应 terminal。bound task 仍 active 表示 crash window
@@ -1468,8 +1646,9 @@ export class AgentManager {
             // refuse Resume，提示 operator 显式 cancel task 或 DELETE agent。
             if (state.awaitingPhase === 'agent_dialog_resolved_runtime'
                 && boundTask && ACTIVE_TASK_STATUSES.has(boundTask.status)) {
-                console.warn(`[AgentManager] resumeAgent: agent ${agentId} dialog resolved but bound task ${state.taskId} still active (crash window) — prompt was never injected; refusing Resume. Operator should cancel the task or DELETE the agent.`);
-                return { resumed: false, releasedBinding: false };
+                const reason = `Dialog resolved but task ${state.taskId} is still active and its prompt was never injected; Resume would strand it. Cancel the task or DELETE the agent.`;
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} — ${reason}`);
+                return { resumed: false, releasedBinding: false, reason };
             }
             // code-dispatch-failed: the code-phase prompt never reached the pane (spec
             // approval already transitioned the task). Resume = clear the hold AND
@@ -1499,15 +1678,25 @@ export class AgentManager {
             // Refuse while the task is active; operator must cancel the task or DELETE the agent to retry.
             if (state.awaitingPhase?.startsWith('signal-arm-failed')
                 && boundTask && ACTIVE_TASK_STATUSES.has(boundTask.status)) {
-                console.warn(`[AgentManager] resumeAgent: agent ${agentId} ${state.awaitingPhase} with active task ${state.taskId} — the dispatched prompt's pane signal has no consumer and Resume cannot rebuild the watcher; refusing Resume. Operator should cancel the task or DELETE the agent.`);
-                return { resumed: false, releasedBinding: false };
+                const reason = `The dispatched prompt's pane signal has no consumer and Resume cannot rebuild the watcher; cancel task ${state.taskId} or DELETE the agent to retry.`;
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} ${state.awaitingPhase} — ${reason}`);
+                return { resumed: false, releasedBinding: false, reason };
             }
             // Un-cleared pane (cancel mid-clear or /clear unconfirmed): Resume would free + reuse it (terminal
             // task → shouldReleaseHeldBinding) and leak the cancelled task's context. Refuse; only DELETE (which
             // destroys the pane) is a safe recovery.
             if (state.awaitingPhase != null && UNCLEARED_PANE_PHASES.has(state.awaitingPhase)) {
-                console.warn(`[AgentManager] resumeAgent: agent ${agentId} ${state.awaitingPhase} — pane holds un-cleared context; refusing Resume. DELETE the agent to discard it.`);
-                return { resumed: false, releasedBinding: false };
+                const reason = 'The pane holds un-cleared context from a cancelled task; Resume would leak it into the next task. DELETE the agent to discard it.';
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} ${state.awaitingPhase} — ${reason}`);
+                return { resumed: false, releasedBinding: false, reason };
+            }
+            // A greeting capability failure must be RE-PROVEN, not Resumed away: the default path below
+            // flips status→'ok' regardless of shouldReleaseHeldBinding, which would put an unverified
+            // agent back in the dispatch pool. The recovery path is restart-repl / retry (re-greets).
+            if (state.awaitingPhase != null && REGREET_REQUIRED_HOLD_PHASES.has(state.awaitingPhase)) {
+                const reason = 'Greeting capability check failed; the runtime must re-prove it. Resume cannot clear this hold — use Restart REPL to re-run the greeting check.';
+                console.warn(`[AgentManager] resumeAgent: agent ${agentId} ${state.awaitingPhase} — ${reason}`);
+                return { resumed: false, releasedBinding: false, reason };
             }
             const now = new Date().toISOString();
             const shouldReleaseBinding = shouldReleaseHeldBinding(state, boundTask);
@@ -1578,7 +1767,11 @@ export class AgentManager {
                 await this.markAwaitingHuman(agentId, 'code-dispatch-failed', 'Code-phase redispatch on Resume failed; Resume again to retry or cancel the task.', { expectedTaskId: result.redispatchCodeTaskId }).catch(() => undefined);
             }
         }
-        return { resumed: result.resumed, releasedBinding: result.releasedBinding };
+        return {
+            resumed: result.resumed,
+            releasedBinding: result.releasedBinding,
+            ...(result.reason ? { reason: result.reason } : {}),
+        };
     }
     async resolvePaneId(state, cfg) {
         if (state.paneId)
@@ -1935,15 +2128,51 @@ export class AgentManager {
         else if (!SHELL.test(cmd)) {
             throw new Error(`restart-repl precondition failed: unexpected pane state "${cmd}"`);
         }
+        // Re-materialize skills BEFORE the relaunch so the fresh REPL scans the current tree. restart-repl
+        // is the operator's recovery for a greeting_failed agent whose on-disk skill tree was stale/missing,
+        // and unlike retry it does not go through ensureSession's provisionRepoSkills. Best-effort: a
+        // provisioning blip must not block the REPL restart (a still-broken tree surfaces on the next regreet).
+        const project = this.getProjectConfig(cfg.projectId);
+        let workdir;
+        let provisioned = false;
+        if (project) {
+            try {
+                workdir = (await this.ensureWorkdir(cfg, project, runner)).workdir;
+                await this.provisionRepoSkills(runner, cfg, workdir);
+                provisioned = true;
+            }
+            catch (err) {
+                console.warn(`[restart-repl] skill re-provision failed for ${agentId} (continuing):`, err);
+            }
+        }
         const runtime = agentRuntimeKindFor(cfg);
-        await tmux.sendKeysToPane(paneId, `${buildLaunchCommand(cfg)}\n`);
-        await tmux.handleTrustDialog(paneId, runtime, {
-            timeoutMs: this.bootstrapTimeoutsMs.trustDialog,
-        });
-        await tmux.waitReplReady(paneId, runtime, {
-            timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
-            scrollback: 0,
-        });
+        const relaunch = async () => {
+            await tmux.sendKeysToPane(paneId, `${buildLaunchCommand(cfg)}\n`);
+            await tmux.handleTrustDialog(paneId, runtime, {
+                timeoutMs: this.bootstrapTimeoutsMs.trustDialog,
+            });
+            await tmux.waitReplReady(paneId, runtime, {
+                timeoutMs: this.bootstrapTimeoutsMs.waitReplReady,
+                scrollback: 0,
+            });
+            // Only re-tag when the tree was actually re-provisioned. Tagging after a FAILED provision
+            // would stamp the current version onto a REPL that scanned the stale/missing tree, so the
+            // next ensureSession reads it as fresh and reuses it instead of self-healing (rebuild). A
+            // successful provision DOES need the tag, else ensureSession needlessly kills this REPL and
+            // drops the agent onto a different, ungreeted one.
+            if (provisioned) {
+                await this.tagSessionSkillsVersion(tmux, agentId);
+            }
+        };
+        // Hold the per-skills-dir lock ACROSS the relaunch (like buildFreshSessionLocked) so a concurrent
+        // same-dir agent's provisioning — which transiently removes helper files (agents/openai.yaml) —
+        // can't make this fresh REPL scan an incomplete skill tree.
+        if (workdir !== undefined) {
+            await this.runUnderSkillDirLock(this.skillDirLockKey(cfg, workdir), relaunch);
+        }
+        else {
+            await relaunch();
+        }
         await this.agentStore.update(agentId, (state) => {
             if (!state)
                 return AGENT_STORE_NOOP;
@@ -2075,6 +2304,10 @@ export class AgentManager {
             agent: cfg,
             worktreePath: worktreePathBound,
             skillRegistry: this.skillRegistry,
+            // A representative token so the preview exercises the SAME required-skill set (baxian-signals)
+            // and worst-case byte size the real signal-emitting dispatch will build — else a missing
+            // baxian-signals only surfaces async after the task is already created (201).
+            signalToken: 'preview-signal-token',
         });
         return Buffer.byteLength(fullPrompt, 'utf8');
     }
@@ -3268,6 +3501,15 @@ export class AgentManager {
             catch { }
             return false;
         }
+        // Pane exists now but the prompt is not out — arm here so a request it triggers is a live chunk,
+        // not snapshot-suppressed scrollback. Abort cleanly (no binding written yet) if it cannot arm.
+        if (opts.armBeforeInject && !(await opts.armBeforeInject())) {
+            try {
+                await worktree.removeWithBranch(workdir, worktreePath, customBranch);
+            }
+            catch { }
+            return false;
+        }
         const now = new Date().toISOString();
         let agentMarkedRunning = false;
         try {
@@ -3668,6 +3910,10 @@ export class AgentManager {
                 return false;
             }
         }
+        // Arm before paste (same reasoning as startSession): pane exists, prompt not out yet.
+        if (opts.armBeforeInject && !(await opts.armBeforeInject())) {
+            return false;
+        }
         const now = new Date().toISOString();
         await this.agentStore.update(agentId, (latest) => {
             if (!latest)
@@ -3778,6 +4024,31 @@ export class AgentManager {
                 // dialog-pending catch below, so a mid-bootstrap task blocked on a startup dialog isn't held forever.)
                 if (await this.rollbackUndeliveredBootstrap(state, agentConfig))
                     continue;
+                // An incomplete create bootstrap (creationToken still set, no task) crashed before it
+                // proved signal capability. Re-run the greeting gate — but in the BACKGROUND: recover() is
+                // awaited before the server serves, and a synchronous handshake would block startup up to
+                // 2×greeting-timeout per such agent (serially). creationToken stays set meanwhile, so
+                // canDispatchWithBinding keeps the agent out of the pool until the handshake resolves.
+                if (state.creationToken && !state.taskId) {
+                    const ct = state.creationToken;
+                    const pane = result.paneId;
+                    const cfg = agentConfig;
+                    const agentId = state.id;
+                    void (async () => {
+                        if (await this.runGreetingHandshake(agentId, cfg, pane)) {
+                            await this.agentStore.update(agentId, (latest) => {
+                                if (!latest || latest.creationToken !== ct)
+                                    return AGENT_STORE_NOOP;
+                                const { creationToken: _ct, status: _s, awaitingPhase: _ap, awaitingReason: _ar, awaitingSince: _as, ...ready } = latest;
+                                return { ...ready, paneId: pane, updatedAt: new Date().toISOString() };
+                            });
+                        }
+                        else {
+                            await this.markGreetingFailed(agentId, ct);
+                        }
+                    })().catch((err) => console.warn(`[recover] background re-greet for ${agentId} crashed:`, err));
+                    continue;
+                }
                 // recover 成功 = server 重启前 dialog_pending 的 agent 现在 REPL ready。
                 // 处理 Held：与 resumeAgent 共用 shouldReleaseHeldBinding 规则（task terminal/无 task /
                 // turn-completed phase → 同步清 binding；task active 且 phase 不在 completed 集合 → 保留 binding）。
@@ -3966,6 +4237,12 @@ export class AgentManager {
                     return AGENT_STORE_NOOP;
                 if (existing.creationToken)
                     return AGENT_STORE_NOOP;
+                // A greeting capability hold must survive a transient/real tmux disappearance — wiping it
+                // (it carries a paneId on the dialog path) would slip an unverified agent back into the
+                // dispatch pool. Operator restart/retry re-greets; recover/Resume already preserve it.
+                if (existing.awaitingPhase != null && REGREET_REQUIRED_HOLD_PHASES.has(existing.awaitingPhase)) {
+                    return AGENT_STORE_NOOP;
+                }
                 timestamp = new Date().toISOString();
                 projectId = existing.projectId;
                 hadBinding = !!existing.taskId;
@@ -5649,6 +5926,9 @@ export class AgentManager {
             ...(opts.priorFindingsJson ? { serverPriorFindings: opts.priorFindingsJson } : {}),
             ...(opts.priorResponseJson ? { serverPriorResponse: opts.priorResponseJson } : {}),
             ...(opts.phase === 'spec' ? { currentSpecRound: newRound } : {}),
+            // Arm the verdict + read-file watcher in the pane-exists / pre-paste window so a QA
+            // [bx:read-file:...] emitted during the dispatch is a live chunk, not snapshot-suppressed.
+            armBeforeInject: () => this.setupPhaseSignalWatcher(taskId, qaId, expectedKind, newToken, false, (req) => { void this.handleReadFileRequest(taskId, qaId, req); }),
         };
         // A continuation consumed the QA's reviewed signal (not the dev's entry
         // signal): rollback restores the prior slice's review/token, so re-arm the
@@ -5669,6 +5949,9 @@ export class AgentManager {
                 : await this.startSession(taskId, qaId, dispatchPhase, sessionOpts);
         }
         catch (err) {
+            // armBeforeInject may have armed the watcher before the failing paste — drop it so a stale
+            // entry can't fire on a rolled-back / failed task (no-op if it never armed).
+            this.stopPhaseSignalWatcher(taskId);
             if (err instanceof DispatchTerminalError) {
                 await this.failTaskForDispatchError(taskId, dispatchPhase, qaId, err);
             }
@@ -5685,6 +5968,9 @@ export class AgentManager {
             throw err;
         }
         if (!started) {
+            // Covers armBeforeInject returning false (watcher couldn't arm) as well as any other
+            // pre-paste abort; stop is a no-op when nothing armed.
+            this.stopPhaseSignalWatcher(taskId);
             await rollback();
             if (!opts.continuation) {
                 await this.releaseAgentForTask(qaId, taskId, 'idle').catch(() => undefined);
@@ -5701,8 +5987,6 @@ export class AgentManager {
             });
             return null;
         }
-        this.stopPhaseSignalWatcher(taskId);
-        await this.armPostDispatchSignalOrHold(taskId, qaId, expectedKind, newToken, false, (req) => { void this.handleReadFileRequest(taskId, qaId, req); });
         return await this.taskStore.get(taskId);
     }
     async dispatchServerFixToDev(taskId, findingsJson) {