aiwcli 0.15.5 → 0.15.7

package/dist/lib/multiplexers/tmux.js

@@ -0,0 +1,262 @@
+/**
+ * TmuxMultiplexer — unified tmux backend.
+ * Consolidates TmuxLauncher + launchInTmuxSession + command building from pane-driver.
+ */
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import { cleanClaudeEnv, getLastLine, spawnAttached, splitFlagFromDimensions } from '../mux-utils.js';
+import { isNonWindowsPlatform, isWindowsPlatform } from '../runtime/platform-adapter.js';
+import { cleanupSentinelIpc, createSentinelIpcPaths } from '../runtime/sentinel-ipc.js';
+import { execFileAsync, findExecutable } from '../runtime/subprocess-utils.js';
+import { wrapSentinelSh } from '../sentinel-wrapper.js';
+import { findBestSplit, listPanes } from '../tmux-pane-placement.js';
+import { quoteForSh, toMsysPosixPath } from '../tmux-primitives.js';
+import { buildShellCommand, buildTmuxRuntimeBootstrapCommands } from '../tmux-session.js';
+/** @internal */
+export function buildEnvPrefix(env) {
+    return Object.entries(env)
+        .map(([key, value]) => `${key}=${quoteForSh(value)}`)
+        .join(' ');
+}
+/** @internal */
+export function buildShToolCommand(params) {
+    const { toolPath, args, env, mode, promptPath, promptText } = params;
+    const envPrefix = buildEnvPrefix(env);
+    const commandArgs = buildCommandArgs(args, mode, promptText);
+    const argPart = commandArgs.map((arg) => quoteForSh(arg)).join(' ');
+    const base = [envPrefix, quoteForSh(toolPath), argPart]
+        .filter(Boolean)
+        .join(' ');
+    if (mode === 'exec' && promptPath) {
+        return `${base} < ${quoteForSh(promptPath)}`;
+    }
+    return base;
+}
+/** @internal */
+export function buildCommandArgs(args, mode, promptText) {
+    if (mode !== 'repl' || promptText === undefined)
+        return args;
+    return [...args, promptText];
+}
+/** @internal */
+export function withWindowsTmuxBootstrap(command, platform = process.platform) {
+    if (platform !== 'win32')
+        return command;
+    const bootstrap = buildTmuxRuntimeBootstrapCommands(platform).join('; ');
+    return `${bootstrap}; ${command}`;
+}
+async function resolveToolForBash(toolName) {
+    const bash = findExecutable('bash');
+    if (!bash)
+        return null;
+    const result = await execFileAsync(bash, ['-lc', `command -v ${toolName}`], {
+        timeout: 3000,
+        env: { ...process.env, MSYS_NO_PATHCONV: '1' },
+    });
+    return result.exitCode === 0 ? result.stdout.trim() || null : null;
+}
+async function resolveAutoSplit(tmuxPath, splitTarget) {
+    const explicitTarget = splitTarget?.trim();
+    if (explicitTarget) {
+        const size = await execFileAsync(tmuxPath, ['display-message', '-p', '-t', explicitTarget, '#{pane_width} #{pane_height}'], { timeout: 3000 });
+        if (size.exitCode === 0) {
+            const parts = size.stdout.trim().split(/\s+/);
+            if (parts.length >= 2) {
+                const width = Number.parseInt(parts[0] ?? '', 10);
+                const height = Number.parseInt(parts[1] ?? '', 10);
+                if (Number.isFinite(width) && Number.isFinite(height)) {
+                    return {
+                        splitFlag: splitFlagFromDimensions(width, height),
+                        splitTarget: explicitTarget,
+                    };
+                }
+            }
+        }
+        return { splitFlag: '-h', splitTarget: explicitTarget };
+    }
+    const panes = await listPanes(tmuxPath);
+    const placement = findBestSplit(panes);
+    if (!placement)
+        return { splitFlag: '-h' };
+    return {
+        splitFlag: placement.splitFlag,
+        splitTarget: placement.targetPane,
+    };
+}
+/** @internal */
+export function buildTmuxSplitWindowArgs(params) {
+    const args = ['split-window', params.splitFlag, '-P', '-F', '#{pane_id}'];
+    if (params.cwd) {
+        args.push('-c', params.cwd);
+    }
+    if (params.splitTarget) {
+        args.push('-t', params.splitTarget);
+    }
+    args.push(params.command);
+    return args;
+}
+/** @internal */
+export function buildTmuxCreateSessionArgs(params) {
+    const args = ['new-session'];
+    if (params.reattach)
+        args.push('-A');
+    args.push('-c', params.cwd, '-s', params.sessionName, params.shellCommand);
+    return args;
+}
+export class TmuxMultiplexer {
+    backend = 'tmux';
+    tmuxPath;
+    constructor(tmuxPath) {
+        this.tmuxPath = tmuxPath;
+    }
+    static create() {
+        const tmuxPath = findExecutable('tmux');
+        if (!tmuxPath)
+            return null;
+        return new TmuxMultiplexer(tmuxPath);
+    }
+    async createSession(options) {
+        const { sessionName, reattach } = options;
+        if (!isNonWindowsPlatform()) {
+            return { exitCode: -1, usedMux: false, reason: 'tmux not available on this platform' };
+        }
+        // Set default-terminal BEFORE session creation (batched into single invocation)
+        try {
+            execSync(String.raw `tmux start-server \; set -g default-terminal "tmux-256color"`, { stdio: 'ignore', timeout: 3000 });
+        }
+        catch {
+            try {
+                execSync(String.raw `tmux start-server \; set -g default-terminal "screen-256color"`, { stdio: 'ignore', timeout: 3000 });
+            }
+            catch { /* best-effort */ }
+        }
+        const shellCommand = buildShellCommand({
+            sessionName,
+            toolPath: options.toolPath,
+            toolArgs: options.toolArgs,
+            promptText: options.promptText,
+            enableMouse: options.enableMouse ?? true,
+        });
+        const args = buildTmuxCreateSessionArgs({
+            sessionName,
+            cwd: process.cwd(),
+            shellCommand,
+            reattach,
+        });
+        return spawnAttached('tmux', args, cleanClaudeEnv(), this.backend);
+    }
+    isInsideSession() {
+        return Boolean(process.env.TMUX);
+    }
+    async kill(paneId) {
+        if (!paneId)
+            return;
+        await execFileAsync(this.tmuxPath, ['kill-pane', '-t', paneId], { timeout: 3000 });
+    }
+    async splitPane(options) {
+        const mode = options.mode ?? 'repl';
+        const args = options.args ?? [];
+        const envVars = options.env ?? {};
+        const cwd = options.cwd ?? process.cwd();
+        // Resolve tool path
+        const toolPath = findExecutable(options.toolName);
+        if (!toolPath) {
+            return { launched: false, backend: this.backend, reason: `${options.toolName} not found on PATH` };
+        }
+        // On Windows with tmux backend, resolve tool path from bash's perspective
+        let effectiveToolPath = toolPath;
+        if (isWindowsPlatform()) {
+            const bashPath = await resolveToolForBash(options.toolName);
+            if (bashPath) {
+                effectiveToolPath = bashPath;
+            }
+            else {
+                return { launched: false, backend: this.backend, reason: `${options.toolName} not found in bash PATH (required for tmux pane)` };
+            }
+        }
+        // Sentinel IPC for exit code tracking
+        const useSentinel = options.sentinel !== false;
+        const sentinel = useSentinel ? createSentinelIpcPaths(`aiwcli-pane-${options.toolName}`) : null;
+        // Inject COLORTERM=truecolor for tmux
+        const effectiveEnvVars = { COLORTERM: 'truecolor', ...envVars };
+        try {
+            const promptText = mode === 'repl' && options.promptPath
+                ? fs.readFileSync(options.promptPath, 'utf8')
+                : undefined;
+            const baseCommand = buildShToolCommand({
+                toolPath: effectiveToolPath,
+                args,
+                env: effectiveEnvVars,
+                mode,
+                promptText,
+                ...(options.promptPath ? { promptPath: options.promptPath } : {}),
+            });
+            let paneCommand = baseCommand;
+            if (sentinel) {
+                const holdMessage = options.holdMessage ?? '[aiwcli] Driver exited. Pane held open.';
+                paneCommand = wrapSentinelSh({
+                    command: baseCommand,
+                    sentinelPath: sentinel.sentinelPath,
+                    autoClose: Boolean(options.autoClose),
+                    holdPane: Boolean(options.holdPane),
+                    holdMessage,
+                });
+            }
+            // Resolve split direction
+            const splitDirection = options.split ?? 'auto';
+            let splitFlag;
+            let splitTarget;
+            if (splitDirection === 'auto') {
+                try {
+                    const resolved = await resolveAutoSplit(this.tmuxPath, options.splitTarget);
+                    splitFlag = resolved.splitFlag;
+                    splitTarget = resolved.splitTarget;
+                }
+                catch {
+                    splitFlag = '-h';
+                    splitTarget = options.splitTarget?.trim();
+                }
+            }
+            else {
+                splitFlag = splitDirection === 'v' ? '-v' : '-h';
+                splitTarget = options.splitTarget?.trim();
+            }
+            // Build tmux split-window command
+            const cwdPath = cwd ? (process.platform === 'win32' ? toMsysPosixPath(cwd) : cwd) : undefined;
+            const bootstrappedCommand = withWindowsTmuxBootstrap(paneCommand);
+            const tmuxArgs = buildTmuxSplitWindowArgs({
+                splitFlag,
+                command: `bash -lc ${quoteForSh(bootstrappedCommand)}`,
+                cwd: cwdPath,
+                splitTarget,
+            });
+            const split = await execFileAsync(this.tmuxPath, tmuxArgs, { timeout: 5000 });
+            if (split.exitCode !== 0) {
+                if (sentinel)
+                    cleanupSentinelIpc(sentinel);
+                return {
+                    launched: false,
+                    backend: this.backend,
+                    reason: 'tmux split-window failed',
+                    stderr: split.stderr.trim() || undefined,
+                };
+            }
+            const paneId = getLastLine(split.stdout) || undefined;
+            return {
+                launched: true,
+                backend: this.backend,
+                paneId,
+                sentinelPath: sentinel?.sentinelPath,
+            };
+        }
+        catch (error) {
+            if (sentinel)
+                cleanupSentinelIpc(sentinel);
+            return {
+                launched: false,
+                backend: this.backend,
+                reason: `pane launch failed: ${String(error)}`,
+            };
+        }
+    }
+}

package/dist/lib/mux-utils.d.ts

@@ -0,0 +1,5 @@
+import type { CreateSessionResult } from './multiplexer.js';
+export declare function getLastLine(text: string): string;
+export declare function spawnAttached(command: string, args: string[], env: NodeJS.ProcessEnv | undefined, backendLabel: string): Promise<CreateSessionResult>;
+export declare function splitFlagFromDimensions(width: number, height: number): '-h' | '-v';
+export declare function cleanClaudeEnv(extra?: Record<string, string>): NodeJS.ProcessEnv;

package/dist/lib/mux-utils.js

@@ -0,0 +1,42 @@
+import { spawn } from 'node:child_process';
+import { getInternalSubprocessEnv } from './runtime/subprocess-utils.js';
+const CELL_ASPECT_RATIO = 2;
+export function getLastLine(text) {
+    const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    return lines.at(-1) ?? '';
+}
+export function spawnAttached(command, args, env, backendLabel) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, args, { stdio: 'inherit', env: env ?? process.env });
+        }
+        catch (error) {
+            resolve({ exitCode: -1, usedMux: false, reason: error instanceof Error ? error.message : String(error) });
+            return;
+        }
+        child.on('error', (error) => {
+            resolve({ exitCode: -1, usedMux: false, reason: error.message });
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve({ exitCode: 0, usedMux: true });
+            }
+            else {
+                resolve({ exitCode: code ?? 1, usedMux: false, reason: `${backendLabel} exited with code ${code ?? 1}` });
+            }
+        });
+    });
+}
+export function splitFlagFromDimensions(width, height) {
+    return width >= height * CELL_ASPECT_RATIO ? '-h' : '-v';
+}
+export function cleanClaudeEnv(extra) {
+    const env = {
+        ...getInternalSubprocessEnv(),
+        ...extra,
+    };
+    delete env['CLAUDECODE'];
+    delete env['CLAUDE_CODE_ENTRYPOINT'];
+    return env;
+}

package/dist/lib/paths.d.ts

@@ -13,14 +13,14 @@ export declare function expandPath(inputPath: string): string;
 /**
  * Convert a path to Unix-style forward slashes.
  * Useful for cross-platform logging or display.
- * @param inputPath - Path with any separator style
+ * @param inputPath - Path with unknown separator style
  * @returns Path with forward slashes only
  */
 export declare function toUnixPath(inputPath: string): string;
 /**
  * Convert a path to Windows-style backslashes.
  * Useful for cross-platform logging or display.
- * @param inputPath - Path with any separator style
+ * @param inputPath - Path with unknown separator style
  * @returns Path with backslashes only
  */
 export declare function toWindowsPath(inputPath: string): string;

package/dist/lib/paths.js

@@ -31,7 +31,7 @@ export function expandPath(inputPath) {
 /**
  * Convert a path to Unix-style forward slashes.
  * Useful for cross-platform logging or display.
- * @param inputPath - Path with any separator style
+ * @param inputPath - Path with unknown separator style
  * @returns Path with forward slashes only
  */
 export function toUnixPath(inputPath) {
@@ -40,7 +40,7 @@ export function toUnixPath(inputPath) {
 /**
  * Convert a path to Windows-style backslashes.
  * Useful for cross-platform logging or display.
- * @param inputPath - Path with any separator style
+ * @param inputPath - Path with unknown separator style
  * @returns Path with backslashes only
  */
 export function toWindowsPath(inputPath) {

package/dist/lib/platform-commands.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Platform-specific hook command adaptation.
+ *
+ * Claude Code on Windows uses cmd.exe to execute hook commands (Node.js
+ * child_process.exec defaults to process.env.ComSpec). Template commands use
+ * bash syntax (~/ expansion, env-var prefixes) that cmd.exe can't parse.
+ *
+ * This module rewrites commands at settings-reconstruction time so they work
+ * in cmd.exe while remaining valid in bash on Unix (where it's a no-op).
+ */
+/**
+ * Resolver path token that appears in all template hook commands.
+ * Shared between templates and adapter — changing this requires updating
+ * all template settings.json files AND tests.
+ */
+export declare const RESOLVER_TOKEN = ".aiwcli/_core/scripts/resolve-run.ts";
+/**
+ * Adapt a hook command for the current platform.
+ * On Windows: strips bash env prefixes, quotes the resolver path.
+ * On Unix: no-op (returns input unchanged).
+ */
+export declare function adaptHookCommand(command: string): string;
+/**
+ * Post-reconstruction validation. On Windows, asserts no command contains
+ * bash-only syntax. Throws with actionable message if validation fails.
+ */
+export declare function validateCommandsForPlatform(commands: string[]): void;

package/dist/lib/platform-commands.js

@@ -0,0 +1,49 @@
+/**
+ * Platform-specific hook command adaptation.
+ *
+ * Claude Code on Windows uses cmd.exe to execute hook commands (Node.js
+ * child_process.exec defaults to process.env.ComSpec). Template commands use
+ * bash syntax (~/ expansion, env-var prefixes) that cmd.exe can't parse.
+ *
+ * This module rewrites commands at settings-reconstruction time so they work
+ * in cmd.exe while remaining valid in bash on Unix (where it's a no-op).
+ */
+/**
+ * Resolver path token that appears in all template hook commands.
+ * Shared between templates and adapter — changing this requires updating
+ * all template settings.json files AND tests.
+ */
+export const RESOLVER_TOKEN = '.aiwcli/_core/scripts/resolve-run.ts';
+/** Matches leading bash-style env-var prefixes: KEY=VALUE KEY2= ... */
+const BASH_ENV_PREFIX_RE = /^(?:[A-Z_]+=\S*\s+)+/;
+/**
+ * Adapt a hook command for the current platform.
+ * On Windows: strips bash env prefixes, quotes the resolver path.
+ * On Unix: no-op (returns input unchanged).
+ */
+export function adaptHookCommand(command) {
+    if (process.platform !== 'win32')
+        return command;
+    const quotedResolver = `"${RESOLVER_TOKEN}"`;
+    let result = command.replace(BASH_ENV_PREFIX_RE, '');
+    result = result.replace(RESOLVER_TOKEN, quotedResolver);
+    return result;
+}
+/**
+ * Post-reconstruction validation. On Windows, asserts no command contains
+ * bash-only syntax. Throws with actionable message if validation fails.
+ */
+export function validateCommandsForPlatform(commands) {
+    if (process.platform !== 'win32')
+        return;
+    for (const cmd of commands) {
+        if (cmd.includes('~/')) {
+            throw new Error(`Hook command contains unexpanded ~/: "${cmd}". ` +
+                'All hook commands must use RESOLVER_TOKEN from platform-commands.ts.');
+        }
+        if (BASH_ENV_PREFIX_RE.test(cmd)) {
+            throw new Error(`Hook command contains bash env prefix: "${cmd}". ` +
+                'Move env vars into resolve-run.ts spawn env instead.');
+        }
+    }
+}

package/dist/lib/runtime/aiw-cli.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Helper to discover and invoke the `aiw` CLI binary from template scripts.
+ *
+ * Reads the resolved binary path from `.aiwcli/.aiw-bin-path` (written by `aiw init`).
+ * Falls back to `aiw` on PATH if the file is missing.
+ */
+export interface AiwLaunchOptions {
+    /** Launch codex instead of claude. */
+    codex?: boolean;
+    /** Working directory. */
+    cwd?: string;
+    /** Extra env vars to inject. */
+    env?: Record<string, string>;
+    /** Return JSON output. */
+    json?: boolean;
+    /** Path to prompt file. */
+    promptPath?: string;
+    /** Split direction: auto, h, or v. */
+    split?: "auto" | "h" | "v";
+    /** Timeout in ms (only relevant with --wait). */
+    timeoutMs?: number;
+    /** Block until pane exits. */
+    wait?: boolean;
+}
+export interface AiwLaunchResult {
+    backend: string;
+    exitCode: null | number;
+    launched: boolean;
+    paneId: null | string;
+    reason: null | string;
+    sentinelPath: null | string;
+}
+/**
+ * Shell out to `aiw launch` with structured options.
+ * Returns parsed JSON result when --json is used.
+ */
+export declare function aiwLaunch(options: AiwLaunchOptions): Promise<AiwLaunchResult>;

package/dist/lib/runtime/aiw-cli.js

@@ -0,0 +1,74 @@
+/**
+ * Helper to discover and invoke the `aiw` CLI binary from template scripts.
+ *
+ * Reads the resolved binary path from `.aiwcli/.aiw-bin-path` (written by `aiw init`).
+ * Falls back to `aiw` on PATH if the file is missing.
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+import { getProjectRoot } from "./constants.js";
+import { execFileAsync } from "./subprocess-utils.js";
+function resolveAiwBin(cwd) {
+    const projectRoot = getProjectRoot(cwd ?? process.cwd());
+    const binPathFile = path.join(projectRoot, ".aiwcli", ".aiw-bin-path");
+    try {
+        const binPath = fs.readFileSync(binPathFile, "utf8").trim();
+        if (binPath && fs.existsSync(binPath))
+            return binPath;
+    }
+    catch {
+        // Fall through to PATH lookup
+    }
+    return "aiw";
+}
+/**
+ * Shell out to `aiw launch` with structured options.
+ * Returns parsed JSON result when --json is used.
+ */
+export async function aiwLaunch(options) {
+    const bin = resolveAiwBin(options.cwd);
+    const args = ["launch"];
+    if (options.codex)
+        args.push("--codex");
+    if (options.wait)
+        args.push("--wait");
+    args.push("--json");
+    if (options.split)
+        args.push("--split", options.split);
+    if (options.env && Object.keys(options.env).length > 0) {
+        args.push("--env", JSON.stringify(options.env));
+    }
+    if (options.promptPath)
+        args.push("--prompt-path", options.promptPath);
+    const result = await execFileAsync(bin, args, {
+        timeout: options.timeoutMs ?? 14_400_000,
+        env: process.env,
+        shell: process.platform === "win32",
+    });
+    return parseJsonResult(result);
+}
+function parseJsonResult(result) {
+    try {
+        const lines = result.stdout.trim().split(/\r?\n/);
+        const lastLine = lines.at(-1) ?? "";
+        const parsed = JSON.parse(lastLine);
+        return {
+            launched: Boolean(parsed.launched),
+            backend: String(parsed.backend ?? "exec"),
+            paneId: parsed.paneId ?? null,
+            sentinelPath: parsed.sentinelPath ?? null,
+            exitCode: typeof parsed.exitCode === "number" ? parsed.exitCode : null,
+            reason: parsed.reason ?? null,
+        };
+    }
+    catch {
+        return {
+            launched: false,
+            backend: "exec",
+            paneId: null,
+            sentinelPath: null,
+            exitCode: result.exitCode,
+            reason: `Failed to parse aiw launch output: ${result.stderr || result.stdout}`,
+        };
+    }
+}

package/dist/lib/runtime/atomic-write.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cross-platform atomic file writes with security.
+ * Crash-safe writes by writing to temp file then renaming.
+ * NOT for concurrent access — assumes single-session-per-context.
+ * See SPEC.md §4
+ */
+/**
+ * Write file atomically with retry logic.
+ * Creates temp file, writes, fsyncs, renames.
+ * Returns [success, error].
+ * See SPEC.md §4.2
+ */
+export declare function atomicWrite(filePath: string, content: string, maxAttempts?: number, backoffMs?: number[], fsync?: boolean): [boolean, null | string];
+/**
+ * Append to file with retry logic.
+ * For JSONL files where each line is independent.
+ * See SPEC.md §4.3
+ */
+export declare function atomicAppend(filePath: string, content: string, maxAttempts?: number, backoffMs?: number[], fsync?: boolean): [boolean, null | string];

package/dist/lib/runtime/atomic-write.js

@@ -0,0 +1,121 @@
+/**
+ * Cross-platform atomic file writes with security.
+ * Crash-safe writes by writing to temp file then renaming.
+ * NOT for concurrent access — assumes single-session-per-context.
+ * See SPEC.md §4
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import path from "node:path";
+/**
+ * Write file atomically with retry logic.
+ * Creates temp file, writes, fsyncs, renames.
+ * Returns [success, error].
+ * See SPEC.md §4.2
+ */
+export function atomicWrite(filePath, content, maxAttempts = 2, backoffMs = [500, 1000], fsync = true) {
+    // Ensure parent directory exists
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const stem = path.basename(filePath, path.extname(filePath));
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const tmpName = `.${stem}_${crypto.randomBytes(4).toString("hex")}.tmp`;
+        const tmpPath = path.join(dir, tmpName);
+        try {
+            // Write to temp file
+            const fd = fs.openSync(tmpPath, "w");
+            try {
+                fs.writeSync(fd, content, undefined, "utf8");
+                if (fsync)
+                    fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            // Set restrictive permissions (best-effort)
+            try {
+                fs.chmodSync(tmpPath, 0o600);
+            }
+            catch {
+                // May fail on some filesystems
+            }
+            // Atomic rename (cross-platform on modern Node/Bun)
+            fs.renameSync(tmpPath, filePath);
+            return [true, null];
+        }
+        catch (error) {
+            // Clean up temp file
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                // Best-effort cleanup
+            }
+            if (attempt < maxAttempts - 1) {
+                const waitMs = backoffMs[Math.min(attempt, backoffMs.length - 1)] ?? backoffMs.at(-1) ?? 500;
+                sleepSync(waitMs);
+            }
+            else {
+                const errType = error?.constructor?.name ?? "Error";
+                const errMsg = String(error).split("\n")[0]?.slice(0, 200) ?? "";
+                return [false, `${errType}: ${errMsg}`];
+            }
+        }
+    }
+    return [false, "Max retry attempts exceeded"];
+}
+/**
+ * Append to file with retry logic.
+ * For JSONL files where each line is independent.
+ * See SPEC.md §4.3
+ */
+export function atomicAppend(filePath, content, maxAttempts = 2, backoffMs = [500, 1000], fsync = true) {
+    // Ensure parent directory exists
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const isNewFile = !fs.existsSync(filePath);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            const fd = fs.openSync(filePath, "a");
+            try {
+                fs.writeSync(fd, content, undefined, "utf8");
+                if (fsync)
+                    fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            // Set permissions on newly created files (best-effort)
+            if (isNewFile) {
+                try {
+                    fs.chmodSync(filePath, 0o600);
+                }
+                catch {
+                    // May fail on some filesystems
+                }
+            }
+            return [true, null];
+        }
+        catch (error) {
+            if (attempt < maxAttempts - 1) {
+                const waitMs = backoffMs[Math.min(attempt, backoffMs.length - 1)] ?? backoffMs.at(-1) ?? 500;
+                sleepSync(waitMs);
+            }
+            else {
+                const errType = error?.constructor?.name ?? "Error";
+                const errMsg = String(error).split("\n")[0]?.slice(0, 200) ?? "";
+                return [false, `${errType}: ${errMsg}`];
+            }
+        }
+    }
+    return [false, "Max retry attempts exceeded"];
+}
+/**
+ * Synchronous sleep for retry backoff.
+ * Uses Atomics.wait() for CPU-friendly blocking instead of busy-wait.
+ */
+function sleepSync(ms) {
+    const sab = new SharedArrayBuffer(4);
+    const i32 = new Int32Array(sab);
+    Atomics.wait(i32, 0, 0, ms);
+}