aiwcli 0.15.1 → 0.15.2

package/dist/templates/_shared/.claude/skills/codex/SKILL.md

@@ -1,42 +1,35 @@
 ---
 name: codex
-description: Launch Codex CLI in a tmux pane. USE WHEN codex OR send to codex OR codex implement OR hand off to codex OR launch codex OR codex plan OR run codex.
+description: Delegate implementation to Codex sub-agents. USE WHEN codex OR send to codex OR codex implement OR hand off to codex OR launch codex OR codex plan OR run codex.
 user-invocable: true
 ---
 
-# Codex CLI
+Read `.aiwcli/_shared/skills/codex/SKILL.md` for delegation patterns and examples.
 
-Launch Codex in a tmux split pane and optionally inject a prompt.
+## Role
 
-## Command
+You are the orchestrator. Codex instances are your implementation sub-agents. Decide what to delegate, how to split work, and review results when summaries arrive.
 
-`bun .aiwcli/_shared/skills/prompt-codex/scripts/launch-codex.ts [flags] <mode>`
+## Command
 
-**Modes:** `plan` (inject active plan) | `--file <path>` (inject file) | `<text...>` (inject inline text)
+```
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [flags] <mode>
+```
 
-**Flags:**
-- `--model <name>` — Model aliases: `spark`, `codex`, `gpt`. Tiers: `fast`, `standard`, `smart`. Or any full model ID.
-- `--sandbox <mode>` — `read-only`, `workspace-write`, `danger-full-access`. Default: Codex default.
-- `--context <id>` — Pass the active context ID so Codex receives project orientation (context folder, notes path). **Always pass this when an active context exists** (check the `Active Context:` system reminder for the ID).
+The script blocks until Codex exits and prints a summary — run with Bash `run_in_background: true` so you stay unblocked.
 
-## Model Reference
+**Modes:** `plan` | `--file <path>` | `<inline text...>`
 
-| Name | Resolves To |
-|------|-------------|
-| `spark` | `gpt-5.3-codex-spark` (fastest) |
-| `codex` | `gpt-5.3-codex` (default) |
-| `gpt` | `gpt-5.2` (non-Codex GPT) |
-| `fast` | `gpt-5.3-codex-spark` (tier) |
-| `standard` | `gpt-5.3-codex` (tier) |
-| `smart` | `gpt-5.3-codex` (tier) |
+**Key flags:**
+- `--context <id>` — Project orientation. Pass when implementing a plan.
+- `--prompt <text>` — Scope the agent's work to a specific plan section or task.
+- `--model <name>` — `spark`, `codex`, `gpt`, or tier: `fast`, `standard`, `smart`.
+- `--no-watch` — Fire-and-forget (skip waiting for summary).
 
-## Examples
+## Delegation Decision
 
-- `/codex --model spark --context <context-id> plan` — hand off active plan to Spark with context
-- `/codex --model codex --context <context-id> Refactor auth to use JWT` — inline prompt with context
-- `/codex --file ./spec.md` — inject file contents (no context)
+**One-shot:** Plan is small or tightly coupled → launch one Codex with `plan` mode. Wait for the summary, then review.
 
-## Requirements
+**Parallel:** Plan has independent sections → launch multiple Codex instances, each scoped with `--prompt` to its section. All share the same `--context`. Review when summaries arrive, check for conflicts.
 
-- Must be running inside tmux
-- `codex` CLI must be on PATH
+**Ad-hoc:** No plan, just a task → pass inline text (e.g., `"Fix the failing test in auth.ts"`).

package/dist/templates/_shared/.codex/workflows/codex.md

@@ -0,0 +1,11 @@
+# Codex Workflow
+
+Use Codex CLI handoff instructions from `.aiwcli/_shared/skills/codex/SKILL.md`.
+
+## Command
+
+`bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [flags] <mode>`
+
+**Modes:** `plan` | `--file <path>` | `<inline text...>`
+
+**Common flags:** `--model <name>`, `--sandbox <mode>`, `--context <id>`, `--prompt <text>`, `--no-yolo`, `--capture`

package/dist/templates/_shared/lib-ts/base/tmux-driver.ts

@@ -12,9 +12,11 @@
 import * as fs from "node:fs";
 
 import { execFileAsync, findExecutable } from "./subprocess-utils.js";
+import { findBestSplit, listPanes } from "./tmux-pane-placement.js";
 
 export type DriverMode = "exec" | "repl";
 export type TmuxSplitFlag = "-h" | "-v";
+export type TmuxSplitOption = TmuxSplitFlag | "auto";
 
 export interface DriverPreflightResult {
   available: boolean;
@@ -53,7 +55,7 @@ export interface LaunchDriverOptions {
   env?: Record<string, string>;
   promptPath?: string;
   sendPromptInRepl?: boolean;
-  splitFlag?: string;
+  splitFlag?: TmuxSplitOption;
   splitTarget?: string;
   autoClose?: boolean;
   holdPane?: boolean;
@@ -165,6 +167,54 @@ export function normalizeSplitFlag(value: string | undefined): TmuxSplitFlag {
   return value?.trim() === "-v" ? "-v" : "-h";
 }
 
+function splitFlagFromDimensions(width: number, height: number): TmuxSplitFlag {
+  return width >= height ? "-h" : "-v";
+}
+
+async function resolveSplitFlagForTargetPane(
+  tmuxPath: string,
+  splitTarget: string,
+): Promise<TmuxSplitFlag | null> {
+  const size = await execFileAsync(
+    tmuxPath,
+    ["display-message", "-p", "-t", splitTarget, "#{pane_width} #{pane_height}"],
+    { timeout: 3000 },
+  );
+  if (size.exitCode !== 0) return null;
+
+  const parts = size.stdout.trim().split(/\s+/);
+  if (parts.length < 2) return null;
+
+  const width = Number.parseInt(parts[0] ?? "", 10);
+  const height = Number.parseInt(parts[1] ?? "", 10);
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+
+  return splitFlagFromDimensions(width, height);
+}
+
+async function resolveAutoSplit(
+  tmuxPath: string,
+  splitTarget?: string,
+): Promise<{ splitFlag: TmuxSplitFlag; splitTarget?: string }> {
+  const explicitTarget = splitTarget?.trim();
+  if (explicitTarget) {
+    const splitFlag = await resolveSplitFlagForTargetPane(tmuxPath, explicitTarget);
+    return {
+      splitFlag: 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,
+  };
+}
+
 export function isTruthy(value: string | undefined): boolean {
   if (!value) return false;
   const normalized = value.trim().toLowerCase();
@@ -287,8 +337,25 @@ export async function launchDriverInTmuxOrFallback(
 
   const tmux = getTmuxAvailability();
   if (tmux.available && tmux.tmuxPath) {
-    const splitFlag = normalizeSplitFlag(options.splitFlag);
-    const splitTarget = options.splitTarget?.trim();
+    const requestedSplitFlag = options.splitFlag;
+    const explicitSplitTarget = options.splitTarget?.trim();
+    let splitFlag: TmuxSplitFlag;
+    let splitTarget: string | undefined;
+
+    if (requestedSplitFlag === "auto") {
+      try {
+        const resolved = await resolveAutoSplit(tmux.tmuxPath, explicitSplitTarget);
+        splitFlag = resolved.splitFlag;
+        splitTarget = resolved.splitTarget;
+      } catch {
+        splitFlag = "-h";
+        splitTarget = explicitSplitTarget;
+      }
+    } else {
+      splitFlag = normalizeSplitFlag(requestedSplitFlag);
+      splitTarget = explicitSplitTarget;
+    }
+
     const baseCmd = buildToolCommand(toolPath, args, envVars, mode, options.promptPath);
     const holdMessage = options.holdMessage ?? "[aiwcli] Driver exited. Pane held open.";
     const paneBody = wrapPaneCommand(

package/dist/templates/_shared/lib-ts/base/tmux-pane-placement.ts

@@ -0,0 +1,70 @@
+import { execFileAsync } from "./subprocess-utils.js";
+
+export type TmuxSplitFlag = "-h" | "-v";
+
+export interface TmuxPaneInfo {
+  paneId: string;
+  width: number;
+  height: number;
+  active: boolean;
+}
+
+export interface PlacementResult {
+  targetPane: string;
+  splitFlag: TmuxSplitFlag;
+}
+
+const LIST_PANES_FORMAT = "#{pane_id} #{pane_width} #{pane_height} #{pane_active}";
+
+export async function listPanes(tmuxPath: string): Promise<TmuxPaneInfo[]> {
+  const result = await execFileAsync(tmuxPath, ["list-panes", "-F", LIST_PANES_FORMAT], {
+    timeout: 3000,
+  });
+  if (result.exitCode !== 0) return [];
+
+  const panes: TmuxPaneInfo[] = [];
+  for (const rawLine of result.stdout.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    const parts = line.split(/\s+/);
+    if (parts.length < 4) continue;
+
+    const paneId = parts[0] ?? "";
+    const width = Number.parseInt(parts[1] ?? "", 10);
+    const height = Number.parseInt(parts[2] ?? "", 10);
+    const activeRaw = parts[3] ?? "";
+
+    if (!paneId || !Number.isFinite(width) || !Number.isFinite(height)) continue;
+    panes.push({
+      paneId,
+      width,
+      height,
+      active: activeRaw === "1",
+    });
+  }
+
+  return panes;
+}
+
+export function findBestSplit(panes: TmuxPaneInfo[]): PlacementResult | null {
+  if (panes.length === 0) return null;
+
+  let best = panes[0];
+  let bestArea = best.width * best.height;
+
+  for (let i = 1; i < panes.length; i++) {
+    const pane = panes[i];
+    if (!pane) continue;
+    const area = pane.width * pane.height;
+    if (area > bestArea) {
+      best = pane;
+      bestArea = area;
+    }
+  }
+
+  return {
+    targetPane: best.paneId,
+    splitFlag: best.width >= best.height ? "-h" : "-v",
+  };
+}

package/dist/templates/_shared/scripts/resolve-run.ts

@@ -52,7 +52,7 @@ if (!fs.existsSync(fullPath)) {
   process.exit(1);
 }
 
-const result = Bun.spawnSync(["bun", fullPath], {
+const result = Bun.spawnSync(["bun", fullPath, ...process.argv.slice(3)], {
   stdin: "inherit",
   stdout: "inherit",
   stderr: "inherit",

package/dist/templates/_shared/skills/codex/CLAUDE.md

@@ -0,0 +1,77 @@
+# Codex Skill
+
+Launch Codex CLI in a tmux pane and inject a prompt into its REPL.
+
+## Directory Structure
+
+```
+codex/
+├── CLAUDE.md       ← This file
+├── lib/
+│   └── codex-watcher.ts  ← Reusable watch/summarize library
+└── scripts/
+    └── launch-codex.ts   ← Single entry point (launch + optional watch)
+```
+
+## Script: launch-codex.ts
+
+**Usage:**
+```bash
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--prompt <text>] [--no-yolo] [--no-watch] [--context <id>] plan
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--prompt <text>] [--no-yolo] [--no-watch] [--context <id>] --file <path>
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--prompt <text>] [--no-yolo] [--no-watch] [--context <id>] <inline text...>
+```
+
+**Args:**
+- `plan` — discover active plan via context system, inject into Codex REPL
+- `--file <path>` — inject file contents into Codex REPL
+- `<text...>` — join remaining args as inline prompt, write to temp file, inject
+- `--model <alias|tier|id>` — Aliases: `spark` → `gpt-5.3-codex-spark`, `codex` → `gpt-5.3-codex`, `gpt` → `gpt-5.2`. Tiers: `fast`/`standard`/`smart` (resolved via `resolveModelForProvider()`). Or any full model ID. Aliases are checked first (local `CODEX_ALIASES` constant in `launch-codex.ts`), then tiers, then pass-through. Omitted = Codex default.
+- `--sandbox <mode>` — `read-only`, `workspace-write`, or `danger-full-access`. Default is `danger-full-access` for implementation handoffs.
+- `--prompt <text>` — append extra instructions under `## Additional Instructions` after the main prompt body.
+- `--no-yolo` — Disable YOLO mode (on by default). YOLO maps to Codex CLI's `--dangerously-bypass-approvals-and-sandbox`. Use `--no-yolo` to restore normal approval prompts.
+- `--no-watch` — Disable watch/summarize mode. Launch exits immediately after Codex starts.
+
+**Plan discovery order:**
+1. `CLAUDE_SESSION_ID` env → `getContextBySessionId()` → `findLatestPlan(contextId)`
+2. Fallback: scan `_output/contexts/*/plans/*.md` by mtime (inline, no `_cc-native` import)
+
+**Dependencies (all from `_shared/lib-ts/`):**
+- `base/tmux-driver.ts` — `launchDriverInTmuxOrFallback()`, `getTmuxAvailability()`
+- `base/cli-args.ts` — `resolveCodexModel()`, `codexReplSpec()`, `buildCliInvocation()`, `isCodexSandbox()`
+- `base/logger.ts` — `logDebug()`, `logWarn()` (injection diagnostics)
+- `context/context-store.ts` — `getContextBySessionId()`
+- `context/context-formatter.ts` — `buildExternalAgentContext()` (orientation header for Codex)
+- `context/plan-manager.ts` — `findLatestPlan()`
+
+**Watch behavior (single entry point):**
+- Watch is enabled by default.
+- `launch-codex.ts` launches Codex, waits for pane close (or timeout), and prints a summary.
+- Summary cascade:
+  1. Spark transcript summary from session file
+  2. `codex exec resume <session_id>` summary
+  3. Transcript-line fallback
+  4. Static `Summary unavailable` message
+- Watch flow is best-effort and does not change launch success semantics.
+
+**Design decisions:**
+- Always creates a new tmux pane (no pane reuse/tracking)
+- No exec fallback — REPL mode requires tmux
+- `_shared` only — never imports from `_cc-native`
+- Temp file cleanup after injection confirmed
+
+## Library: lib/codex-watcher.ts
+
+Reusable side-effect-free watch/summarize functions used by launch flow:
+- `waitForPaneClose(paneId, timeoutMs?)`
+- `summarizeViaSessionFileSpark(sessionFile)`
+- `summarizeViaResume(sessionId)`
+- `summarizeFromSessionFileFallback(sessionFile)`
+- `collectTranscriptLines(sessionFile)`
+
+Constants and helper utilities are exported for reuse and testing (`POLL_INTERVAL_MS`, `SUMMARY_UNAVAILABLE_MESSAGE`, `normalizeText`, `looksLikeBadSummary`, etc.).
+
+**Resilience policy:**
+- Watch path is best-effort and never fails a successful launch
+- Pane-wait timeout defaults to 4 hours; when reached, summarization continues with available transcript state
+- Summary functions degrade through layered fallbacks and end with static message

package/dist/templates/_shared/skills/codex/SKILL.md

@@ -0,0 +1,71 @@
+# /codex
+
+## Role
+
+You are the orchestrator. Each Codex launch spawns an implementation sub-agent. Delegate implementation work to Codex, then review results when summaries arrive.
+
+The script blocks until Codex exits and prints a session summary. Run with Bash `run_in_background: true` so you stay unblocked and receive the summary as a background task notification.
+
+## Command
+
+```
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [flags] <mode>
+```
+
+**Modes:** `plan` | `--file <path>` | `<inline text...>`
+
+**Flags:**
+- `--context <id>` — Project orientation for the sub-agent. Pass when implementing a plan so Codex understands the project structure.
+- `--prompt <text>` — Scope the agent's work. Direct each instance to a specific plan section or task.
+- `--model <name>` — Aliases: `spark`, `codex`, `gpt`. Tiers: `fast`, `standard`, `smart`. Or any full model ID.
+- `--sandbox <mode>` — `read-only`, `workspace-write`, `danger-full-access`.
+- `--no-yolo` — Disable YOLO mode (on by default).
+- `--no-watch` — Fire-and-forget: exit immediately after launch, skip waiting for summary.
+
+## Delegation Patterns
+
+### One-shot
+
+For small or tightly coupled plans. One sub-agent implements the whole plan.
+
+```bash
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts --context <ctx-id> plan
+```
+
+Run with `run_in_background: true`. Wait for the summary. Review the changes.
+
+### Parallel
+
+For plans with independent sections. Each sub-agent owns one section, scoped by `--prompt`.
+
+```bash
+# Sub-agent A — section 1
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts \
+  --context <ctx-id> --prompt "Implement section 1: Extract watch logic into lib/codex-watcher.ts" plan
+
+# Sub-agent B — section 3
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts \
+  --context <ctx-id> --prompt "Implement section 3: Update launch-codex.ts arg parsing" plan
+```
+
+Run each with `run_in_background: true`. Summaries arrive as separate background task notifications. When all complete, review for conflicts between agents, then verify with tests or import checks.
+
+### Ad-hoc
+
+For tasks outside a plan. Pass inline text or a file path.
+
+```bash
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts \
+  "Fix the failing test in auth.ts"
+
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts \
+  --file path/to/task-description.md
+```
+
+## Orchestrator Checklist
+
+- **Delegate implementation.** If the work involves writing code and Codex can handle it, send it to Codex.
+- **Split independent sections** into parallel sub-agents for faster execution.
+- **Pass `--context`** when implementing a plan — Codex needs project orientation to make good decisions.
+- **Scope with `--prompt`** when running parallel agents — each sub-agent performs better when it knows exactly which section it owns.
+- **Review results** when summaries arrive. Check for merge conflicts between parallel agents, then verify with `tsc --noEmit`, tests, or manual inspection.

package/dist/templates/_shared/skills/{prompt-codex/scripts/watch-codex.ts → codex/lib/codex-watcher.ts}

@@ -1,5 +1,3 @@
-#!/usr/bin/env bun
-
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -10,15 +8,16 @@ import { CODEX_MODELS } from "../../../lib-ts/base/models.js";
 import { execFileAsync } from "../../../lib-ts/base/subprocess-utils.js";
 import { getTmuxAvailability } from "../../../lib-ts/base/tmux-driver.js";
 
-const POLL_INTERVAL_MS = 2000;
-const POLL_TIMEOUT_MS = 3000;
-const SUMMARY_TIMEOUT_SEC = 8;
-const RESUME_TIMEOUT_MS = 45000;
-const MAX_TRANSCRIPT_LINES = 220;
-const MAX_LINE_LENGTH = 500;
-const SUMMARY_UNAVAILABLE_MESSAGE = "Codex session completed. Summary unavailable.";
+export const POLL_INTERVAL_MS = 2000;
+export const POLL_TIMEOUT_MS = 3000;
+export const SUMMARY_TIMEOUT_SEC = 8;
+export const RESUME_TIMEOUT_MS = 45000;
+export const MAX_TRANSCRIPT_LINES = 220;
+export const MAX_LINE_LENGTH = 500;
+export const WAIT_TIMEOUT_MS_DEFAULT = 14_400_000;
+export const SUMMARY_UNAVAILABLE_MESSAGE = "Codex session completed. Summary unavailable.";
 
-const TRANSCRIPT_SUMMARY_PROMPT = `Summarize this Codex session transcript excerpt.
+export const TRANSCRIPT_SUMMARY_PROMPT = `Summarize this Codex session transcript excerpt.
 Return 3-5 concise bullet points.
 Focus on:
 - what was accomplished
@@ -28,7 +27,7 @@ Do not ask follow-up questions.
 Do not request additional input.
 If information is partial, provide best-effort summary from available text.`;
 
-const RESUME_SUMMARY_PROMPT = `Summarize the previous Codex session in 3-5 concise bullet points.
+export const RESUME_SUMMARY_PROMPT = `Summarize the previous Codex session in 3-5 concise bullet points.
 Focus on:
 - what was accomplished
 - files changed
@@ -37,11 +36,11 @@ Do not ask follow-up questions.
 Do not request additional input.
 If the prior session was brief, still provide a best-effort summary.`;
 
-function sleep(ms: number): Promise<void> {
+export function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function safeCleanup(filePath: string): void {
+export function safeCleanup(filePath: string): void {
   try {
     if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
   } catch {
@@ -49,7 +48,7 @@ function safeCleanup(filePath: string): void {
   }
 }
 
-function readTextIfExists(filePath: string): string {
+export function readTextIfExists(filePath: string): string {
   try {
     if (!filePath || !fs.existsSync(filePath)) return "";
     return fs.readFileSync(filePath, "utf-8").trim();
@@ -58,7 +57,7 @@ function readTextIfExists(filePath: string): string {
   }
 }
 
-function normalizeText(text: string): string {
+export function normalizeText(text: string): string {
   return text
     .replace(/\r/g, "")
     .replace(/[\x00-\x08\x0B-\x1F\x7F]/g, "")
@@ -66,7 +65,7 @@ function normalizeText(text: string): string {
     .trim();
 }
 
-function getMessageContentText(content: unknown): string {
+export function getMessageContentText(content: unknown): string {
   if (!Array.isArray(content)) return "";
   return content
     .map((entry: any) => {
@@ -77,7 +76,7 @@ function getMessageContentText(content: unknown): string {
     .join("\n");
 }
 
-function collectTranscriptLines(sessionFile: string): string[] {
+export function collectTranscriptLines(sessionFile: string): string[] {
   if (!sessionFile || !fs.existsSync(sessionFile)) return [];
 
   const out: string[] = [];
@@ -126,7 +125,7 @@ function collectTranscriptLines(sessionFile: string): string[] {
   return out.slice(-MAX_TRANSCRIPT_LINES);
 }
 
-function looksLikeBadSummary(output: string): boolean {
+export function looksLikeBadSummary(output: string): boolean {
   const normalized = output.toLowerCase();
   return (
     normalized.includes("don't see") ||
@@ -136,14 +135,22 @@ function looksLikeBadSummary(output: string): boolean {
   );
 }
 
-async function waitForPaneClose(paneId: string): Promise<void> {
+export async function waitForPaneClose(paneId: string, timeoutMs = WAIT_TIMEOUT_MS_DEFAULT): Promise<void> {
+  if (!paneId) return;
+
   const tmux = getTmuxAvailability();
   if (!tmux.available || !tmux.tmuxPath) {
     logWarn("codex-capture", `tmux unavailable while watching pane ${paneId}: ${tmux.reason ?? "unknown reason"}`);
     return;
   }
 
+  const deadline = Date.now() + timeoutMs;
   while (true) {
+    if (Date.now() >= deadline) {
+      logDebug("codex-capture", `watch timeout reached for pane ${paneId} after ${timeoutMs}ms`);
+      return;
+    }
+
     const result = await execFileAsync(tmux.tmuxPath, ["list-panes", "-a", "-F", "#{pane_id}"], {
       timeout: POLL_TIMEOUT_MS,
     });
@@ -156,11 +163,12 @@ async function waitForPaneClose(paneId: string): Promise<void> {
     const activePaneIds = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
     if (!activePaneIds.includes(paneId)) return;
 
-    await sleep(POLL_INTERVAL_MS);
+    const remainingMs = deadline - Date.now();
+    await sleep(Math.max(0, Math.min(POLL_INTERVAL_MS, remainingMs)));
   }
 }
 
-function summarizeViaSessionFileSpark(sessionFile: string): string | null {
+export function summarizeViaSessionFileSpark(sessionFile: string): string | null {
   const transcriptLines = collectTranscriptLines(sessionFile);
   if (transcriptLines.length === 0) return null;
 
@@ -184,7 +192,7 @@ function summarizeViaSessionFileSpark(sessionFile: string): string | null {
   return null;
 }
 
-async function summarizeViaResume(sessionId: string): Promise<string | null> {
+export async function summarizeViaResume(sessionId: string): Promise<string | null> {
   const outputFile = path.join(os.tmpdir(), `codex-resume-summary-${Date.now()}-${process.pid}.txt`);
 
   const result = await execFileAsync(
@@ -211,47 +219,8 @@ async function summarizeViaResume(sessionId: string): Promise<string | null> {
   return null;
 }
 
-function summarizeFromSessionFileFallback(sessionFile: string): string | null {
+export function summarizeFromSessionFileFallback(sessionFile: string): string | null {
   const lines = collectTranscriptLines(sessionFile).slice(-12);
   if (lines.length === 0) return null;
   return `Codex session completed. Transcript fallback:\n- ${lines.join("\n- ")}`;
 }
-
-async function main(): Promise<void> {
-  const [paneId, sessionId, sessionFile] = process.argv.slice(2);
-
-  if (!paneId) {
-    console.log(SUMMARY_UNAVAILABLE_MESSAGE);
-    return;
-  }
-
-  await waitForPaneClose(paneId);
-
-  const transcriptSummary = summarizeViaSessionFileSpark(sessionFile ?? "");
-  if (transcriptSummary) {
-    console.log(transcriptSummary);
-    return;
-  }
-
-  if (sessionId) {
-    const resumeSummary = await summarizeViaResume(sessionId);
-    if (resumeSummary) {
-      console.log(resumeSummary);
-      return;
-    }
-  }
-
-  const fallback = summarizeFromSessionFileFallback(sessionFile ?? "");
-  if (fallback) {
-    console.log(fallback);
-    return;
-  }
-
-  console.log(SUMMARY_UNAVAILABLE_MESSAGE);
-}
-
-main().catch((error) => {
-  logWarn("codex-capture", `watch-codex failed: ${String(error)}`);
-  console.log(SUMMARY_UNAVAILABLE_MESSAGE);
-  process.exit(0);
-});

package/dist/templates/_shared/skills/{prompt-codex → codex}/scripts/launch-codex.ts

@@ -3,9 +3,9 @@
  * Launch Codex in a tmux pane and inject a prompt into its REPL.
  *
  * Usage:
- *   bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|workspace-write|danger-full-access] [--no-yolo] [--capture] [--context <id>] plan
- *   bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|workspace-write|danger-full-access] [--no-yolo] [--capture] [--context <id>] --file <path>
- *   bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|workspace-write|danger-full-access] [--no-yolo] [--capture] [--context <id>] <inline text...>
+ *   bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|workspace-write|danger-full-access] [--no-yolo] [--no-watch] [--context <id>] [--prompt <text>] plan
+ *   bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|workspace-write|danger-full-access] [--no-yolo] [--no-watch] [--context <id>] [--prompt <text>] --file <path>
+ *   bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|workspace-write|danger-full-access] [--no-yolo] [--no-watch] [--context <id>] [--prompt <text>] <inline text...>
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -179,16 +179,17 @@ function findLatestPlanByMtime(projectRoot: string): string | null {
 const rawArgs = process.argv.slice(2);
 
 if (rawArgs.length === 0) {
-  eprint("Usage: launch-codex.ts [--model <model>] [--sandbox <mode>] [--no-yolo] [--capture] [--context <id>] plan | --file <path> | <text...>");
+  eprint("Usage: launch-codex.ts [--model <model>] [--sandbox <mode>] [--no-yolo] [--no-watch] [--context <id>] [--prompt <text>] plan | --file <path> | <text...>");
   process.exit(1);
 }
 
-// Extract --model, --sandbox, and --context flags before mode dispatch
+// Extract flags before mode dispatch
 let modelFlag: string | undefined;
 let sandboxFlag: CodexSandbox | undefined;
 let contextFlag: string | undefined;
+let extraPrompt: string | undefined;
 let yolo = true;
-let capture = false;
+let watch = true;
 const args: string[] = [];
 
 for (let i = 0; i < rawArgs.length; i++) {
@@ -203,19 +204,24 @@ for (let i = 0; i < rawArgs.length; i++) {
     sandboxFlag = val;
   } else if (rawArgs[i] === "--context" && i + 1 < rawArgs.length) {
     contextFlag = rawArgs[++i];
+  } else if (rawArgs[i] === "--prompt" && i + 1 < rawArgs.length) {
+    extraPrompt = rawArgs[++i];
+  } else if (rawArgs[i] === "--prompt") {
+    eprint("Error: --prompt requires a text argument.");
+    process.exit(1);
   } else if (rawArgs[i] === "--yolo") {
     yolo = true;
   } else if (rawArgs[i] === "--no-yolo") {
     yolo = false;
-  } else if (rawArgs[i] === "--capture") {
-    capture = true;
+  } else if (rawArgs[i] === "--no-watch") {
+    watch = false;
   } else {
     args.push(rawArgs[i]);
   }
 }
 
 if (args.length === 0) {
-  eprint("Usage: launch-codex.ts [--model <model>] [--sandbox <mode>] [--no-yolo] [--capture] [--context <id>] plan | --file <path> | <text...>");
+  eprint("Usage: launch-codex.ts [--model <model>] [--sandbox <mode>] [--no-yolo] [--no-watch] [--context <id>] [--prompt <text>] plan | --file <path> | <text...>");
   process.exit(1);
 }
 
@@ -303,6 +309,22 @@ if (ctx && promptPath) {
   }
 }
 
+if (extraPrompt && promptPath) {
+  try {
+    const base = fs.readFileSync(promptPath, "utf-8");
+    const combined = `${base}\n\n---\n\n## Additional Instructions\n\n${extraPrompt}`;
+    const extraPromptPath = path.join(os.tmpdir(), `codex-extra-prompt-${Date.now()}.md`);
+    fs.writeFileSync(extraPromptPath, combined, "utf-8");
+    if (tempFile) {
+      try { fs.unlinkSync(tempFile); } catch { /* ignore */ }
+    }
+    promptPath = extraPromptPath;
+    tempFile = extraPromptPath;
+  } catch {
+    logWarn("codex-skill", "Extra prompt append failed, continuing without it");
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Pre-flight: tmux required
 // ---------------------------------------------------------------------------
@@ -324,13 +346,14 @@ if (yolo) console.log("Mode: YOLO (bypass approvals and sandbox)");
 if (sandboxFlag) console.log(`Sandbox: ${sandboxFlag}`);
 if (resolvedModel) console.log(`Model: ${resolvedModel}${modelFlag !== resolvedModel ? ` (from "${modelFlag}")` : ""}`);
 
-logDebug("codex-skill", `Launching: model=${resolvedModel ?? "default"}, sandbox=${sandboxFlag ?? "default"}, yolo=${yolo}, source=${args[0]}, bytes=${promptPath ? fs.statSync(promptPath).size : 0}`);
+logDebug("codex-skill", `Launching: model=${resolvedModel ?? "default"}, sandbox=${sandboxFlag ?? "default"}, yolo=${yolo}, extraPrompt=${!!extraPrompt}, source=${args[0]}, bytes=${promptPath ? fs.statSync(promptPath).size : 0}`);
 const launchStartedAtMs = Date.now();
 
 const result = await launchDriverInTmuxOrFallback({
   toolName: "codex",
   mode: "repl",
   args: codexArgs,
+  splitFlag: "auto",
   promptPath,
   sendPromptInRepl: true,
   allowExecFallback: false,
@@ -363,21 +386,32 @@ if (result.paneId) {
   console.log("Codex launched in tmux pane.");
 }
 
-if (capture && result.paneId) {
+if (watch && result.paneId) {
   try {
+    const {
+      SUMMARY_UNAVAILABLE_MESSAGE,
+      summarizeFromSessionFileFallback,
+      summarizeViaResume,
+      summarizeViaSessionFileSpark,
+      waitForPaneClose,
+    } = await import("../lib/codex-watcher.js");
+
     const sessionInfo = await waitForCaptureSession(projectRoot, launchStartedAtMs);
-    if (sessionInfo) {
-      console.log(`CODEX_CAPTURE_PANE=${result.paneId}`);
-      console.log(`CODEX_CAPTURE_SESSION_ID=${sessionInfo.sessionId}`);
-      console.log(`CODEX_CAPTURE_SESSION_FILE=${sessionInfo.sessionFile}`);
-    } else {
-      logWarn(
-        "codex-skill",
-        `Capture session discovery failed for pane ${result.paneId} in ${SESSION_DISCOVERY_TIMEOUT_MS}ms`,
-      );
-    }
+    await waitForPaneClose(result.paneId);
+
+    const sessionFile = sessionInfo?.sessionFile ?? "";
+    const sessionId = sessionInfo?.sessionId ?? "";
+    const summary = summarizeViaSessionFileSpark(sessionFile)
+      ?? (sessionId ? await summarizeViaResume(sessionId) : null)
+      ?? summarizeFromSessionFileFallback(sessionFile)
+      ?? SUMMARY_UNAVAILABLE_MESSAGE;
+
+    console.log("\n--- Codex Session Summary ---");
+    console.log(summary);
   } catch (error) {
-    logWarn("codex-skill", `Capture session discovery threw for ${result.paneId}: ${String(error)}`);
+    logWarn("codex-skill", `Watch flow failed for ${result.paneId}: ${String(error)}`);
+    console.log("\n--- Codex Session Summary ---");
+    console.log("Codex session completed. Summary unavailable.");
   }
 }
 

package/dist/templates/_shared/skills/codex/scripts/watch-codex.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env bun
+/**
+ * Thin CLI wrapper over lib/codex-watcher.ts for backward compatibility.
+ *
+ * Usage:
+ *   bun watch-codex.ts <pane_id> <session_id> <session_file>
+ *
+ * Prefer using launch-codex.ts directly (watch is built-in by default).
+ */
+import {
+  SUMMARY_UNAVAILABLE_MESSAGE,
+  summarizeFromSessionFileFallback,
+  summarizeViaResume,
+  summarizeViaSessionFileSpark,
+  waitForPaneClose,
+} from "../lib/codex-watcher.js";
+
+async function main(): Promise<void> {
+  const [paneId, sessionId, sessionFile] = process.argv.slice(2);
+  if (!paneId) {
+    console.log(SUMMARY_UNAVAILABLE_MESSAGE);
+    return;
+  }
+
+  await waitForPaneClose(paneId);
+
+  const sf = sessionFile ?? "";
+  const sid = sessionId ?? "";
+  const summary =
+    summarizeViaSessionFileSpark(sf) ??
+    (sid ? await summarizeViaResume(sid) : null) ??
+    summarizeFromSessionFileFallback(sf) ??
+    SUMMARY_UNAVAILABLE_MESSAGE;
+
+  console.log("\n--- Codex Session Summary ---");
+  console.log(summary);
+}
+
+main().catch((error) => {
+  console.error(`watch-codex error: ${String(error)}`);
+  console.log(SUMMARY_UNAVAILABLE_MESSAGE);
+});

package/oclif.manifest.json

@@ -434,5 +434,5 @@
       ]
     }
   },
-  "version": "0.15.1"
+  "version": "0.15.2"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aiwcli",
   "description": "AI Workflow CLI - Command-line interface for AI-powered workflows",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "author": "jofu-tofu",
   "bin": {
     "aiw": "bin/run.js"

package/dist/templates/_shared/.claude/skills/codex/prompt.md

@@ -1,30 +0,0 @@
-# /codex
-
-| Command | Description |
-|---|---|
-| `bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|workspace-write|danger-full-access] [--no-yolo] [--capture] plan` | Launch Codex REPL with active plan. |
-| `bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|workspace-write|danger-full-access] [--no-yolo] [--capture] --file <path>` | Launch Codex REPL with file contents. |
-| `bun launch-codex.ts [--model fast|standard|smart|<model-id>] [--sandbox read-only|workspace-write|danger-full-access] [--no-yolo] [--capture] <inline text...>` | Launch Codex REPL with inline prompt. |
-
-- `--model`: model tier (`fast`/`standard`/`smart`) resolves to `gpt-5.3-codex-spark` / `gpt-5.3-codex`, or any explicit Codex model id. Aliases: `spark`, `codex`, `gpt`.
-- `--sandbox`: `read-only`, `workspace-write`, or `danger-full-access`. Default is `danger-full-access` for implementation handoffs.
-- YOLO mode is **on by default** — bypasses all approvals and sandbox (`--dangerously-bypass-approvals-and-sandbox`). Use `--no-yolo` to disable.
-- `--capture`: best-effort session capture. If setup succeeds, launch output includes:
-  - `CODEX_CAPTURE_PANE=<pane_id>`
-  - `CODEX_CAPTURE_SESSION_ID=<session_id>`
-  - `CODEX_CAPTURE_SESSION_FILE=<path>`
-
-If launch output includes `CODEX_CAPTURE_PANE` and `CODEX_CAPTURE_SESSION_ID`:
-
-1. Parse pane/session metadata from stdout.
-2. Start a background watcher:
-```bash
-bun .aiwcli/_shared/skills/prompt-codex/scripts/watch-codex.ts <pane_id> <session_id> <session_file>
-```
-Use `Bash` with `run_in_background: true`.
-3. Tell the user: `Codex is running in the tmux pane. I'll receive a summary when you exit.`
-4. Continue with other work; the background task output will arrive as a notification.
-
-Watcher behavior:
-- Primary: summarize from `CODEX_CAPTURE_SESSION_FILE` with Spark.
-- Fallback: use `codex exec resume <session_id>` if transcript summarization fails.

package/dist/templates/_shared/skills/prompt-codex/CLAUDE.md

@@ -1,71 +0,0 @@
-# Prompt Codex Skill
-
-Launch Codex CLI in a tmux pane and inject a prompt into its REPL.
-
-## Directory Structure
-
-```
-prompt-codex/
-├── CLAUDE.md       ← This file
-└── scripts/
-    ├── launch-codex.ts  ← CLI entry point
-    └── watch-codex.ts   ← Capture watcher and summarizer
-```
-
-## Script: launch-codex.ts
-
-**Usage:**
-```bash
-bun .aiwcli/_shared/skills/prompt-codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--full-auto] plan
-bun .aiwcli/_shared/skills/prompt-codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--full-auto] --file <path>
-bun .aiwcli/_shared/skills/prompt-codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--full-auto] <inline text...>
-bun .aiwcli/_shared/skills/prompt-codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--full-auto] [--capture] <mode>
-```
-
-**Args:**
-- `plan` — discover active plan via context system, inject into Codex REPL
-- `--file <path>` — inject file contents into Codex REPL
-- `<text...>` — join remaining args as inline prompt, write to temp file, inject
-- `--model <alias|tier|id>` — Aliases: `spark` → `gpt-5.3-codex-spark`, `codex` → `gpt-5.3-codex`, `gpt` → `gpt-5.2`. Tiers: `fast`/`standard`/`smart` (resolved via `resolveModelForProvider()`). Or any full model ID. Aliases are checked first (local `CODEX_ALIASES` constant in `launch-codex.ts`), then tiers, then pass-through. Omitted = Codex default.
-- `--sandbox <mode>` — `read-only`, `workspace-write`, or `danger-full-access`. Default is `danger-full-access` for implementation handoffs.
-- `--no-yolo` — Disable YOLO mode (on by default). YOLO maps to Codex CLI's `--dangerously-bypass-approvals-and-sandbox`. Use `--no-yolo` to restore normal approval prompts.
-- `--capture` — Best-effort session capture. On success, prints:
-  - `CODEX_CAPTURE_PANE=<pane_id>`
-  - `CODEX_CAPTURE_SESSION_ID=<session_id>`
-  - `CODEX_CAPTURE_SESSION_FILE=<session_file>`
-  These are consumed by the skill prompt to run `watch-codex.ts` as a background task.
-
-**Plan discovery order:**
-1. `CLAUDE_SESSION_ID` env → `getContextBySessionId()` → `findLatestPlan(contextId)`
-2. Fallback: scan `_output/contexts/*/plans/*.md` by mtime (inline, no `_cc-native` import)
-
-**Dependencies (all from `_shared/lib-ts/`):**
-- `base/tmux-driver.ts` — `launchDriverInTmuxOrFallback()`, `getTmuxAvailability()`
-- `base/cli-args.ts` — `resolveCodexModel()`, `codexReplSpec()`, `buildCliInvocation()`, `isCodexSandbox()`
-- `base/logger.ts` — `logDebug()`, `logWarn()` (injection diagnostics)
-- `context/context-store.ts` — `getContextBySessionId()`
-- `context/context-formatter.ts` — `buildExternalAgentContext()` (orientation header for Codex)
-- `context/plan-manager.ts` — `findLatestPlan()`
-
-**Design decisions:**
-- Always creates a new tmux pane (no pane reuse/tracking)
-- No exec fallback — REPL mode requires tmux
-- `_shared` only — never imports from `_cc-native`
-- Temp file cleanup after injection confirmed
-
-## Script: watch-codex.ts
-
-**Usage:**
-```bash
-bun .aiwcli/_shared/skills/prompt-codex/scripts/watch-codex.ts <pane_id> <session_id> <session_file>
-```
-
-**Behavior:**
-- Polls tmux until `<pane_id>` closes
-- Primary: parses `<session_file>` transcript and summarizes via Spark (`inference()` + `CODEX_MODELS.spark`)
-- Fallback: runs `codex exec resume <session_id>` if transcript summarization fails
-- Final fallback: emits concise transcript lines directly from `<session_file>`
-
-**Resilience policy:**
-- Capture path is best-effort and never blocks Codex launch
-- Watcher exits cleanly on poll/summary/parse failures with fallback text