aicodeman 1.2.1 → 1.3.0

package/dist/remote-hosts.js

@@ -0,0 +1,198 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+const REMOTE_HOSTS_FILE = 'remote-hosts.json';
+const REMOTE_CASES_FILE = 'remote-cases.json';
+export function remoteHostsPath(configDir) {
+    return join(configDir, REMOTE_HOSTS_FILE);
+}
+export function remoteCasesPath(configDir) {
+    return join(configDir, REMOTE_CASES_FILE);
+}
+async function readJsonArray(path) {
+    try {
+        const raw = await fs.readFile(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function writeJsonArray(configDir, path, value) {
+    if (!existsSync(configDir))
+        mkdirSync(configDir, { recursive: true });
+    await fs.writeFile(path, JSON.stringify(value, null, 2));
+}
+export async function readRemoteHosts(configDir) {
+    return readJsonArray(remoteHostsPath(configDir));
+}
+export async function writeRemoteHosts(configDir, hosts) {
+    await writeJsonArray(configDir, remoteHostsPath(configDir), hosts);
+}
+export async function readRemoteCases(configDir) {
+    return readJsonArray(remoteCasesPath(configDir));
+}
+export async function writeRemoteCases(configDir, cases) {
+    await writeJsonArray(configDir, remoteCasesPath(configDir), cases);
+}
+export function defaultRemoteCommandForMode(mode) {
+    const commands = {
+        shell: 'exec bash -l',
+        // Mirror the LOCAL claude default so the remote agent runs non-interactively
+        // (no trust-folder/permission prompt that nothing on the remote answers). The
+        // per-host `commands.claude` override stays the escape hatch.
+        claude: 'exec claude --dangerously-skip-permissions',
+        opencode: 'exec opencode',
+        codex: 'exec codex',
+        gemini: 'exec gemini',
+    };
+    return commands[mode] || commands.shell;
+}
+export function remoteSshTarget(host) {
+    return `${host.username}@${host.host}`;
+}
+/**
+ * POSIX single-quote shell-escaping (end-quote, escaped-quote, restart-quote).
+ * Mirrors the helper in tmux-manager.ts so a value with spaces/metachars stays a
+ * single shell token. Used here for identity paths and `-o KEY=VALUE` options.
+ */
+function shellescape(str) {
+    return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+/**
+ * Expand a leading `~` or `$HOME` in an identity path to an absolute path.
+ *
+ * ssh does NOT expand `~` inside `-i` (the shell would, but we shellescape the
+ * value into a single quoted token so the shell never sees it). So we expand at
+ * build time, before escaping. Non-`~`/`$HOME` paths are returned unchanged.
+ */
+function expandIdentityPath(identityFile) {
+    if (identityFile === '~')
+        return homedir();
+    if (identityFile.startsWith('~/'))
+        return join(homedir(), identityFile.slice(2));
+    if (identityFile === '$HOME')
+        return homedir();
+    if (identityFile.startsWith('$HOME/'))
+        return join(homedir(), identityFile.slice('$HOME/'.length));
+    return identityFile;
+}
+/**
+ * COD-107 — build the ordered, shell-safe ssh CONNECTION tokens shared by both
+ * the durable-launch command (`buildRemoteLaunchCommand`) and the tmux
+ * prerequisite probe (`buildRemoteTmuxCheckCommand`), so the prereq check and
+ * the real launch connect with IDENTICAL options (they can't drift).
+ *
+ * Returns the leading tokens of an ssh command line (NOT including `-t`, the
+ * target, or any remote command). Order:
+ *   ssh -o BatchMode=yes
+ *       [-o ConnectTimeout=10]           (default; suppressed if extraSshOptions sets it)
+ *       [-p <port>]
+ *       [-i <abs-identity>]              (~/$HOME expanded, then shellescaped)
+ *       [-J <jumpHost>]                  (shellescaped, single token)
+ *       [-o ProxyCommand=nc -X 5 -x <socks> %h %p]   (ONE shellescaped -o token)
+ *       [-o <KEY=VALUE>] …               (each extra option, shellescaped)
+ *
+ * Escaping notes (the risky part):
+ *  - The ProxyCommand is emitted as a single shellescaped `-o KEY=VALUE`, so the
+ *    whole value (spaces + `%h`/`%p`) reaches ssh as one argument and `%h %p`
+ *    survive verbatim — ssh expands them to the real host/port, not the shell.
+ *  - A default `-o ConnectTimeout=10` bounds the wait on an unreachable/blackholed
+ *    host (else the pane hangs on the OS TCP timeout). It is omitted when the
+ *    operator already set ConnectTimeout via extraSshOptions, so their value wins.
+ */
+export function buildSshConnectionArgs(remote) {
+    const parts = ['ssh', '-o BatchMode=yes'];
+    const hasConnectTimeout = (remote.extraSshOptions ?? []).some((opt) => /^ConnectTimeout=/i.test(opt));
+    if (!hasConnectTimeout)
+        parts.push('-o ConnectTimeout=10');
+    if (remote.port)
+        parts.push(`-p ${remote.port}`);
+    if (remote.identityFile)
+        parts.push(`-i ${shellescape(expandIdentityPath(remote.identityFile))}`);
+    if (remote.jumpHost)
+        parts.push(`-J ${shellescape(remote.jumpHost)}`);
+    if (remote.socksProxy) {
+        parts.push(`-o ${shellescape(`ProxyCommand=nc -X 5 -x ${remote.socksProxy} %h %p`)}`);
+    }
+    for (const opt of remote.extraSshOptions ?? []) {
+        parts.push(`-o ${shellescape(opt)}`);
+    }
+    return parts;
+}
+/**
+ * COD-104 — build the SSH command that checks the remote host has tmux.
+ *
+ * Durable remote sessions run the agent inside a tmux server ON the remote host
+ * (`tmux -L codeman new-session -A …`), so tmux is now a hard prerequisite there.
+ * `command -v tmux` exits 0 (and prints the path) when tmux is installed.
+ *
+ * COD-107 — connects with the SAME options as the real launch
+ * (`buildSshConnectionArgs`) so a proxied/custom-port/identity host that the
+ * launch can reach also passes the prereq probe (and vice-versa).
+ */
+export function buildRemoteTmuxCheckCommand(host) {
+    // ConnectTimeout is now a default of buildSshConnectionArgs (shared with the launch).
+    return [...buildSshConnectionArgs(host), remoteSshTarget(host), "'command -v tmux'"].join(' ');
+}
+/**
+ * COD-104 — verify the remote host has tmux installed (required for durable
+ * remote sessions). Returns a structured result with a clear, user-facing error
+ * when tmux is missing or the host is unreachable. Never throws.
+ */
+export async function checkRemoteTmuxAvailable(host) {
+    const command = buildRemoteTmuxCheckCommand(host);
+    try {
+        const { stdout } = await execAsync(command, { timeout: 15_000 });
+        const tmuxPath = stdout.trim();
+        if (!tmuxPath) {
+            return {
+                ok: false,
+                error: `remote host ${host.host} needs tmux installed for durable remote sessions`,
+            };
+        }
+        return { ok: true, tmuxPath };
+    }
+    catch (err) {
+        const stderr = err && typeof err === 'object' && 'stderr' in err ? String(err.stderr ?? '') : '';
+        // `command -v tmux` exits non-zero when tmux is absent (no stderr); a real
+        // connection failure surfaces ssh diagnostics on stderr.
+        if (stderr.trim()) {
+            return {
+                ok: false,
+                error: `could not verify tmux on remote host ${host.host}: ${stderr.trim()}`,
+            };
+        }
+        return {
+            ok: false,
+            error: `remote host ${host.host} needs tmux installed for durable remote sessions`,
+        };
+    }
+}
+export function remoteDisplayPath(remote) {
+    const path = 'remotePath' in remote ? remote.remotePath : remote.path;
+    return `${remote.username}@${remote.host}:${path}`;
+}
+export function toSessionRemote(host, remoteCase) {
+    return {
+        hostId: host.id,
+        label: host.label,
+        host: host.host,
+        username: host.username,
+        port: host.port,
+        remotePath: remoteCase.remotePath,
+        commands: host.commands,
+        // COD-107 — carry the advanced SSH options from host config into the session
+        // so the launch/prereq commands connect the same way the operator configured.
+        identityFile: host.identityFile,
+        socksProxy: host.socksProxy,
+        jumpHost: host.jumpHost,
+        extraSshOptions: host.extraSshOptions,
+    };
+}
+//# sourceMappingURL=remote-hosts.js.map

package/dist/remote-hosts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-hosts.js","sourceRoot":"","sources":["../src/remote-hosts.ts"],"names":[],"mappings":"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"}

package/dist/services/unified-session-service.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Pure merge/filter logic for the unified session list (COD-121).
+ *
+ * Combines four read-only views of a session — live (in-memory `Session`),
+ * persisted (`state.json`), transcript history (`~/.claude/projects`), and the
+ * lifecycle audit log — plus mux process stats, into one de-duplicated list
+ * keyed by sessionId. Transcript-history rows are keyed by the Claude
+ * conversation UUID (the `.jsonl` filename stem), which diverges from the
+ * Codeman id for resumed sessions — an alias map (claudeSessionId → Codeman id,
+ * built from the live/persisted views) folds them into the owning session item.
+ * Higher-precedence sources overwrite scalar fields when present
+ * (history < lifecycle < persisted < live), while the `sources` array
+ * always accumulates every contributing view. A "meaningfulness floor" drops
+ * noise (bare lifecycle/mux-only rows with no name and no first prompt).
+ *
+ * PURE: no fs/IO and no node imports. All IO happens in the route that feeds
+ * this module its inputs, which keeps the merge/sort/filter behavior unit-testable.
+ */
+export type UnifiedSessionItem = {
+    sessionId: string;
+    name?: string;
+    mode?: string;
+    status?: string;
+    isWorking?: boolean;
+    workingDir?: string;
+    createdAt?: number;
+    lastActivityAt?: number;
+    claudeSessionId?: string;
+    firstPrompt?: string;
+    sizeBytes?: number;
+    projectKey?: string;
+    remote?: boolean;
+    sources: string[];
+    stats?: {
+        memoryMB: number;
+        cpuPercent: number;
+    };
+};
+/** Live in-memory session view (subset of `Session.toState()`). */
+export type LiveSessionInput = {
+    id: string;
+    name?: string;
+    mode?: string;
+    status?: string;
+    isWorking?: boolean;
+    workingDir?: string;
+    createdAt?: number;
+    lastActivityAt?: number;
+    claudeSessionId?: string;
+};
+/** Persisted session view (subset of `SessionState`). */
+export type PersistedSessionInput = {
+    id: string;
+    name?: string;
+    mode?: string;
+    status?: string;
+    workingDir?: string;
+    createdAt?: number;
+    lastActivityAt?: number;
+    /** Claude conversation ID this session resumes (`SessionState.resumeSessionId`). */
+    claudeSessionId?: string;
+};
+/** Lifecycle audit-log view. Entries are expected NEWEST-first (the order `SessionLifecycleLog.query()` returns). */
+export type LifecycleInput = {
+    sessionId: string;
+    name?: string;
+    mode?: string;
+    ts: number;
+    event?: string;
+};
+/** Transcript-history view (one `.jsonl` per session). */
+export type HistoryInput = {
+    sessionId: string;
+    workingDir: string;
+    sizeBytes: number;
+    lastModified: string;
+    firstPrompt?: string;
+    projectKey?: string;
+};
+/** Mux process-stat view. */
+export type MuxStatInput = {
+    sessionId: string;
+    muxName?: string;
+    mode?: string;
+    stats?: {
+        memoryMB: number;
+        cpuPercent: number;
+    };
+    remote?: boolean;
+};
+export type UnifiedSources = {
+    live?: LiveSessionInput[];
+    persisted?: PersistedSessionInput[];
+    lifecycle?: LifecycleInput[];
+    history?: HistoryInput[];
+    mux?: MuxStatInput[];
+};
+/**
+ * Merge all source views into one list, applying precedence
+ * (history → lifecycle → persisted → live) and the meaningfulness floor.
+ */
+export declare function mergeUnifiedSessions(sources: UnifiedSources): UnifiedSessionItem[];
+/**
+ * Case-insensitive substring filter (name + firstPrompt + workingDir + sessionId)
+ * with offset/limit paging. `total` is the filtered count BEFORE paging.
+ */
+export declare function filterAndPaginate(items: UnifiedSessionItem[], opts: {
+    q?: string;
+    offset?: number;
+    limit?: number;
+}): {
+    sessions: UnifiedSessionItem[];
+    total: number;
+};
+//# sourceMappingURL=unified-session-service.d.ts.map

package/dist/services/unified-session-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-session-service.d.ts","sourceRoot":"","sources":["../../src/services/unified-session-service.ts"],"names":[],"mappings":"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"}

package/dist/services/unified-session-service.js

@@ -0,0 +1,173 @@
+/**
+ * @fileoverview Pure merge/filter logic for the unified session list (COD-121).
+ *
+ * Combines four read-only views of a session — live (in-memory `Session`),
+ * persisted (`state.json`), transcript history (`~/.claude/projects`), and the
+ * lifecycle audit log — plus mux process stats, into one de-duplicated list
+ * keyed by sessionId. Transcript-history rows are keyed by the Claude
+ * conversation UUID (the `.jsonl` filename stem), which diverges from the
+ * Codeman id for resumed sessions — an alias map (claudeSessionId → Codeman id,
+ * built from the live/persisted views) folds them into the owning session item.
+ * Higher-precedence sources overwrite scalar fields when present
+ * (history < lifecycle < persisted < live), while the `sources` array
+ * always accumulates every contributing view. A "meaningfulness floor" drops
+ * noise (bare lifecycle/mux-only rows with no name and no first prompt).
+ *
+ * PURE: no fs/IO and no node imports. All IO happens in the route that feeds
+ * this module its inputs, which keeps the merge/sort/filter behavior unit-testable.
+ */
+/** Push a source tag onto an item exactly once. */
+function addSource(item, source) {
+    if (!item.sources.includes(source))
+        item.sources.push(source);
+}
+/** Get-or-create the accumulator item for a sessionId. */
+function ensureItem(map, sessionId) {
+    let item = map.get(sessionId);
+    if (!item) {
+        item = { sessionId, sources: [] };
+        map.set(sessionId, item);
+    }
+    return item;
+}
+/** Overwrite a scalar field only when the incoming value is defined. */
+function overwrite(item, key, value) {
+    if (value !== undefined)
+        item[key] = value;
+}
+/**
+ * Merge all source views into one list, applying precedence
+ * (history → lifecycle → persisted → live) and the meaningfulness floor.
+ */
+export function mergeUnifiedSessions(sources) {
+    const map = new Map();
+    // Alias map: Claude conversation UUID → owning Codeman session id. Resumed
+    // (claudeSessionId = resumeSessionId != id) and /clear-respawned sessions
+    // would otherwise surface twice — once as a live/persisted row and once as a
+    // separate history-only row keyed by the conversation UUID. Live wins over
+    // persisted on conflicting entries (registered last).
+    const aliasToOwner = new Map();
+    for (const p of sources.persisted ?? []) {
+        if (p.claudeSessionId !== undefined && p.claudeSessionId !== p.id)
+            aliasToOwner.set(p.claudeSessionId, p.id);
+    }
+    for (const v of sources.live ?? []) {
+        if (v.claudeSessionId !== undefined && v.claudeSessionId !== v.id)
+            aliasToOwner.set(v.claudeSessionId, v.id);
+    }
+    const resolveId = (sessionId) => aliasToOwner.get(sessionId) ?? sessionId;
+    // 1) history (lowest precedence; keys resolve through the alias map)
+    for (const h of sources.history ?? []) {
+        const item = ensureItem(map, resolveId(h.sessionId));
+        addSource(item, 'history');
+        overwrite(item, 'workingDir', h.workingDir);
+        overwrite(item, 'sizeBytes', h.sizeBytes);
+        overwrite(item, 'firstPrompt', h.firstPrompt);
+        overwrite(item, 'projectKey', h.projectKey);
+        const ms = Date.parse(h.lastModified);
+        if (!Number.isNaN(ms) && item.lastActivityAt === undefined)
+            item.lastActivityAt = ms;
+    }
+    // 2) lifecycle — entries arrive NEWEST-first, so first-seen wins for
+    //    name/mode (mirrors the lastActivityAt guard); unconditional overwrites
+    //    would leave the OLDEST entry in the window (stale name/mode) standing.
+    for (const l of sources.lifecycle ?? []) {
+        const item = ensureItem(map, resolveId(l.sessionId));
+        addSource(item, 'lifecycle');
+        if (item.name === undefined)
+            overwrite(item, 'name', l.name);
+        if (item.mode === undefined)
+            overwrite(item, 'mode', l.mode);
+        if (item.lastActivityAt === undefined && typeof l.ts === 'number')
+            item.lastActivityAt = l.ts;
+    }
+    // 3) persisted
+    for (const p of sources.persisted ?? []) {
+        const item = ensureItem(map, p.id);
+        addSource(item, 'persisted');
+        overwrite(item, 'name', p.name);
+        overwrite(item, 'mode', p.mode);
+        overwrite(item, 'status', p.status);
+        overwrite(item, 'workingDir', p.workingDir);
+        overwrite(item, 'createdAt', p.createdAt);
+        overwrite(item, 'lastActivityAt', p.lastActivityAt);
+    }
+    // 4) live (highest precedence)
+    for (const v of sources.live ?? []) {
+        const item = ensureItem(map, v.id);
+        addSource(item, 'live');
+        overwrite(item, 'name', v.name);
+        overwrite(item, 'mode', v.mode);
+        overwrite(item, 'status', v.status);
+        overwrite(item, 'isWorking', v.isWorking);
+        overwrite(item, 'workingDir', v.workingDir);
+        overwrite(item, 'createdAt', v.createdAt);
+        overwrite(item, 'lastActivityAt', v.lastActivityAt);
+        overwrite(item, 'claudeSessionId', v.claudeSessionId);
+    }
+    // 5) mux stats + remote flag (create item if mux-only)
+    for (const m of sources.mux ?? []) {
+        const item = ensureItem(map, m.sessionId);
+        addSource(item, 'mux');
+        overwrite(item, 'mode', m.mode);
+        if (m.stats)
+            item.stats = m.stats;
+        if (m.remote !== undefined)
+            item.remote = m.remote;
+    }
+    // Meaningfulness floor: keep real rows, drop bare lifecycle/mux-only noise.
+    const kept = [];
+    for (const item of map.values()) {
+        const isReal = item.sources.includes('live') ||
+            item.sources.includes('persisted') ||
+            item.sources.includes('history') ||
+            (item.firstPrompt !== undefined && item.firstPrompt !== '');
+        if (isReal)
+            kept.push(item);
+    }
+    // Stable sort: lastActivityAt desc (undefined last), createdAt desc, sessionId asc.
+    kept.sort((a, b) => {
+        const la = a.lastActivityAt;
+        const lb = b.lastActivityAt;
+        if (la !== lb) {
+            if (la === undefined)
+                return 1;
+            if (lb === undefined)
+                return -1;
+            return lb - la;
+        }
+        const ca = a.createdAt;
+        const cb = b.createdAt;
+        if (ca !== cb) {
+            if (ca === undefined)
+                return 1;
+            if (cb === undefined)
+                return -1;
+            return cb - ca;
+        }
+        return a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0;
+    });
+    return kept;
+}
+/**
+ * Case-insensitive substring filter (name + firstPrompt + workingDir + sessionId)
+ * with offset/limit paging. `total` is the filtered count BEFORE paging.
+ */
+export function filterAndPaginate(items, opts) {
+    const q = (opts.q ?? '').trim().toLowerCase();
+    const filtered = q
+        ? items.filter((it) => {
+            const hay = [it.name, it.firstPrompt, it.workingDir, it.sessionId]
+                .filter((v) => typeof v === 'string')
+                .join(' ')
+                .toLowerCase();
+            return hay.includes(q);
+        })
+        : items;
+    const total = filtered.length;
+    const offset = Math.max(0, Math.floor(opts.offset ?? 0));
+    const limit = Math.min(500, Math.max(1, Math.floor(opts.limit ?? 100)));
+    const sessions = filtered.slice(offset, offset + limit);
+    return { sessions, total };
+}
+//# sourceMappingURL=unified-session-service.js.map

package/dist/services/unified-session-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-session-service.js","sourceRoot":"","sources":["../../src/services/unified-session-service.ts"],"names":[],"mappings":"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"}

package/dist/session-cli-builder.d.ts

@@ -58,9 +58,11 @@ export declare function buildClaudeEnv(sessionId: string): Record<string, string
  * Lighter than buildClaudeEnv — no PATH augmentation or Codeman vars needed
  * since the mux session already has those set.
  *
+ * @param truecolorEnabled - When true, set COLORTERM=truecolor (COD-75 opt-in);
+ *   otherwise leave COLORTERM unset. Mirrors buildEnvExports() so both paths agree.
  * @returns Environment variables object for pty.spawn
  */
-export declare function buildMuxAttachEnv(): Record<string, string | undefined>;
+export declare function buildMuxAttachEnv(truecolorEnabled?: boolean): Record<string, string | undefined>;
 /**
  * Build environment variables for a direct shell session (non-mux fallback).
  *

package/dist/session-cli-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-cli-builder.d.ts","sourceRoot":"","sources":["../src/session-cli-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAyB1D;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,EAAE,CAGjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,UAAU,EACtB,KAAK,CAAC,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,MAAM,EAAE,CAKV;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAOxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAgBpF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAStE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAYnF"}
+{"version":3,"file":"session-cli-builder.d.ts","sourceRoot":"","sources":["../src/session-cli-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAyB1D;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,EAAE,CAGjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,UAAU,EACtB,KAAK,CAAC,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,MAAM,EAAE,CAKV;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAOxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAmBpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAsBhG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAYnF"}

package/dist/session-cli-builder.js

@@ -91,14 +91,12 @@ export function buildPromptArgs(prompt, model) {
  * @returns Environment variables object for pty.spawn
  */
 export function buildClaudeEnv(sessionId) {
-    return {
+    const env = {
         ...process.env,
         LANG: 'en_US.UTF-8',
         LC_ALL: 'en_US.UTF-8',
         PATH: getAugmentedPath(),
         TERM: 'xterm-256color',
-        COLORTERM: undefined,
-        CLAUDECODE: undefined,
         // Inform Claude it's running within Codeman (helps prevent self-termination)
         CODEMAN_MUX: '1',
         CODEMAN_SESSION_ID: sessionId,
@@ -106,23 +104,44 @@ export function buildClaudeEnv(sessionId) {
         // Path only (not the secret value) — hook curls cat it at execution time (COD-54)
         CODEMAN_HOOK_SECRET_FILE: dataPath('hook-secret'),
     };
+    // COD-115: `delete`, not `= undefined` — node-pty serializes a present-with-undefined
+    // key as the literal string "KEY=undefined" (see buildMuxAttachEnv below).
+    delete env.COLORTERM;
+    delete env.CLAUDECODE;
+    return env;
 }
 /**
  * Build environment variables for mux-attached PTY sessions (tmux attach).
  * Lighter than buildClaudeEnv — no PATH augmentation or Codeman vars needed
  * since the mux session already has those set.
  *
+ * @param truecolorEnabled - When true, set COLORTERM=truecolor (COD-75 opt-in);
+ *   otherwise leave COLORTERM unset. Mirrors buildEnvExports() so both paths agree.
  * @returns Environment variables object for pty.spawn
  */
-export function buildMuxAttachEnv() {
-    return {
+export function buildMuxAttachEnv(truecolorEnabled) {
+    const env = {
         ...process.env,
         LANG: 'en_US.UTF-8',
         LC_ALL: 'en_US.UTF-8',
         TERM: 'xterm-256color',
-        COLORTERM: undefined,
-        CLAUDECODE: undefined,
     };
+    // COD-115: keys to UNSET must be `delete`d, NOT set to `undefined`. On a
+    // `{...process.env}` spread the key stays present with value undefined, and node-pty
+    // serializes it as the literal string "TMUX=undefined" — a non-empty value that still
+    // trips tmux's nesting guard, killing the attach-bridge PTY (exit 1 → respawn loop).
+    // The server can be launched from inside tmux; attach clients must never inherit that
+    // parent tmux context. (Same fix the working create path uses in tmux-manager.ts.)
+    delete env.TMUX;
+    delete env.TMUX_PANE;
+    delete env.CLAUDECODE;
+    if (truecolorEnabled) {
+        env.COLORTERM = 'truecolor';
+    }
+    else {
+        delete env.COLORTERM; // COD-75: unset for non-truecolor (was `: undefined`, same node-pty quirk)
+    }
+    return env;
 }
 /**
  * Build environment variables for a direct shell session (non-mux fallback).

package/dist/session-cli-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-cli-builder.js","sourceRoot":"","sources":["../src/session-cli-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-cli-builder.js","sourceRoot":"","sources":["../src/session-cli-builder.ts"],"names":[],"mappings":"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"}