agent-tempo 1.6.1 → 1.7.0-beta.0

package/dashboard/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-tempo-dashboard",
   "private": true,
-  "version": "1.6.1",
+  "version": "1.7.0-beta.0",
   "type": "module",
   "description": "Web dashboard for agent-tempo. Bundled into the npm package; served by the daemon at /dashboard/*.",
   "scripts": {

package/dist/activities/hard-terminate.js

@@ -30,6 +30,7 @@ exports.hardTerminateAttachment = hardTerminateAttachment;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const path_1 = require("path");
+const config_1 = require("../config");
 const constants_1 = require("../constants");
 const log = (...args) => console.error('[agent-tempo:hard-terminate]', ...args);
 /**
@@ -43,8 +44,13 @@ async function hardTerminateAttachment(input) {
     log(`hardTerminate start — ensemble=${ensemble} player=${playerName} agent=${agent}`);
     // ── Copilot bridge: PID file is authoritative ──
     if (agent === 'copilot') {
-        const pidDir = logDir || (0, path_1.join)(workDir, 'logs');
-        const pidPath = (0, path_1.join)(pidDir, `${playerName}.pid`);
+        // #690 — pid lives at the CENTRAL ~/.agent-tempo/logs/<ensemble>/ path now.
+        // Transitional (one version, v1.6.2) READ-ONLY fallback to the legacy per-cwd
+        // <workDir>/logs so we can still find+kill an orphan from a pre-upgrade spawn.
+        // TODO(v1.7): drop the legacy fallback.
+        const centralPid = (0, config_1.bridgeLogPaths)(ensemble, playerName, logDir).pidPath;
+        const legacyPid = (0, path_1.join)(logDir || (0, path_1.join)(workDir, 'logs'), `${playerName}.pid`);
+        const pidPath = (0, fs_1.existsSync)(centralPid) ? centralPid : legacyPid;
         if ((0, fs_1.existsSync)(pidPath)) {
             try {
                 const pidStr = (0, fs_1.readFileSync)(pidPath, 'utf8').trim();

package/dist/adapters/claude-api/adapter.js

@@ -332,10 +332,11 @@ class DirectApiAttachment extends base_1.SdkAttachment {
             process.exit(1);
         }
         // PID file so callers can find / kill orphaned adapter processes.
-        const pidDir = path.join(workDir, 'logs');
-        const pidFile = path.join(pidDir, `${playerIdForWorkflow}.pid`);
+        // #690 — write/unlink the EXACT path the spawner computed (ENV.PID_FILE) so the
+        // adapter pid can't diverge from the spawner's; helper fallback for a manual launch.
+        const pidFile = (0, config_1.resolveAdapterPidFile)(config.ensemble, playerIdForWorkflow);
         try {
-            fs.mkdirSync(pidDir, { recursive: true });
+            fs.mkdirSync(path.dirname(pidFile), { recursive: true });
             fs.writeFileSync(pidFile, String(process.pid));
         }
         catch (err) {

package/dist/adapters/claude-code-headless/adapter.js

@@ -353,10 +353,11 @@ class ClaudeCodeHeadlessAttachment extends base_1.SdkAttachment {
             process.exit(1);
         }
         // PID file so callers can find / kill orphaned adapter processes.
-        const pidDir = path.join(workDir, 'logs');
-        const pidFile = path.join(pidDir, `${playerIdForWorkflow}.pid`);
+        // #690 — write/unlink the EXACT path the spawner computed (ENV.PID_FILE) so the
+        // adapter pid can't diverge from the spawner's; helper fallback for a manual launch.
+        const pidFile = (0, config_1.resolveAdapterPidFile)(config.ensemble, playerIdForWorkflow);
         try {
-            fs.mkdirSync(pidDir, { recursive: true });
+            fs.mkdirSync(path.dirname(pidFile), { recursive: true });
             fs.writeFileSync(pidFile, String(process.pid));
         }
         catch (err) {

package/dist/adapters/copilot/adapter.js

@@ -386,8 +386,13 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
             log(`Initial prompt error after ${Date.now()}ms:`, err?.message, err?.stack?.substring(0, 300));
         }
         // PID file paths — computed early so early-exit paths can clean up
-        const pidDir = path.join(workDir, 'logs');
-        const pidFile = path.join(pidDir, `${playerName || playerIdForWorkflow}.pid`);
+        // #690 — write/unlink the EXACT path the spawner computed (ENV.PID_FILE), so this
+        // adapter's pid file can't diverge from the spawner's. The copilot split-brain was
+        // here: spawnCopilotBridge sets PLAYER_NAME='' + BRIDGE_NAME=name, so this
+        // re-derivation fell to `playerIdForWorkflow` (→ `copilot-${Date.now()}`) ≠ the
+        // spawner's logName. Consuming the passed path removes the re-derivation entirely.
+        // Helper fallback only for a manual launch with no env.
+        const pidFile = (0, config_1.resolveAdapterPidFile)(config.ensemble, playerName || playerIdForWorkflow);
         // Wait for the MCP server's workflow to register in Temporal.
         // We know the exact workflow ID because we pass AGENT_TEMPO_PLAYER_NAME to the
         // MCP server — no need for a time-window heuristic that could misidentify workflows.
@@ -485,7 +490,7 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
         // Imported at the top of this module.
         // Write PID file so callers can find/kill orphaned bridge processes
         try {
-            fs.mkdirSync(pidDir, { recursive: true });
+            fs.mkdirSync(path.dirname(pidFile), { recursive: true });
             fs.writeFileSync(pidFile, String(process.pid));
             log(`PID file written: ${pidFile}`);
         }

package/dist/adapters/opencode/adapter.js

@@ -239,7 +239,9 @@ class OpenCodeAttachment extends base_1.SdkAttachment {
         log(`Synthesized OPENCODE_CONFIG_CONTENT: ${(0, helpers_1.redactSecrets)(configContent)}`);
         // (3) Spawn opencode serve. Stdio redirected to a per-player log file
         // so terminal noise from opencode doesn't clutter the adapter's log.
-        const logDir = path.join(workDir, 'logs');
+        // #690 — central ~/.agent-tempo/logs/<ensemble>/ (the opencode serve subprocess
+        // log sits beside the adapter's own log, not in a per-cwd ./logs).
+        const logDir = (0, config_1.bridgeLogPaths)(config.ensemble, playerIdForWorkflow).dir;
         fs.mkdirSync(logDir, { recursive: true });
         const opencodeLogFile = path.join(logDir, `opencode-${playerIdForWorkflow}.log`);
         const logFd = fs.openSync(opencodeLogFile, 'a');

package/dist/cli/commands.js

@@ -805,7 +805,7 @@ async function status(opts) {
             const agent = s.agentType === 'copilot' ? out.dim(' [copilot]') : '';
             const statusLabel = phaseLabel(s.phase);
             // Show PID info for copilot bridge sessions
-            const pidInfo = s.agentType === 'copilot' ? getBridgePidInfo(s.name) : '';
+            const pidInfo = s.agentType === 'copilot' ? getBridgePidInfo(ensemble, s.name) : '';
             const name = out.bold(s.name);
             out.log(`  ${name}${role}${statusLabel}${agent}${pidInfo}`);
             if (s.part)
@@ -1065,6 +1065,9 @@ async function server(opts) {
 }
 async function up(opts) {
     const config = (0, config_1.getConfig)(opts);
+    // #689 — best-effort sweep of stale 0600 secret env files (residual from a shell
+    // that died between `source` and `rm`). Owner-only, swallows errors.
+    (0, spawn_1.sweepStaleSecretEnvFiles)();
     out.heading('agent-tempo setup');
     // Step 1: Check temporal CLI
     if (!temporalCliExists()) {
@@ -1910,8 +1913,13 @@ async function down(opts) {
  * Read PID info for a copilot bridge session from its PID file.
  * Returns a formatted string like " (pid 12345)" or "" if no PID file found.
  */
-function getBridgePidInfo(name) {
-    const pidPath = (0, path_1.join)(process.cwd(), 'logs', `${name}.pid`);
+function getBridgePidInfo(ensemble, name) {
+    // #690 — pid lives at the CENTRAL ~/.agent-tempo/logs/<ensemble>/ path; transitional
+    // READ-ONLY fallback to the legacy per-cwd ./logs for a pre-upgrade bridge.
+    // TODO(v1.7): drop the legacy fallback.
+    const centralPid = (0, config_1.bridgeLogPaths)(ensemble, name).pidPath;
+    const legacyPid = (0, path_1.join)(process.cwd(), 'logs', `${name}.pid`);
+    const pidPath = (0, fs_1.existsSync)(centralPid) ? centralPid : legacyPid;
     if (!(0, fs_1.existsSync)(pidPath))
         return '';
     try {
@@ -1932,36 +1940,63 @@ function getBridgePidInfo(name) {
     }
 }
 /**
- * Kill all bridge processes found in logs/*.pid and clean up PID files.
+ * Kill all bridge processes found in `*.pid` files and clean up the pid files.
+ *
+ * #690 — bridge pid files moved to the CENTRAL `~/.agent-tempo/logs/<ensemble>/`
+ * dirs. `down` is a GLOBAL teardown (it stops the daemon + Temporal for EVERY
+ * ensemble), so this scans ALL central ensemble subdirs — NOT a single ensemble.
+ *
+ * ⚠️ GLOBAL-TEARDOWN ONLY. The sole caller is `down()`, which has no ensemble (it
+ * stops everything), so scanning all ensembles is correct HERE. A FUTURE
+ * ensemble-scoped teardown (e.g. `down --ensemble X` / a per-ensemble `destroy`)
+ * MUST add an `ensemble` param and scope this to `bridgeLogPaths(ensemble, '').dir`
+ * — do NOT reuse this global scan-all from a scoped op: it would kill OTHER live
+ * ensembles' bridges. The param is intentionally NOT added now (no caller needs it
+ * = speculative; backlogged per the architect's deviation ruling).
+ *
+ * Plus a transitional READ of the legacy per-cwd `./logs` for a pre-upgrade
+ * bridge. TODO(v1.7): drop the legacy `./logs` dir.
  */
 function killBridgeProcesses() {
-    const logsDir = (0, path_1.join)(process.cwd(), 'logs');
-    if (!(0, fs_1.existsSync)(logsDir))
-        return;
+    const centralRoot = (0, config_1.bridgeLogsRoot)();
+    const dirs = [(0, path_1.join)(process.cwd(), 'logs')]; // legacy (transitional)
     try {
-        const pidFiles = (0, fs_1.readdirSync)(logsDir).filter(f => f.endsWith('.pid'));
-        for (const pidFile of pidFiles) {
-            const pidPath = (0, path_1.join)(logsDir, pidFile);
-            try {
-                const pid = parseInt((0, fs_1.readFileSync)(pidPath, 'utf8').trim(), 10);
-                if (!isNaN(pid)) {
-                    try {
-                        process.kill(pid);
-                        out.log(`  ${out.dim(`Killed bridge process ${pidFile.replace('.pid', '')} (pid ${pid})`)}`);
-                    }
-                    catch {
-                        // already dead
+        for (const ent of (0, fs_1.readdirSync)(centralRoot, { withFileTypes: true })) {
+            if (ent.isDirectory())
+                dirs.push((0, path_1.join)(centralRoot, ent.name));
+        }
+    }
+    catch {
+        // no central logs root yet — nothing central to scan
+    }
+    for (const logsDir of dirs) {
+        if (!(0, fs_1.existsSync)(logsDir))
+            continue;
+        try {
+            const pidFiles = (0, fs_1.readdirSync)(logsDir).filter(f => f.endsWith('.pid'));
+            for (const pidFile of pidFiles) {
+                const pidPath = (0, path_1.join)(logsDir, pidFile);
+                try {
+                    const pid = parseInt((0, fs_1.readFileSync)(pidPath, 'utf8').trim(), 10);
+                    if (!isNaN(pid)) {
+                        try {
+                            process.kill(pid);
+                            out.log(`  ${out.dim(`Killed bridge process ${pidFile.replace('.pid', '')} (pid ${pid})`)}`);
+                        }
+                        catch {
+                            // already dead
+                        }
                     }
+                    (0, fs_1.unlinkSync)(pidPath);
+                }
+                catch {
+                    // unreadable — skip
                 }
-                (0, fs_1.unlinkSync)(pidPath);
-            }
-            catch {
-                // unreadable — skip
             }
         }
-    }
-    catch {
-        // logs dir unreadable
+        catch {
+            // logs dir unreadable
+        }
     }
 }
 async function agentTypesCommand(opts) {

package/dist/cli/config-command.d.ts

@@ -19,8 +19,6 @@ import type { AgentType } from '../types';
  * stale subset; this one is intentionally narrow and must stay that way.
  */
 export declare const VALID_DEFAULT_AGENTS: readonly AgentType[];
-/** True when a config key holds a credential value that must be masked on display. */
-export declare function isSecretKey(key: string): boolean;
 /**
  * Render a secret for display: a short non-sensitive prefix (when the value is
  * long enough that the prefix reveals only a small fraction) + a masked tail +

package/dist/cli/config-command.js

@@ -34,7 +34,6 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VALID_DEFAULT_AGENTS = void 0;
-exports.isSecretKey = isSecretKey;
 exports.maskSecret = maskSecret;
 exports.configInteractive = configInteractive;
 exports.configSet = configSet;
@@ -43,6 +42,7 @@ exports.configCommand = configCommand;
 const readline = __importStar(require("readline"));
 const config_1 = require("../config");
 const config_2 = require("../config");
+const secrets_1 = require("../utils/secrets");
 const out = __importStar(require("./output"));
 /**
  * Agents valid as a persistent `defaultAgent` — the conductor-capable PRODUCTION
@@ -71,18 +71,9 @@ exports.VALID_DEFAULT_AGENTS = ['claude', 'copilot', 'pi'];
 // under a broken Temporal SDK install.
 // #684 — secret-masking. Any config field whose name looks like a credential is
 // masked in EVERY display path (show / interactive default / set echo) so a key is
-// never printed raw (terminal scrollback, screen-share, logs). Generalized on
-// purpose: a future secret added to the config is masked BY DEFAULT, not leaked.
-const SECRET_KEYS = new Set(['temporalApiKey', 'httpToken', 'readToken', 'adminToken']);
-// Matches *_API_KEY / *ApiKey / *Token / *Secret / *Password but NOT path fields
-// (e.g. temporalTlsKeyPath is a file path, not the key — it must stay visible).
-const SECRET_KEY_PATTERN = /(api[_-]?key|token|secret|password)/i;
-/** True when a config key holds a credential value that must be masked on display. */
-function isSecretKey(key) {
-    if (/path$/i.test(key))
-        return false; // *Path fields are file locations, not secrets
-    return SECRET_KEYS.has(key) || SECRET_KEY_PATTERN.test(key);
-}
+// never printed raw (terminal scrollback, screen-share, logs). The classifier
+// (`isSecretKey`) was extracted to `utils/secrets.ts` in #689 so `spawn.ts` shares
+// it — a future secret masks AND stays off the command line everywhere at once.
 /**
  * Render a secret for display: a short non-sensitive prefix (when the value is
  * long enough that the prefix reveals only a small fraction) + a masked tail +
@@ -257,7 +248,7 @@ function configSet(key, value) {
     (0, config_1.saveConfigFile)(config);
     // #684 — echo through the same secret-masking path so `config set temporalApiKey …`
     // never prints the value back raw (and a *Path field still shows its location).
-    out.success(`Set ${configKey} = ${isSecretKey(configKey) ? maskSecret(value) : value}`);
+    out.success(`Set ${configKey} = ${(0, secrets_1.isSecretKey)(configKey) ? maskSecret(value) : value}`);
 }
 /** Show current config: `agent-tempo config show` */
 function configShow() {
@@ -281,7 +272,7 @@ function configShow() {
         const source = sources[configKey];
         // #684 — secret-like fields go through maskSecret (prefix + masked tail + char
         // count); everything else shows its value or "(not set)".
-        const display = isSecretKey(key) ? maskSecret(value) : (!value ? '(not set)' : value);
+        const display = (0, secrets_1.isSecretKey)(key) ? maskSecret(value) : (!value ? '(not set)' : value);
         out.log(`  ${key.padEnd(22)} ${display.padEnd(30)} ${out.dim(source)}`);
     }
     console.log();

package/dist/config.d.ts

@@ -130,6 +130,15 @@ export declare const ENV: {
      * spawns do NOT set it, so recruited adapters keep the #604 anti-leak ppid-poll.
      */
     readonly 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`.
+     */
+    readonly 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
@@ -226,6 +235,48 @@ export declare function isDevMode(): boolean;
 export declare function resolveTempoHome(): string;
 export declare const AGENT_TEMPO_HOME: string;
 export declare const CONFIG_FILE_PATH: string;
+/** Resolved log + pid paths for a recruited bridge/adapter player (#690). */
+export interface BridgeLogPaths {
+    /** The directory holding the player's log + pid files. */
+    dir: string;
+    /** `<dir>/<player>.log`. */
+    logPath: string;
+    /** `<dir>/<player>.pid`. */
+    pidPath: string;
+}
+/**
+ * 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.
+ */
+export declare function bridgeLogsRoot(): string;
+export declare function bridgeLogPaths(ensemble: string, player: string, overrideDir?: string): BridgeLogPaths;
+/**
+ * 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).
+ */
+export declare function resolveAdapterPidFile(ensemble: string, fallbackPlayer: string): string;
 /**
  * Daemon-level configuration persisted in `~/.agent-tempo/config.json`
  * alongside the existing `PersistedConfig` fields.

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;
@@ -155,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
@@ -223,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`

package/dist/pi/extension.js

@@ -188,6 +188,34 @@ function createPiExtension(options = {}) {
         };
         (0, render_tools_1.renderToPi)(pi, (0, server_tools_1.buildAllTempoTools)(toolOpts));
         log(`registered tools (player=${currentPlayerId}, conductor=${isConductor}, mode=${mode})`);
+        // ── #698 — FULL server-instruction preamble into the Pi system prompt ──
+        // The Pi equivalent of MCP players' `buildServerInstructions` (#695 S2 seeded
+        // this hook with just the 4 yield-norms; #698 widens it to the WHOLE preamble —
+        // identity, cue/report/recruit guidance, Communication-discipline, and the
+        // conductor/player operational rules). SINGLE-SOURCED off `buildServerInstructions`
+        // so MCP + Pi guidance can't drift; the yield-norms now arrive FOLDED IN (they
+        // live inside that builder since #695 S1), so there is no separate const.
+        // `before_agent_start` exposes the fully-assembled systemPrompt and accepts a
+        // replacement (chained across extensions), so we APPEND — injected into the
+        // model's system prompt every turn, invisibly (NOT a sendMessage, which would
+        // spam the transcript). Applies to ALL Pi players (interactive + headless).
+        //
+        // Opts are built PER FIRE (before_agent_start fires every turn): playerId and
+        // hasRequestedName must reflect CURRENT state, so a `set_name`-renamed player
+        // gets the right identity rather than the boot-time one.
+        const piInstructionOpts = () => ({
+            ensemble: config.ensemble,
+            playerId: toolOpts.getPlayerId(),
+            isConductor,
+            playerType: process.env[config_1.ENV.PLAYER_TYPE] || undefined,
+            // playerTypeDescription omitted (MVP — not threaded into the Pi runtime).
+            hasRequestedName: Boolean(process.env[config_1.ENV.PLAYER_NAME]),
+        });
+        // Cast mirrors the tool_call returning-handler pattern (the shim's `on` is
+        // void-typed; the real ExtensionAPI before_agent_start handler returns a result).
+        pi.on('before_agent_start', (ev) => ({
+            systemPrompt: `${ev.systemPrompt ?? ''}\n\n${(0, server_tools_1.buildServerInstructions)(piInstructionOpts())}`,
+        }));
         // ── #677 PART B — interactive-only `/tempo-reset` command ──
         // Pi's `newSession` (clean-wipe) is ExtensionCommandContext-ONLY (not on the
         // SDK session), so an interactive Pi conductor can ONLY be reset by the operator

package/dist/pi/pi-types.d.ts

@@ -191,6 +191,24 @@ export interface PiToolCallResult {
     block?: boolean;
     reason?: string;
 }
+/**
+ * `before_agent_start` payload (#695). Pi fires this after the user prompt is
+ * assembled but before the agent loop; it carries the fully-built `systemPrompt`.
+ * A handler returns {@link PiBeforeAgentStartResult} to replace it. We read only
+ * `systemPrompt` (to append the yield norms); kept open for forward-compat.
+ */
+export interface PiBeforeAgentStartEvent {
+    /** The fully-assembled system prompt string for this turn. */
+    systemPrompt?: string;
+}
+/**
+ * Result of a `before_agent_start` handler (#695). Returning `systemPrompt`
+ * REPLACES the system prompt for the turn ("If multiple extensions return this,
+ * they are chained" — Pi 0.78). We append the yield norms and return it.
+ */
+export interface PiBeforeAgentStartResult {
+    systemPrompt?: string;
+}
 /**
  * Pi tool result — a Pi-free structural mirror of the real `AgentToolResult`
  * (#653, 1.4.2). The Phase-0 `{ output, isError }` guess was WRONG: Pi's real

package/dist/server-tools.js

@@ -138,6 +138,11 @@ function buildServerInstructions(opts) {
         `Use \`report\` to notify the conductor of task completion, blockers, or questions — always report when you finish a recruited task.` +
         `\n\nCommunication discipline:\n` +
         `- Drafting a response in your turn is not the same as sending one. The conductor and other players cannot read your reasoning — only your \`cue\` and \`report\` tool calls cross the channel boundary. If you reach a decision, ruling, or status update, fire the appropriate tool before moving on. If you find yourself thinking "I already answered that," verify the tool was actually invoked.` +
+        // #695 — yield-don't-poll norms (apply to all MCP players).
+        `\n- Yield after dispatch — after cueing a player and expecting a reply, end your turn. Inbound cues wake you automatically at the next turn boundary; there is nothing to poll.` +
+        `\n- \`listen\` is a one-shot inbox drain, not a wait primitive — it reads whatever is already queued at call time. A \`sleep\`+\`listen\` loop does not work as a wait and is an anti-pattern that burns tokens across the ensemble. If you're waiting for a reply, end your turn.` +
+        `\n- Don't reply to ack/FYI cues — if a player sends a status update or acknowledgment without asking a question or requesting action, do not respond. Responding starts a ping-pong that wastes turns on both sides.` +
+        `\n- Cues queue, they don't interrupt — a cue sent to you while you're processing arrives at your next turn boundary, not mid-turn. A burst from multiple players arrives together; process the batch in one turn.` +
         (isConductor
             ? `\n\nOperational rules:\n` +
                 `- Before assigning parallel work on different branches, provision git worktrees via the \`worktree\` tool so each player has an isolated checkout.\n` +

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,

package/dist/utils/secrets.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared secret-classification — the single source of truth for "does this config
+ * key / env-var name hold a credential?" Used by:
+ *   - `cli/config-command.ts` — masks secret VALUES in the config display (#684).
+ *   - `spawn.ts` — partitions terminal-launch env so secret VALUES go to a 0600
+ *     file instead of being inlined into the echoed command (#689).
+ *
+ * Lives in `utils/` (not `cli/`) so `spawn.ts` can import it without a layering
+ * violation (spawn must not depend on the CLI surface). Extracted from
+ * config-command.ts in #689 so the two consumers share ONE classifier and can't
+ * drift — a secret added to the pattern is masked AND kept off the command line
+ * everywhere at once.
+ */
+/**
+ * Config/env keys that hold a credential value and must never be displayed raw or
+ * inlined into a command. Extend this (or {@link SECRET_KEY_PATTERN}) when a new
+ * secret config field / env var is introduced — both consumers pick it up.
+ */
+export declare const SECRET_KEYS: Set<string>;
+/**
+ * Matches credential-bearing key/env names: `*_API_KEY` / `*ApiKey` / `*Token` /
+ * `*Secret` / `*Password`. NOT `*Path` fields (those are file LOCATIONS, not the
+ * secret material — e.g. `temporalTlsKeyPath` must stay visible); the `path$`
+ * guard in {@link isSecretKey} excludes them.
+ */
+export declare const SECRET_KEY_PATTERN: RegExp;
+/**
+ * True when a config key or environment-variable name holds a credential value
+ * that must be masked on display and kept out of an echoed command line.
+ *
+ * Keys on the NAME, not the value. `*Path` fields are file locations (not secret
+ * material) and are explicitly excluded so they stay visible/inline.
+ */
+export declare function isSecretKey(key: string): boolean;

package/dist/utils/secrets.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Shared secret-classification — the single source of truth for "does this config
+ * key / env-var name hold a credential?" Used by:
+ *   - `cli/config-command.ts` — masks secret VALUES in the config display (#684).
+ *   - `spawn.ts` — partitions terminal-launch env so secret VALUES go to a 0600
+ *     file instead of being inlined into the echoed command (#689).
+ *
+ * Lives in `utils/` (not `cli/`) so `spawn.ts` can import it without a layering
+ * violation (spawn must not depend on the CLI surface). Extracted from
+ * config-command.ts in #689 so the two consumers share ONE classifier and can't
+ * drift — a secret added to the pattern is masked AND kept off the command line
+ * everywhere at once.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECRET_KEY_PATTERN = exports.SECRET_KEYS = void 0;
+exports.isSecretKey = isSecretKey;
+/**
+ * Config/env keys that hold a credential value and must never be displayed raw or
+ * inlined into a command. Extend this (or {@link SECRET_KEY_PATTERN}) when a new
+ * secret config field / env var is introduced — both consumers pick it up.
+ */
+exports.SECRET_KEYS = new Set([
+    'temporalApiKey',
+    'httpToken',
+    'readToken',
+    'adminToken',
+]);
+/**
+ * Matches credential-bearing key/env names: `*_API_KEY` / `*ApiKey` / `*Token` /
+ * `*Secret` / `*Password`. NOT `*Path` fields (those are file LOCATIONS, not the
+ * secret material — e.g. `temporalTlsKeyPath` must stay visible); the `path$`
+ * guard in {@link isSecretKey} excludes them.
+ */
+exports.SECRET_KEY_PATTERN = /(api[_-]?key|token|secret|password)/i;
+/**
+ * True when a config key or environment-variable name holds a credential value
+ * that must be masked on display and kept out of an echoed command line.
+ *
+ * Keys on the NAME, not the value. `*Path` fields are file locations (not secret
+ * material) and are explicitly excluded so they stay visible/inline.
+ */
+function isSecretKey(key) {
+    if (/path$/i.test(key))
+        return false;
+    return exports.SECRET_KEYS.has(key) || exports.SECRET_KEY_PATTERN.test(key);
+}

package/examples/agents/tempo-conductor.md

@@ -57,6 +57,18 @@ You are a combination of Product Manager, Task Decomposition Expert, and Context
 - **Wrap-up**: Collect final reports, synthesize results, `detach` players who may be needed again (or `destroy` those who are truly done), report completion.
 - **Autonomous work session**: Pre-flight (check ensemble state — skip if active work is in progress) → review backlog → close completed items → identify tasks your ensemble can handle autonomously (flag those needing human design input) → kick off, track to completion, summarize results.
 
+## Message Delivery Model
+
+Understanding how cues are delivered prevents the most common conductor anti-pattern — busy-waiting for replies.
+
+**Cues wake you; you don't need to poll.** After cueing a player and expecting a reply, end your turn. When the reply arrives, the runtime wakes you automatically at the next turn boundary. There is nothing to poll.
+
+**`listen` is a one-shot inbox drain, not a wait primitive.** `listen` reads whatever messages are already queued at call time — it cannot block or wait for future messages. A `sleep`+`listen` loop does not work as a wait: it burns tokens across every player in the ensemble without advancing any work. If you're waiting for a reply, end your turn.
+
+**Don't reply to ack/FYI cues.** If a player sends a status update or acknowledgment without asking a question or requesting action, do not respond. Responding starts a ping-pong — your reply wakes them, they acknowledge, you're awake again — that wastes turns on both sides for zero information transfer.
+
+**Cues queue, they don't interrupt.** A cue sent to you while you're processing arrives at your next turn boundary, not mid-turn. A burst from multiple players arrives together; process the batch in one turn rather than starting a separate turn for each.
+
 ## Worktree Coordination
 
 Use the `worktree` tool to give players isolated git checkouts when two or more engineers need to work in the same repo on different branches simultaneously. Each worktree is an independent checkout — players can build, test, and commit without interfering with each other.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tempo",
-  "version": "1.6.1",
+  "version": "1.7.0-beta.0",
   "description": "Many agents, one tempo. Durable coordination for multi-agent work via Temporal.",
   "keywords": [
     "mcp",