agent-tempo 1.6.0 → 1.6.2

package/dist/config.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GLOBAL_MAESTRO_WORKFLOW_ID = exports.DaemonConfigSchema = exports.CleanupPolicySchema = exports.CONFIG_FILE_PATH = exports.AGENT_TEMPO_HOME = exports.PROD_DAEMON_PORT = exports.DEV_DAEMON_PORT = exports.PROD_TASK_QUEUE = exports.DEV_TASK_QUEUE = exports.PROD_TEMPORAL_NAMESPACE = exports.DEV_TEMPORAL_NAMESPACE = exports.PROD_HOME_DIR_NAME = exports.DEV_HOME_DIR_NAME = exports.ENV = void 0;
 exports.isDevMode = isDevMode;
 exports.resolveTempoHome = resolveTempoHome;
+exports.bridgeLogsRoot = bridgeLogsRoot;
+exports.bridgeLogPaths = bridgeLogPaths;
+exports.resolveAdapterPidFile = resolveAdapterPidFile;
 exports.loadDaemonConfig = loadDaemonConfig;
 exports.matchEnsembleGlob = matchEnsembleGlob;
 exports.isEnsembleAllowed = isEnsembleAllowed;
@@ -23,14 +26,8 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
 const zod_1 = require("zod");
+const types_1 = require("./types");
 const validation_1 = require("./utils/validation");
-// `'mock'` is a valid `AgentType` value but intentionally NOT in the resolved
-// `defaultAgent` set — recruit pre-flight rejects it outside dev mode anyway,
-// and it's never a sensible *default* (each mock spawn is configured per call
-// via the `agent: 'mock'` flag, not via the resolved chain). Listing it here
-// would only enable users to set `defaultAgent=mock` in `~/.agent-tempo/config.json`,
-// which the recruit gate would then turn around and reject in production.
-const VALID_AGENTS = ['claude', 'copilot'];
 /** Environment variable name constants — use these instead of string literals. */
 exports.ENV = {
     ENSEMBLE: 'AGENT_TEMPO_ENSEMBLE',
@@ -161,6 +158,15 @@ exports.ENV = {
      * spawns do NOT set it, so recruited adapters keep the #604 anti-leak ppid-poll.
      */
     NO_PPID_WATCHDOG: 'AGENT_TEMPO_NO_PPID_WATCHDOG',
+    /**
+     * #690 — absolute path to the bridge pid file, computed ONCE by the spawn
+     * helper (`bridgeLogPaths(ensemble, name).pidPath`) and passed to the adapter
+     * child. The adapter writes/unlinks THIS path rather than re-deriving its own
+     * (which diverged from the spawner's when PLAYER_NAME was empty — the
+     * split-brain orphan). PLAIN (non-secret): it's a file location, not a
+     * credential — must stay inline under #689's `partitionEnv`.
+     */
+    PID_FILE: 'AGENT_TEMPO_PID_FILE',
     /**
      * Escape hatch for triple-isolated environments (ADR 0014 §5.3). When
      * set, `resolveTempoHome()` returns this path verbatim — bypassing both
@@ -229,6 +235,51 @@ function resolveTempoHome() {
 }
 exports.AGENT_TEMPO_HOME = resolveTempoHome();
 exports.CONFIG_FILE_PATH = (0, path_1.join)(exports.AGENT_TEMPO_HOME, 'config.json');
+/**
+ * SINGLE source of truth for where a recruited bridge/adapter's `.log` + `.pid`
+ * live (#690). Default is CENTRAL — `~/.agent-tempo/logs/<ensemble>/<player>.*` —
+ * NOT the old per-cwd `<workDir>/logs` (which scattered pid files across every
+ * recruit directory and orphaned them on `down`). No call site should construct
+ * its own `join(..., 'logs', ...)`; route everything through here so the writer
+ * (spawn helper) and the readers (status / down / hard-terminate) compute the
+ * SAME path and can't split-brain.
+ *
+ * `overrideDir` is the existing per-spawn `opts.logDir` escape hatch (rarely set);
+ * when present it wins over the central default. `ensemble`/`player` are
+ * regex-validated upstream (ENSEMBLE_NAME_REGEX / PLAYER_NAME_REGEX — no slashes),
+ * but a defensive guard rejects path-traversal as insurance.
+ */
+/**
+ * Root of the central bridge-log tree: `~/.agent-tempo/logs`. Per-ensemble dirs
+ * live under it. Exposed so a cluster-wide reader (e.g. `down`'s
+ * killBridgeProcesses) can enumerate every ensemble's dir without re-constructing
+ * the `'logs'` segment itself — {@link bridgeLogPaths} is the only other place
+ * that names it.
+ */
+function bridgeLogsRoot() {
+    return (0, path_1.join)(exports.AGENT_TEMPO_HOME, 'logs');
+}
+function bridgeLogPaths(ensemble, player, overrideDir) {
+    for (const [label, seg] of [['ensemble', ensemble], ['player', player]]) {
+        if (/[/\\]|\.\./.test(seg)) {
+            throw new Error(`bridgeLogPaths: ${label} "${seg}" must not contain path separators or "..".`);
+        }
+    }
+    const dir = overrideDir ?? (0, path_1.join)(bridgeLogsRoot(), ensemble);
+    return { dir, logPath: (0, path_1.join)(dir, `${player}.log`), pidPath: (0, path_1.join)(dir, `${player}.pid`) };
+}
+/**
+ * The pid path an ADAPTER subprocess should write/unlink (#690). The SPAWNER
+ * computes the path once via {@link bridgeLogPaths} and passes it as
+ * `ENV.PID_FILE`; the adapter consumes THAT — it does NOT re-derive its own from
+ * a (possibly divergent) player identifier. The `bridgeLogPaths` fallback is used
+ * ONLY when the env is absent (a manual adapter launch outside the spawner). This
+ * is the by-construction fix for the copilot split-brain (PLAYER_NAME='' →
+ * `copilot-${Date.now()}` ≠ the spawner's logName).
+ */
+function resolveAdapterPidFile(ensemble, fallbackPlayer) {
+    return process.env[exports.ENV.PID_FILE] || bridgeLogPaths(ensemble, fallbackPlayer).pidPath;
+}
 // ── Daemon config (PR-E design §10.2) ──
 /**
  * Daemon-level configuration persisted in `~/.agent-tempo/config.json`
@@ -458,16 +509,25 @@ const AGENT_SOURCE_LABELS = {
     none: 'none',
 };
 /**
- * Parse an agent value against the {@link AgentType} union.
- * Throws when `value` is present but not a valid agent; returns `'claude'`
- * for empty/unset values so callers can use it as a source-aware default.
+ * Parse an agent value against the canonical {@link AGENT_TYPES} union — the
+ * SINGLE SOURCE OF TRUTH for agent validity (shared with `cli.ts`'s `--agent`
+ * parser). Throws when `value` is present but not a known agent; returns
+ * `'claude'` for empty/unset values so callers can use it as a source-aware default.
+ *
+ * This is a pure type-VALIDITY check — it accepts EVERY `AgentType` (including
+ * `mock` and the headless adapters). Narrower CAPABILITY constraints are gated
+ * separately downstream: the recruit pre-flight rejects `mock` outside dev mode,
+ * and `config`'s `VALID_DEFAULT_AGENTS` restricts the persistent default to the
+ * conductor-capable subset. (#683: the former hardcoded `['claude','copilot']`
+ * list was stale — it rejected `defaultAgent=pi` at config LOAD, poisoning every
+ * command before the `--agent` flag was even read.)
  */
 function parseAgent(value, source) {
     if (value == null || value === '')
         return 'claude';
-    if (!VALID_AGENTS.includes(value)) {
+    if (!types_1.AGENT_TYPES.includes(value)) {
         throw new Error(`Invalid agent "${value}" from ${AGENT_SOURCE_LABELS[source]}. ` +
-            `Valid values: ${VALID_AGENTS.join(', ')}.`);
+            `Valid values: ${types_1.AGENT_TYPES.join(', ')}.`);
     }
     return value;
 }

package/dist/pi/cue-pump.js

@@ -18,7 +18,15 @@ function buildPiInjector(rt) {
         const sendUser = typeof pi?.sendUserMessage === 'function' ? pi.sendUserMessage.bind(pi) : null;
         return {
             inject: (msg, opts) => send(msg, opts),
-            ...(sendUser ? { escalate: (text) => sendUser(text) } : {}),
+            // #688 — escalate with `deliverAs: 'followUp'`. maybeEscalate can fire while a
+            // turn is ALREADY in flight (one that started BEFORE the inject — a busy
+            // false-positive), and a bare sendUserMessage (no deliverAs) while Pi is
+            // streaming throws "Agent is already processing". followUp is correct in BOTH
+            // cases: cold-idle (behavior ignored → the user message still starts a turn,
+            // escalation works) and busy (queues + drains in order, no throw). NOT 'steer'
+            // — steer would let a peer cue preempt the operator's in-flight turn, breaking
+            // the operator-vs-peer guarantee (see file header).
+            ...(sendUser ? { escalate: (text) => sendUser(text, { deliverAs: 'followUp' }) } : {}),
             lastTurnStartAt: () => rt.lastTurnStartAt,
         };
     }

package/dist/spawn.d.ts

@@ -35,10 +35,56 @@ export declare function detectMacTerminal(): 'ghostty' | 'iterm2' | 'terminal';
 /** Find the first available terminal emulator on Linux */
 export declare function findLinuxTerminal(): string | null;
 /**
- * Build a shell command string that sets env vars and runs claude.
- * Uses inline `KEY=val` syntax which works in bash, zsh, AND fish.
+ * fish single-quote escaping. Inside fish `'...'` only `\` and `'` are special
+ * (`\\` and `\'`) — POSIX `shellQuote`'s `'\''` trick is WRONG in fish, so the
+ * secret file's `set -gx` lines need this. Plain inline env keeps `shellQuote`
+ * (safe there: plain values are regex-validated names with no embedded quotes).
  */
-export declare function buildTerminalCommand(bin: string, binArgs: string[], envVars: Record<string, string>): string;
+export declare function fishQuote(s: string): string;
+/** Split env into non-secret (inline-able) and secret (file-only) by key name. */
+export declare function partitionEnv(env: Record<string, string>): {
+    plainEnv: Record<string, string>;
+    secretEnv: Record<string, string>;
+};
+export interface SecretEnvFile {
+    /** Absolute path to the 0600 env file, or '' when there were no secrets. */
+    path: string;
+    /** Chain prefix that sources THEN deletes the file before the bin runs (or ''). */
+    sourcePrefix: string;
+    /** Standalone delete command for the file (or ''). */
+    cleanup: string;
+}
+/**
+ * Write secret env to a 0600 file in the 0700 {@link SECRET_ENV_DIR} and return a
+ * `sourcePrefix` that sources + deletes it before exec. Empty `secretEnv` → no
+ * file, empty strings (no behavior change when there are no secrets, e.g. local
+ * dev with no Cloud key).
+ *
+ * Security: `openSync(path, 'wx', 0o600)` (O_EXCL → fails if the path exists,
+ * defeating symlink pre-creation in a shared tmp), a `crypto.randomBytes` name
+ * (NOT a predictable `Date.now()`), and the 0700 dir + 0600 file = owner-only
+ * twice over. The LAUNCHER self-deletes (sourcePrefix `… && rm -f <f> && …`) — the
+ * spawner does NOT, so there's no race: Node writes synchronously before the
+ * terminal launches, only the shell reads the file, and after `rm` the value
+ * lives only in the process env.
+ */
+export declare function writeSecretEnvFile(secretEnv: Record<string, string>, opts: {
+    syntax: 'posix' | 'fish' | 'cmd';
+}): SecretEnvFile;
+/**
+ * Best-effort sweep of secret env files older than `maxAgeMs` (default 5 min) —
+ * a backstop for the accepted residual when a shell dies between `source` and
+ * `rm`. Owner-only files in our 0700 dir; swallow all errors. Call at `up` start.
+ */
+export declare function sweepStaleSecretEnvFiles(maxAgeMs?: number, now?: number): void;
+/**
+ * Build a shell command string that sets env vars and runs `bin` (#689).
+ * Plain env keeps the inline `KEY=val` form (works in bash/zsh/fish); SECRET env
+ * is routed to a sourced 0600 file via {@link writeSecretEnvFile}, so secret
+ * VALUES never appear in the returned command string. `syntax` picks the secret
+ * file's dialect (the inline plain form is identical across posix/fish).
+ */
+export declare function buildTerminalCommand(bin: string, binArgs: string[], envVars: Record<string, string>, syntax?: 'posix' | 'fish'): string;
 /**
  * Launch ANY binary in a visible terminal window (the cross-platform core
  * extracted from `spawnInTerminal`, #666 C1). Generic over `bin`/`args` so it

package/dist/spawn.js

@@ -6,6 +6,10 @@ exports.shellQuote = shellQuote;
 exports.resolveClaudePath = resolveClaudePath;
 exports.detectMacTerminal = detectMacTerminal;
 exports.findLinuxTerminal = findLinuxTerminal;
+exports.fishQuote = fishQuote;
+exports.partitionEnv = partitionEnv;
+exports.writeSecretEnvFile = writeSecretEnvFile;
+exports.sweepStaleSecretEnvFiles = sweepStaleSecretEnvFiles;
 exports.buildTerminalCommand = buildTerminalCommand;
 exports.launchInTerminal = launchInTerminal;
 exports.spawnInTerminal = spawnInTerminal;
@@ -22,7 +26,9 @@ const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
+const crypto_1 = require("crypto");
 const config_1 = require("./config");
+const secrets_1 = require("./utils/secrets");
 const log = (...args) => console.error('[agent-tempo:spawn]', ...args);
 /** Stable GUID for the agent-tempo Windows Terminal profile. */
 const WT_PROFILE_GUID = '{c1a0d300-0e30-4000-a000-c1a0de00e300}';
@@ -234,18 +240,128 @@ function findLinuxTerminal() {
     }
     return null;
 }
+// ── #689 no-echo spawn: keep secret env values OUT of the echoed command ──────
+//
+// Terminal launches (claude conductor/recruit via spawnInTerminal, pi conductor
+// via buildPiConductorSpawn) INLINE env into the command string that gets typed/
+// echoed into the terminal — so `TEMPORAL_API_KEY='<JWT>' … pi …` lands in
+// scrollback + shell history. Fix: partition env by name; SECRET values are
+// written to a 0600 file in a 0700 owner-only dir and `source`d (then the
+// launcher self-`rm`s it) so the value never appears on the command line. Plain
+// (non-secret) env keeps the existing inline form. Headless adapters
+// (copilot/claude-api/opencode/*-headless) pass env via child_process `env:{}`
+// inheritance — no terminal, no inline — so they're unaffected.
+/** Owner-only (0700) dir holding short-lived 0600 secret env files. */
+const SECRET_ENV_DIR = (0, path_1.join)((0, os_1.tmpdir)(), 'agent-tempo-spawn');
+/** Escape a value for `cmd.exe` (wrap-in-quotes callers add the quotes). */
+function cmdEscape(s) {
+    return s.replace(/([&|<>^"%])/g, '^$1');
+}
 /**
- * Build a shell command string that sets env vars and runs claude.
- * Uses inline `KEY=val` syntax which works in bash, zsh, AND fish.
+ * fish single-quote escaping. Inside fish `'...'` only `\` and `'` are special
+ * (`\\` and `\'`) — POSIX `shellQuote`'s `'\''` trick is WRONG in fish, so the
+ * secret file's `set -gx` lines need this. Plain inline env keeps `shellQuote`
+ * (safe there: plain values are regex-validated names with no embedded quotes).
+ */
+function fishQuote(s) {
+    return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/** Split env into non-secret (inline-able) and secret (file-only) by key name. */
+function partitionEnv(env) {
+    const plainEnv = {};
+    const secretEnv = {};
+    for (const [k, v] of Object.entries(env)) {
+        if ((0, secrets_1.isSecretKey)(k))
+            secretEnv[k] = v;
+        else
+            plainEnv[k] = v;
+    }
+    return { plainEnv, secretEnv };
+}
+/**
+ * Write secret env to a 0600 file in the 0700 {@link SECRET_ENV_DIR} and return a
+ * `sourcePrefix` that sources + deletes it before exec. Empty `secretEnv` → no
+ * file, empty strings (no behavior change when there are no secrets, e.g. local
+ * dev with no Cloud key).
+ *
+ * Security: `openSync(path, 'wx', 0o600)` (O_EXCL → fails if the path exists,
+ * defeating symlink pre-creation in a shared tmp), a `crypto.randomBytes` name
+ * (NOT a predictable `Date.now()`), and the 0700 dir + 0600 file = owner-only
+ * twice over. The LAUNCHER self-deletes (sourcePrefix `… && rm -f <f> && …`) — the
+ * spawner does NOT, so there's no race: Node writes synchronously before the
+ * terminal launches, only the shell reads the file, and after `rm` the value
+ * lives only in the process env.
  */
-function buildTerminalCommand(bin, binArgs, envVars) {
-    const envInline = Object.entries(envVars)
+function writeSecretEnvFile(secretEnv, opts) {
+    const keys = Object.keys(secretEnv);
+    if (keys.length === 0)
+        return { path: '', sourcePrefix: '', cleanup: '' };
+    (0, fs_1.mkdirSync)(SECRET_ENV_DIR, { recursive: true, mode: 0o700 });
+    const ext = opts.syntax === 'cmd' ? 'cmd' : 'sh';
+    const path = (0, path_1.join)(SECRET_ENV_DIR, `env-${(0, crypto_1.randomBytes)(9).toString('hex')}.${ext}`);
+    let content;
+    if (opts.syntax === 'fish') {
+        content = keys.map((k) => `set -gx ${k} ${fishQuote(secretEnv[k])}`).join('\n') + '\n';
+    }
+    else if (opts.syntax === 'cmd') {
+        content = keys.map((k) => `set "${k}=${cmdEscape(secretEnv[k])}"`).join('\r\n') + '\r\n';
+    }
+    else {
+        content = keys.map((k) => `export ${k}=${shellQuote(secretEnv[k])}`).join('\n') + '\n';
+    }
+    // O_EXCL create with 0600 — fails (no follow) if a symlink/file pre-exists.
+    const fd = (0, fs_1.openSync)(path, 'wx', 0o600);
+    try {
+        (0, fs_1.writeSync)(fd, content);
+    }
+    finally {
+        (0, fs_1.closeSync)(fd);
+    }
+    if (opts.syntax === 'cmd') {
+        const q = `"${cmdEscape(path)}"`;
+        return { path, sourcePrefix: `call ${q} && del ${q} && `, cleanup: `del ${q}` };
+    }
+    const q = shellQuote(path);
+    return { path, sourcePrefix: `source ${q} && rm -f ${q} && `, cleanup: `rm -f ${q}` };
+}
+/**
+ * Best-effort sweep of secret env files older than `maxAgeMs` (default 5 min) —
+ * a backstop for the accepted residual when a shell dies between `source` and
+ * `rm`. Owner-only files in our 0700 dir; swallow all errors. Call at `up` start.
+ */
+function sweepStaleSecretEnvFiles(maxAgeMs = 5 * 60_000, now = Date.now()) {
+    try {
+        for (const name of (0, fs_1.readdirSync)(SECRET_ENV_DIR)) {
+            if (!name.startsWith('env-'))
+                continue;
+            const p = (0, path_1.join)(SECRET_ENV_DIR, name);
+            try {
+                if (now - (0, fs_1.statSync)(p).mtimeMs > maxAgeMs)
+                    (0, fs_1.rmSync)(p, { force: true });
+            }
+            catch { /* per-file best-effort */ }
+        }
+    }
+    catch { /* dir absent / unreadable — nothing to sweep */ }
+}
+/**
+ * Build a shell command string that sets env vars and runs `bin` (#689).
+ * Plain env keeps the inline `KEY=val` form (works in bash/zsh/fish); SECRET env
+ * is routed to a sourced 0600 file via {@link writeSecretEnvFile}, so secret
+ * VALUES never appear in the returned command string. `syntax` picks the secret
+ * file's dialect (the inline plain form is identical across posix/fish).
+ */
+function buildTerminalCommand(bin, binArgs, envVars, syntax = 'posix') {
+    const { plainEnv, secretEnv } = partitionEnv(envVars);
+    const { sourcePrefix } = writeSecretEnvFile(secretEnv, { syntax });
+    const envInline = Object.entries(plainEnv)
         .map(([k, v]) => `${k}=${shellQuote(v)}`)
         .join(' ');
     // Quote the binary path if it contains spaces (e.g., "C:\Program Files\...")
     const quotedBin = bin.includes(' ') ? shellQuote(bin) : bin;
     const args = binArgs.map(a => shellQuote(a)).join(' ');
-    return envInline ? `${envInline} ${quotedBin} ${args}` : `${quotedBin} ${args}`;
+    const invocation = envInline ? `${envInline} ${quotedBin} ${args}` : `${quotedBin} ${args}`;
+    return `${sourcePrefix}${invocation}`;
 }
 /**
  * Launch ANY binary in a visible terminal window (the cross-platform core
@@ -267,11 +383,16 @@ function launchInTerminal(bin, args, workDir, envVars) {
     // is bin/args-agnostic; the `claude*` names are historical.
     const claudeBin = bin;
     const claudeArgs = args;
-    const claudeInvocation = buildTerminalCommand(claudeBin, claudeArgs, envVars);
     if (process.platform === 'darwin') {
         const detected = detectMacTerminal();
         log(`Terminal detection: TERM_PROGRAM=${JSON.stringify(process.env.TERM_PROGRAM)}, detected=${detected}`);
+        // #689 — secret env routes through a sourced 0600 file (buildTerminalCommand /
+        // the .command body); pick the file dialect from the user's shell since
+        // Ghostty/iTerm2 type the command into it. Computed per-branch below so only
+        // the branch that runs writes a secret file (no orphan).
+        const macSyntax = (process.env.SHELL || '').endsWith('/fish') ? 'fish' : 'posix';
         if (detected === 'ghostty') {
+            const claudeInvocation = buildTerminalCommand(claudeBin, claudeArgs, envVars, macSyntax);
             // Append `; exit` so the wrapping shell exits when claude does (clean or killed).
             // Without it, claude exit returns control to the shell prompt and the tab lingers —
             // parity with the Windows WT `closeOnExit: 'always'` + parent-walk fix from #166.
@@ -292,6 +413,7 @@ function launchInTerminal(bin, args, workDir, envVars) {
             return { pid: child.pid };
         }
         if (detected === 'iterm2') {
+            const claudeInvocation = buildTerminalCommand(claudeBin, claudeArgs, envVars, macSyntax);
             // Append `; exit` so the wrapping shell exits when claude does. `;` rather than
             // `&&` so exit runs regardless of claude's exit code (force-kill returns non-zero).
             // JSON.stringify embeds the full shell command as a properly-escaped string literal
@@ -313,38 +435,50 @@ function launchInTerminal(bin, args, workDir, envVars) {
             child.unref();
             return { pid: child.pid };
         }
-        // Terminal.app: .command file with shell profile sourcing
+        // Terminal.app: .command file with shell profile sourcing.
         const userShell = process.env.SHELL || '/bin/zsh';
-        const scriptPath = (0, path_1.join)((0, os_1.tmpdir)(), `agent-tempo-recruit-${Date.now()}.command`);
-        let profileSource;
+        // #689 — the .command file is mode 0700 (was 0755 — it should never have been
+        // world/group-readable). The secret env lives in a SEPARATE sourced 0600 file,
+        // never inlined into this .command body.
+        const scriptPath = (0, path_1.join)(SECRET_ENV_DIR, `recruit-${(0, crypto_1.randomBytes)(9).toString('hex')}.command`);
+        (0, fs_1.mkdirSync)(SECRET_ENV_DIR, { recursive: true, mode: 0o700 });
+        let lines;
         if (userShell.endsWith('/fish')) {
-            profileSource = `exec fish -c "cd ${shellQuote(workDir)} && ${claudeInvocation}"`;
+            // claudeInvocation (fish) already carries the plain inline env + the fish
+            // secret-file source+rm — just exec fish with it.
+            const claudeInvocation = buildTerminalCommand(claudeBin, claudeArgs, envVars, 'fish');
+            lines = ['#!/bin/bash', `exec fish -c "cd ${shellQuote(workDir)} && ${claudeInvocation}"`];
         }
         else {
-            profileSource = [
+            const { plainEnv, secretEnv } = partitionEnv(envVars);
+            const secretFile = writeSecretEnvFile(secretEnv, { syntax: 'posix' });
+            const plainExports = Object.entries(plainEnv)
+                .map(([k, v]) => `export ${k}=${shellQuote(v)}`)
+                .join('\n');
+            const profileSource = [
                 `[ -f "$HOME/.zshrc" ] && source "$HOME/.zshrc" 2>/dev/null`,
                 `[ -f "$HOME/.bashrc" ] && source "$HOME/.bashrc" 2>/dev/null`,
                 `[ -f "$HOME/.nvm/nvm.sh" ] && source "$HOME/.nvm/nvm.sh" 2>/dev/null`,
                 `command -v fnm >/dev/null && eval "$(fnm env)" 2>/dev/null`,
             ].join('\n');
+            lines = [
+                '#!/bin/bash',
+                // Secret env from the sourced 0600 file (self-deleted), BEFORE profile
+                // sourcing — same ordering rationale as the plain exports (#98).
+                ...(secretFile.path ? [`source ${shellQuote(secretFile.path)} && rm -f ${shellQuote(secretFile.path)}`] : []),
+                // Plain env vars BEFORE profile sourcing — profiles that call `exec` (e.g.
+                // oh-my-zsh) would otherwise lose the exports and the claude command (#98)
+                plainExports,
+                profileSource,
+                `cd ${shellQuote(workDir)}`,
+                // `exec` so the shell is replaced by claude — when claude exits (clean or killed),
+                // the script process ends and Terminal.app closes the window per its settings.
+                // Without `exec`, bash waits for claude and then returns to prompt, leaving the
+                // window open. Parity with the WT `closeOnExit: 'always'` fix from #166.
+                `exec ${shellQuote(claudeBin)} ${claudeArgs.map(a => shellQuote(a)).join(' ')}`,
+            ];
         }
-        const envExports = Object.entries(envVars)
-            .map(([k, v]) => `export ${k}=${shellQuote(v)}`)
-            .join('\n');
-        const lines = [
-            '#!/bin/bash',
-            // Env vars BEFORE profile sourcing — profiles that call `exec` (e.g. oh-my-zsh)
-            // would otherwise lose the exports and the claude command (#98)
-            envExports,
-            profileSource,
-            `cd ${shellQuote(workDir)}`,
-            // `exec` so the shell is replaced by claude — when claude exits (clean or killed),
-            // the script process ends and Terminal.app closes the window per its settings.
-            // Without `exec`, bash waits for claude and then returns to prompt, leaving the
-            // window open. Parity with the WT `closeOnExit: 'always'` fix from #166.
-            `exec ${shellQuote(claudeBin)} ${claudeArgs.map(a => shellQuote(a)).join(' ')}`,
-        ];
-        (0, fs_1.writeFileSync)(scriptPath, lines.join('\n') + '\n', { mode: 0o755 });
+        (0, fs_1.writeFileSync)(scriptPath, lines.join('\n') + '\n', { mode: 0o700 });
         log('Using Terminal.app .command path:', scriptPath);
         const child = (0, child_process_1.spawn)('open', [scriptPath], { detached: true, stdio: 'ignore' });
         child.unref();
@@ -364,18 +498,20 @@ function launchInTerminal(bin, args, workDir, envVars) {
             // Ensure our profile with icon exists in Windows Terminal settings
             const hasProfile = ensureWindowsTerminalProfile();
             // Build inline env var assignments for cmd /c since wt.exe spawns
-            // a new process that won't inherit our env.
-            // Escape values for cmd.exe: wrap in quotes and escape inner special chars.
-            const cmdEscape = (s) => s.replace(/([&|<>^"%])/g, '^$1');
-            const setCmds = Object.entries(envVars)
+            // a new process that won't inherit our env. (cmdEscape is module-level.)
+            // #689 — SECRET env goes to a sourced 0600 .cmd file (call + del before the
+            // bin runs) so JWTs never land in the wt.exe command / cmd history; PLAIN env
+            // stays inline as `set "K=v"`.
+            const { plainEnv, secretEnv } = partitionEnv(envVars);
+            const secretFile = writeSecretEnvFile(secretEnv, { syntax: 'cmd' });
+            const setCmds = Object.entries(plainEnv)
                 .map(([k, v]) => `set "${k}=${cmdEscape(v)}"`)
                 .join(' && ');
             // Quote the binary path if it contains spaces (e.g., "C:\Program Files\...")
             const quotedWinBin = claudeBin.includes(' ') ? `"${cmdEscape(claudeBin)}"` : cmdEscape(claudeBin);
             const claudeCmd = `${quotedWinBin} ${claudeArgs.map(a => `"${cmdEscape(a)}"`).join(' ')}`;
-            const innerCmd = setCmds
-                ? `${setCmds} && ${claudeCmd}`
-                : claudeCmd;
+            const inlinePart = setCmds ? `${setCmds} && ${claudeCmd}` : claudeCmd;
+            const innerCmd = `${secretFile.sourcePrefix}${inlinePart}`;
             // Use `cmd.exe /c start "" wt.exe ...` to resolve the UWP app alias
             // When our profile exists, use --profile to get the tab icon
             const wtArgs = [
@@ -404,11 +540,19 @@ function launchInTerminal(bin, args, workDir, envVars) {
         child.unref();
         return { pid: child.pid };
     }
-    // Linux
-    const envExports = Object.entries(envVars)
+    // Linux — #689: SECRET env → sourced 0600 file (source+rm before the bin); PLAIN
+    // env stays inline `export`. One fullCmd covers both the terminal `-e` path and
+    // the headless `bash -c` fallback below (also closes the gnome-terminal-server
+    // env-inheritance gap for free).
+    const { plainEnv, secretEnv } = partitionEnv(envVars);
+    const secretFile = writeSecretEnvFile(secretEnv, { syntax: 'posix' });
+    const secretSource = secretFile.path
+        ? `source ${shellQuote(secretFile.path)}; rm -f ${shellQuote(secretFile.path)}; `
+        : '';
+    const plainExports = Object.entries(plainEnv)
         .map(([k, v]) => `export ${k}=${shellQuote(v)}`)
         .join('; ');
-    const fullCmd = `${envExports}; cd ${shellQuote(workDir)} && ${shellQuote(claudeBin)} ${claudeArgs.map(a => shellQuote(a)).join(' ')}`;
+    const fullCmd = `${secretSource}${plainExports ? `${plainExports}; ` : ''}cd ${shellQuote(workDir)} && ${shellQuote(claudeBin)} ${claudeArgs.map(a => shellQuote(a)).join(' ')}`;
     const terminal = findLinuxTerminal();
     if (!terminal) {
         log('No terminal emulator found on Linux, falling back to headless spawn');
@@ -549,10 +693,9 @@ function resolveBridgePath() {
  */
 function spawnCopilotBridge(opts) {
     const { cmd, args } = resolveBridgePath();
-    const logDirPath = opts.logDir || (0, path_1.join)(opts.workDir, 'logs');
     const logName = opts.name || `copilot-${Date.now()}`;
-    const logPath = (0, path_1.join)(logDirPath, `${logName}.log`);
-    const pidPath = (0, path_1.join)(logDirPath, `${logName}.pid`);
+    // #690 — central ~/.agent-tempo/logs/<ensemble>/ (overrideDir = opts.logDir wins).
+    const { dir: logDirPath, logPath, pidPath } = (0, config_1.bridgeLogPaths)(opts.ensemble, logName, opts.logDir);
     (0, fs_1.mkdirSync)(logDirPath, { recursive: true });
     const logFd = (0, fs_1.openSync)(logPath, 'a');
     let child;
@@ -564,6 +707,7 @@ function spawnCopilotBridge(opts) {
             env: {
                 ...process.env,
                 [config_1.ENV.ENSEMBLE]: opts.ensemble,
+                [config_1.ENV.PID_FILE]: pidPath, // #690 — adapter writes/unlinks THIS exact path (no re-derive → no split-brain)
                 [config_1.ENV.BRIDGE_NAME]: opts.name,
                 [config_1.ENV.PLAYER_NAME]: '', // Clear parent's player name so child uses BRIDGE_NAME
                 [config_1.ENV.BRIDGE_MODE]: '', // Clear parent's bridge mode
@@ -614,10 +758,9 @@ function resolveMockAdapterPath() {
  */
 function spawnMockAdapter(opts) {
     const { cmd, args } = resolveMockAdapterPath();
-    const logDirPath = opts.logDir || (0, path_1.join)(opts.workDir, 'logs');
     const logName = opts.name || `mock-${Date.now()}`;
-    const logPath = (0, path_1.join)(logDirPath, `${logName}.log`);
-    const pidPath = (0, path_1.join)(logDirPath, `${logName}.pid`);
+    // #690 — central ~/.agent-tempo/logs/<ensemble>/ (overrideDir = opts.logDir wins).
+    const { dir: logDirPath, logPath, pidPath } = (0, config_1.bridgeLogPaths)(opts.ensemble, logName, opts.logDir);
     (0, fs_1.mkdirSync)(logDirPath, { recursive: true });
     const logFd = (0, fs_1.openSync)(logPath, 'a');
     let child;
@@ -629,6 +772,7 @@ function spawnMockAdapter(opts) {
             env: {
                 ...process.env,
                 [config_1.ENV.ENSEMBLE]: opts.ensemble,
+                [config_1.ENV.PID_FILE]: pidPath, // #690 — adapter writes/unlinks THIS exact path (no re-derive → no split-brain)
                 [config_1.ENV.PLAYER_NAME]: opts.name,
                 [config_1.ENV.CONDUCTOR]: opts.isConductor ? 'true' : '',
                 [config_1.ENV.TEMPORAL_ADDRESS]: opts.temporalAddress,
@@ -682,10 +826,9 @@ function resolveClaudeApiPath() {
  */
 function spawnClaudeApiAdapter(opts) {
     const { cmd, args } = resolveClaudeApiPath();
-    const logDirPath = opts.logDir || (0, path_1.join)(opts.workDir, 'logs');
     const logName = opts.name || `claude-api-${Date.now()}`;
-    const logPath = (0, path_1.join)(logDirPath, `${logName}.log`);
-    const pidPath = (0, path_1.join)(logDirPath, `${logName}.pid`);
+    // #690 — central ~/.agent-tempo/logs/<ensemble>/ (overrideDir = opts.logDir wins).
+    const { dir: logDirPath, logPath, pidPath } = (0, config_1.bridgeLogPaths)(opts.ensemble, logName, opts.logDir);
     (0, fs_1.mkdirSync)(logDirPath, { recursive: true });
     const logFd = (0, fs_1.openSync)(logPath, 'a');
     let child;
@@ -697,6 +840,7 @@ function spawnClaudeApiAdapter(opts) {
             env: {
                 ...process.env,
                 [config_1.ENV.ENSEMBLE]: opts.ensemble,
+                [config_1.ENV.PID_FILE]: pidPath, // #690 — adapter writes/unlinks THIS exact path (no re-derive → no split-brain)
                 [config_1.ENV.PLAYER_NAME]: opts.name,
                 [config_1.ENV.CONDUCTOR]: opts.isConductor ? 'true' : '',
                 [config_1.ENV.TEMPORAL_ADDRESS]: opts.temporalAddress,
@@ -749,10 +893,9 @@ function resolveOpenCodePath() {
  */
 function spawnOpenCodeAdapter(opts) {
     const { cmd, args } = resolveOpenCodePath();
-    const logDirPath = opts.logDir || (0, path_1.join)(opts.workDir, 'logs');
     const logName = opts.name || `opencode-${Date.now()}`;
-    const logPath = (0, path_1.join)(logDirPath, `${logName}.log`);
-    const pidPath = (0, path_1.join)(logDirPath, `${logName}.pid`);
+    // #690 — central ~/.agent-tempo/logs/<ensemble>/ (overrideDir = opts.logDir wins).
+    const { dir: logDirPath, logPath, pidPath } = (0, config_1.bridgeLogPaths)(opts.ensemble, logName, opts.logDir);
     (0, fs_1.mkdirSync)(logDirPath, { recursive: true });
     const logFd = (0, fs_1.openSync)(logPath, 'a');
     let child;
@@ -764,6 +907,7 @@ function spawnOpenCodeAdapter(opts) {
             env: {
                 ...process.env,
                 [config_1.ENV.ENSEMBLE]: opts.ensemble,
+                [config_1.ENV.PID_FILE]: pidPath, // #690 — adapter writes/unlinks THIS exact path (no re-derive → no split-brain)
                 [config_1.ENV.PLAYER_NAME]: opts.name,
                 [config_1.ENV.CONDUCTOR]: opts.isConductor ? 'true' : '',
                 [config_1.ENV.TEMPORAL_ADDRESS]: opts.temporalAddress,
@@ -811,10 +955,9 @@ function resolvePiPath() {
  */
 function spawnPiHeadless(opts) {
     const { cmd, args } = resolvePiPath();
-    const logDirPath = opts.logDir || (0, path_1.join)(opts.workDir, 'logs');
     const logName = opts.name || `pi-${Date.now()}`;
-    const logPath = (0, path_1.join)(logDirPath, `${logName}.log`);
-    const pidPath = (0, path_1.join)(logDirPath, `${logName}.pid`);
+    // #690 — central ~/.agent-tempo/logs/<ensemble>/ (overrideDir = opts.logDir wins).
+    const { dir: logDirPath, logPath, pidPath } = (0, config_1.bridgeLogPaths)(opts.ensemble, logName, opts.logDir);
     (0, fs_1.mkdirSync)(logDirPath, { recursive: true });
     const logFd = (0, fs_1.openSync)(logPath, 'a');
     const toolAccess = opts.toolAccess || 'restricted';
@@ -827,6 +970,7 @@ function spawnPiHeadless(opts) {
             env: {
                 ...process.env,
                 [config_1.ENV.ENSEMBLE]: opts.ensemble,
+                [config_1.ENV.PID_FILE]: pidPath, // #690 — adapter writes/unlinks THIS exact path (no re-derive → no split-brain)
                 [config_1.ENV.PLAYER_NAME]: opts.name,
                 [config_1.ENV.CONDUCTOR]: opts.isConductor ? 'true' : '',
                 [config_1.ENV.TEMPORAL_ADDRESS]: opts.temporalAddress,
@@ -890,10 +1034,9 @@ function resolveClaudeCodeHeadlessPath() {
  */
 function spawnClaudeCodeHeadlessAdapter(opts) {
     const { cmd, args } = resolveClaudeCodeHeadlessPath();
-    const logDirPath = opts.logDir || (0, path_1.join)(opts.workDir, 'logs');
     const logName = opts.name || `claude-code-headless-${Date.now()}`;
-    const logPath = (0, path_1.join)(logDirPath, `${logName}.log`);
-    const pidPath = (0, path_1.join)(logDirPath, `${logName}.pid`);
+    // #690 — central ~/.agent-tempo/logs/<ensemble>/ (overrideDir = opts.logDir wins).
+    const { dir: logDirPath, logPath, pidPath } = (0, config_1.bridgeLogPaths)(opts.ensemble, logName, opts.logDir);
     (0, fs_1.mkdirSync)(logDirPath, { recursive: true });
     const logFd = (0, fs_1.openSync)(logPath, 'a');
     let child;
@@ -905,6 +1048,7 @@ function spawnClaudeCodeHeadlessAdapter(opts) {
             env: {
                 ...process.env,
                 [config_1.ENV.ENSEMBLE]: opts.ensemble,
+                [config_1.ENV.PID_FILE]: pidPath, // #690 — adapter writes/unlinks THIS exact path (no re-derive → no split-brain)
                 [config_1.ENV.PLAYER_NAME]: opts.name,
                 [config_1.ENV.CONDUCTOR]: opts.isConductor ? 'true' : '',
                 [config_1.ENV.TEMPORAL_ADDRESS]: opts.temporalAddress,