oh-my-codex 0.7.5 → 0.8.0

package/scripts/notify-hook/visual-verdict.js

@@ -0,0 +1,158 @@
+/**
+ * Visual verdict extraction and persistence.
+ *
+ * Parses PASS / FAIL / INCOMPLETE verdicts from verifier agent output
+ * and persists them to stateDir/verdicts/latest-verdict.json.
+ *
+ * All failures are logged with structured context (issue #421) rather
+ * than silently swallowed.
+ */
+
+import { writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { logNotifyHookEvent } from './log.js';
+import { safeString } from './utils.js';
+
+/** Structured patterns that reliably indicate a verification verdict. */
+const VERDICT_PATTERNS = [
+  /\*\*Status\*\*:\s*(PASS|FAIL|INCOMPLETE)/i,
+  /\bVerdict:\s*(PASS|FAIL|INCOMPLETE)\b/i,
+];
+
+/**
+ * Heuristic: output contains verdict-like markers but no structured match.
+ * Used to emit a debug-level log for candidate parse failures.
+ */
+const VERDICT_CANDIDATE_RE = /(?:\*\*Status\*\*\s*:|Verdict\s*:)/i;
+
+function extractJsonCandidates(rawMessage) {
+  const message = safeString(rawMessage).trim();
+  if (!message) return [];
+
+  const candidates = [message];
+  const fencePattern = /```(?:json)?\s*([\s\S]*?)```/gi;
+  for (const match of message.matchAll(fencePattern)) {
+    const block = safeString(match[1]).trim();
+    if (block) candidates.push(block);
+  }
+  return candidates;
+}
+
+async function maybePersistRuntimeVisualFeedback({ cwd, output, sessionId }) {
+  if (!cwd || !output) return;
+
+  const candidates = extractJsonCandidates(output);
+  if (candidates.length === 0) return;
+
+  const { buildVisualLoopFeedback } = await import('../../dist/visual/verdict.js');
+  const { recordRalphVisualFeedback } = await import('../../dist/ralph/persistence.js');
+
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      const feedback = buildVisualLoopFeedback(parsed);
+      await recordRalphVisualFeedback(cwd, feedback, sessionId || undefined);
+      return;
+    } catch {
+      // Try next candidate
+    }
+  }
+}
+
+/**
+ * Attempt to extract a structured verdict from free-form text.
+ * Returns `{ verdict, raw }` on success, `null` otherwise.
+ */
+export function parseVisualVerdict(text) {
+  if (!text || typeof text !== 'string') return null;
+  for (const pattern of VERDICT_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      return { verdict: match[1].toUpperCase(), raw: match[0] };
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse a visual verdict from the agent payload output and persist it.
+ *
+ * Logs structured warnings/debug events instead of silently swallowing
+ * errors (addresses issue #421):
+ *   - debug: candidate markers found but no structured verdict matched
+ *   - warn:  verdict file write failure (with turn/session context)
+ *
+ * Module import failure is handled by the caller in notify-hook.js.
+ */
+export async function maybePersistVisualVerdict({ cwd, payload, stateDir, logsDir, sessionId, turnId }) {
+  const output = safeString(
+    payload?.['last-assistant-message'] || payload?.last_assistant_message || '',
+  );
+  if (!output) return;
+
+  // Runtime visual feedback (JSON/fenced JSON) for ralph-progress persistence.
+  // Non-fatal and observable via warn-level structured logging.
+  try {
+    await maybePersistRuntimeVisualFeedback({ cwd, output, sessionId });
+  } catch (err) {
+    await logNotifyHookEvent(logsDir, {
+      timestamp: new Date().toISOString(),
+      level: 'warn',
+      type: 'visual_runtime_feedback_persist_failure',
+      error: err?.message || String(err),
+      session_id: sessionId,
+      turn_id: turnId,
+    });
+  }
+
+  const parsed = parseVisualVerdict(output);
+
+  if (!parsed) {
+    // Debug level: verdict-like markers present but no structured match
+    if (VERDICT_CANDIDATE_RE.test(output)) {
+      await logNotifyHookEvent(logsDir, {
+        timestamp: new Date().toISOString(),
+        level: 'debug',
+        type: 'visual_verdict_parse_no_match',
+        session_id: sessionId,
+        turn_id: turnId,
+      });
+    }
+    return;
+  }
+
+  // Persist the extracted verdict
+  try {
+    const verdictDir = join(stateDir, 'verdicts');
+    await mkdir(verdictDir, { recursive: true });
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      verdict: parsed.verdict,
+      raw_match: parsed.raw,
+      session_id: sessionId,
+      turn_id: turnId,
+    };
+
+    await writeFile(
+      join(verdictDir, 'latest-verdict.json'),
+      JSON.stringify(entry, null, 2),
+    );
+
+    await logNotifyHookEvent(logsDir, {
+      ...entry,
+      level: 'info',
+      type: 'visual_verdict_persisted',
+    });
+  } catch (err) {
+    // Warn level: persistence write failure with turn/session context
+    await logNotifyHookEvent(logsDir, {
+      timestamp: new Date().toISOString(),
+      level: 'warn',
+      type: 'visual_verdict_write_failure',
+      error: err?.message || String(err),
+      session_id: sessionId,
+      turn_id: turnId,
+    });
+  }
+}

package/scripts/notify-hook.js

@@ -404,6 +404,33 @@ async function main() {
     // Non-critical
   }
 
+  // 10.5. Visual verdict persistence (non-fatal, observable – issue #421)
+  if (!isTeamWorker) {
+    try {
+      const { maybePersistVisualVerdict } = await import('./notify-hook/visual-verdict.js');
+      await maybePersistVisualVerdict({
+        cwd,
+        payload,
+        stateDir,
+        logsDir,
+        sessionId: payloadSessionId,
+        turnId: safeString(payload['turn-id'] || payload.turn_id || ''),
+      });
+    } catch (err) {
+      // Structured warning for module import failure (issue #421)
+      const warnEntry = JSON.stringify({
+        timestamp: new Date().toISOString(),
+        level: 'warn',
+        type: 'visual_verdict_import_failure',
+        error: err?.message || String(err),
+        session_id: payloadSessionId,
+        turn_id: safeString(payload['turn-id'] || payload.turn_id || ''),
+      });
+      const warnFile = join(logsDir, `notify-hook-${new Date().toISOString().split('T')[0]}.jsonl`);
+      await appendFile(warnFile, warnEntry + '\n').catch(() => {});
+    }
+  }
+
   // 10. Code simplifier: delegate recently modified files for simplification.
   //     Opt-in via ~/.omx/config.json: { "codeSimplifier": { "enabled": true } }
   if (!isTeamWorker) {

package/scripts/run-provider-advisor.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import process from 'process';
+import { spawnSync } from 'child_process';
+
+const PROVIDER_BINARIES = {
+  claude: 'claude',
+  gemini: 'gemini',
+};
+const ASK_ORIGINAL_TASK_ENV = 'OMX_ASK_ORIGINAL_TASK';
+
+function usage() {
+  console.error('Usage: omx ask <claude|gemini> "<prompt>"');
+  console.error('Legacy direct usage: node scripts/run-provider-advisor.js <claude|gemini> <prompt...>');
+  console.error('                 or: node scripts/run-provider-advisor.js claude --print "<prompt>"');
+  console.error('                 or: node scripts/run-provider-advisor.js gemini --prompt "<prompt>"');
+}
+
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'task';
+}
+
+function timestampToken(date = new Date()) {
+  return date.toISOString().replace(/[:.]/g, '-');
+}
+
+function parseArgs(argv) {
+  const [providerRaw, ...rest] = argv;
+  const provider = (providerRaw || '').toLowerCase();
+
+  if (!provider || !(provider in PROVIDER_BINARIES)) {
+    usage();
+    process.exit(1);
+  }
+
+  if (rest.length === 0) {
+    usage();
+    process.exit(1);
+  }
+
+  if (rest[0] === '-p' || rest[0] === '--print' || rest[0] === '--prompt') {
+    const prompt = rest.slice(1).join(' ').trim();
+    if (!prompt) {
+      usage();
+      process.exit(1);
+    }
+    return { provider, prompt };
+  }
+
+  return { provider, prompt: rest.join(' ').trim() };
+}
+
+function ensureBinary(binary) {
+  const probe = spawnSync(binary, ['--version'], {
+    stdio: 'ignore',
+    encoding: 'utf8',
+  });
+
+  if (probe.error && probe.error.code === 'ENOENT') {
+    const verify = `${binary} --version`;
+    console.error(`[ask-${binary}] Missing required local CLI binary: ${binary}`);
+    console.error(`[ask-${binary}] Install/configure ${binary} CLI, then verify with: ${verify}`);
+    process.exit(1);
+  }
+}
+
+function buildSummary(exitCode, output) {
+  if (exitCode === 0) {
+    return 'Provider completed successfully. Review the raw output for details.';
+  }
+
+  const firstLine = output
+    .split('\n')
+    .map((line) => line.trim())
+    .find(Boolean);
+
+  return firstLine
+    ? `Provider command failed (exit ${exitCode}): ${firstLine}`
+    : `Provider command failed with exit code ${exitCode}.`;
+}
+
+function buildActionItems(exitCode) {
+  if (exitCode === 0) {
+    return ['Review the response and extract decisions you want to apply.', 'Capture follow-up implementation tasks if needed.'];
+  }
+
+  return ['Inspect the raw output error details.', 'Fix CLI/auth/environment issues and rerun the command.'];
+}
+
+async function writeArtifact({ provider, originalTask, finalPrompt, rawOutput, exitCode }) {
+  const root = process.cwd();
+  const artifactDir = join(root, '.omx', 'artifacts');
+  const slug = slugify(originalTask);
+  const timestamp = timestampToken();
+  const artifactPath = join(artifactDir, `${provider}-${slug}-${timestamp}.md`);
+
+  const summary = buildSummary(exitCode, rawOutput);
+  const actionItems = buildActionItems(exitCode);
+
+  const body = [
+    `# ${provider} advisor artifact`,
+    '',
+    `- Provider: ${provider}`,
+    `- Exit code: ${exitCode}`,
+    `- Created at: ${new Date().toISOString()}`,
+    '',
+    '## Original task',
+    '',
+    originalTask,
+    '',
+    '## Final prompt',
+    '',
+    finalPrompt,
+    '',
+    '## Raw output',
+    '',
+    '```text',
+    rawOutput || '(no output)',
+    '```',
+    '',
+    '## Concise summary',
+    '',
+    summary,
+    '',
+    '## Action items',
+    '',
+    ...actionItems.map((item) => `- ${item}`),
+    '',
+  ].join('\n');
+
+  await mkdir(artifactDir, { recursive: true });
+  await writeFile(artifactPath, body, 'utf8');
+  return artifactPath;
+}
+
+async function main() {
+  const { provider, prompt } = parseArgs(process.argv.slice(2));
+  const binary = PROVIDER_BINARIES[provider];
+
+  ensureBinary(binary);
+
+  const run = spawnSync(binary, ['-p', prompt], {
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024,
+  });
+
+  const stdout = run.stdout || '';
+  const stderr = run.stderr || '';
+  const rawOutput = [stdout, stderr].filter(Boolean).join(stdout && stderr ? '\n\n' : '');
+  const exitCode = typeof run.status === 'number' ? run.status : 1;
+
+  const artifactPath = await writeArtifact({
+    provider,
+    originalTask: process.env[ASK_ORIGINAL_TASK_ENV] ?? prompt,
+    finalPrompt: prompt,
+    rawOutput,
+    exitCode,
+  });
+
+  console.log(artifactPath);
+
+  if (run.error) {
+    console.error(`[ask-${provider}] ${run.error.message}`);
+  }
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}
+
+main().catch((error) => {
+  console.error(`[run-provider-advisor] ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/scripts/tmux-hook-engine.js

@@ -154,6 +154,30 @@ export function buildPaneInModeArgv(paneTarget) {
   return ['display-message', '-p', '-t', paneTarget, '#{pane_in_mode}'];
 }
 
+/**
+ * Returns the tmux argv to query the current foreground command of a pane.
+ * Used to detect when the agent process has exited and the pane has returned
+ * to a shell (zsh, bash, fish, etc.).
+ */
+export function buildPaneCurrentCommandArgv(paneTarget) {
+  return ['display-message', '-p', '-t', paneTarget, '#{pane_current_command}'];
+}
+
+const SHELL_COMMANDS = new Set(['zsh', 'bash', 'fish', 'sh', 'dash', 'ksh', 'csh', 'tcsh', 'login']);
+
+/**
+ * Returns true when the pane's foreground process is an interactive shell,
+ * meaning the agent has exited and injection would land on a bare prompt.
+ */
+export function isPaneRunningShell(paneCurrentCommand) {
+  if (typeof paneCurrentCommand !== 'string') return false;
+  const cmd = paneCurrentCommand.trim().toLowerCase();
+  if (cmd === '') return false;
+  // Handle paths like /bin/zsh -> zsh, and flags like -zsh -> zsh
+  const base = cmd.split('/').pop().replace(/^-/, '');
+  return SHELL_COMMANDS.has(base);
+}
+
 export function buildCapturePaneArgv(paneTarget, tailLines = 80) {
   return ['capture-pane', '-t', paneTarget, '-p', '-S', `-${tailLines}`];
 }

package/skills/ask-claude/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ask-claude
+description: Ask Claude via local CLI and capture a reusable artifact
+---
+
+# Ask Claude (Local CLI)
+
+Use the locally installed Claude CLI as a direct external advisor for focused questions, reviews, or second opinions.
+
+## Usage
+
+```bash
+/ask-claude <question or task>
+```
+
+## Routing
+
+### Preferred: Local CLI execution
+Run Claude through the canonical OMX CLI command path (no MCP routing):
+
+```bash
+omx ask claude "{{ARGUMENTS}}"
+```
+
+Exact non-interactive Claude CLI command from `claude --help`:
+
+```bash
+claude -p "{{ARGUMENTS}}"
+# equivalent: claude --print "{{ARGUMENTS}}"
+```
+
+If needed, adapt to the user's installed Claude CLI variant while keeping local execution as the default path.
+
+Legacy compatibility entrypoints (`./scripts/ask-claude.sh`, `npm run ask:claude -- ...`) are transitional wrappers.
+
+### Missing binary behavior
+If `claude` is not found, do **not** switch to MCP.
+Instead:
+1. Explain that local Claude CLI is required for this skill.
+2. Ask the user to install/configure Claude CLI.
+3. Provide a quick verification command:
+
+```bash
+claude --version
+```
+
+## Artifact requirement
+After local execution, save a markdown artifact to:
+
+```text
+.omx/artifacts/claude-<slug>-<timestamp>.md
+```
+
+Minimum artifact sections:
+1. Original user task
+2. Final prompt sent to Claude CLI
+3. Claude output (raw)
+4. Concise summary
+5. Action items / next steps
+
+Task: {{ARGUMENTS}}

package/skills/ask-gemini/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ask-gemini
+description: Ask Gemini via local CLI and capture a reusable artifact
+---
+
+# Ask Gemini (Local CLI)
+
+Use the locally installed Gemini CLI as a direct external advisor for brainstorming, design feedback, and second opinions.
+
+## Usage
+
+```bash
+/ask-gemini <question or task>
+```
+
+## Routing
+
+### Preferred: Local CLI execution
+Run Gemini through the canonical OMX CLI command path (no MCP routing):
+
+```bash
+omx ask gemini "{{ARGUMENTS}}"
+```
+
+Exact non-interactive Gemini CLI command from `gemini --help`:
+
+```bash
+gemini -p "{{ARGUMENTS}}"
+# equivalent: gemini --prompt "{{ARGUMENTS}}"
+```
+
+If needed, adapt to the user's installed Gemini CLI variant while keeping local execution as the default path.
+
+Legacy compatibility entrypoints (`./scripts/ask-gemini.sh`, `npm run ask:gemini -- ...`) are transitional wrappers.
+
+### Missing binary behavior
+If `gemini` is not found, do **not** switch to MCP.
+Instead:
+1. Explain that local Gemini CLI is required for this skill.
+2. Ask the user to install/configure Gemini CLI.
+3. Provide a quick verification command:
+
+```bash
+gemini --version
+```
+
+## Artifact requirement
+After local execution, save a markdown artifact to:
+
+```text
+.omx/artifacts/gemini-<slug>-<timestamp>.md
+```
+
+Minimum artifact sections:
+1. Original user task
+2. Final prompt sent to Gemini CLI
+3. Gemini output (raw)
+4. Concise summary
+5. Action items / next steps
+
+Task: {{ARGUMENTS}}

package/skills/autopilot/SKILL.md

@@ -32,10 +32,28 @@ Most non-trivial software tasks require coordinated phases: understanding requir
 - QA cycles repeat up to 5 times; if the same error persists 3 times, stop and report the fundamental issue
 - Validation requires approval from all reviewers; rejected items get fixed and re-validated
 - Cancel with `/cancel` at any time; progress is preserved for resume
+- If a deep-interview spec exists, use it as high-clarity phase input instead of re-expanding from scratch
+- If input is too vague for reliable expansion, offer/trigger `$deep-interview` first
+- Do not enter expansion/planning/execution-heavy phases until pre-context grounding exists; if fast execution is forced, proceed only with explicit risk notes
 </Execution_Policy>
 
 <Steps>
+0. **Pre-context Intake (required before Phase 0 starts)**:
+   - Derive a task slug from the request.
+   - Load the latest relevant snapshot from `.omx/context/{slug}-*.md` when available.
+   - If no snapshot exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
+     - Task statement
+     - Desired outcome
+     - Known facts/evidence
+     - Constraints
+     - Unknowns/open questions
+     - Likely codebase touchpoints
+   - If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` before proceeding.
+   - Carry the snapshot path into autopilot artifacts/state so all phases share grounded context.
+
 1. **Phase 0 - Expansion**: Turn the user's idea into a detailed spec
+   - If `.omx/specs/deep-interview-*.md` exists for this task: reuse it and skip redundant expansion work
+   - If prompt is highly vague: route to `$deep-interview` for Socratic ambiguity-gated clarification
    - Analyst (Opus): Extract requirements
    - Architect (Opus): Create technical specification
    - Output: `.omx/plans/autopilot-spec.md`
@@ -84,7 +102,7 @@ Most non-trivial software tasks require coordinated phases: understanding requir
 Use `omx_state` MCP tools for autopilot lifecycle state.
 
 - **On start**:
-  `state_write({mode: "autopilot", active: true, current_phase: "expansion", started_at: "<now>"})`
+  `state_write({mode: "autopilot", active: true, current_phase: "expansion", started_at: "<now>", state: {context_snapshot_path: "<snapshot-path>"}})`
 - **On phase transitions**:
   `state_write({mode: "autopilot", current_phase: "planning"})`
   `state_write({mode: "autopilot", current_phase: "execution"})`
@@ -121,7 +139,7 @@ Why bad: This is an exploration/brainstorming request. Respond conversationally
 - Stop and report when the same QA error persists across 3 cycles (fundamental issue requiring human input)
 - Stop and report when validation keeps failing after 3 re-validation rounds
 - Stop when the user says "stop", "cancel", or "abort"
-- If requirements were too vague and expansion produces an unclear spec, pause and ask the user for clarification before proceeding
+- If requirements were too vague and expansion produces an unclear spec, pause and redirect to `$deep-interview` before proceeding
 </Escalation_And_Stop_Conditions>
 
 <Final_Checklist>
@@ -139,7 +157,7 @@ Why bad: This is an exploration/brainstorming request. Respond conversationally
 Optional settings in `~/.codex/config.toml`:
 
 ```toml
-[omc.autopilot]
+[omx.autopilot]
 maxIterations = 10
 maxQaCycles = 5
 maxValidationRounds = 3
@@ -153,6 +171,18 @@ skipValidation = false
 
 If autopilot was cancelled or failed, run `/autopilot` again to resume from where it stopped.
 
+## Recommended Clarity Pipeline
+
+For ambiguous requests, prefer:
+
+```
+deep-interview -> ralplan -> autopilot
+```
+
+- `deep-interview`: ambiguity-gated Socratic requirements
+- `ralplan`: consensus planning (planner/architect/critic)
+- `autopilot`: execution + QA + validation
+
 ## Best Practices for Input
 
 1. Be specific about the domain -- "bookstore" not "store"
@@ -172,7 +202,7 @@ RALPLAN (consensus planning) -> team-exec (Codex CLI workers) -> ralph-verify (a
 Pipeline configuration options:
 
 ```toml
-[omc.autopilot.pipeline]
+[omx.autopilot.pipeline]
 maxRalphIterations = 10    # Ralph verification iteration ceiling
 workerCount = 2            # Number of Codex CLI team workers
 agentType = "executor"     # Agent type for team workers

package/skills/configure-notifications/SKILL.md

@@ -89,7 +89,7 @@ Then use AskUserQuestion:
 1. **Discord** - Webhook or bot notifications to Discord channels
 2. **Telegram** - Bot notifications to personal or group chats
 3. **Slack** - Incoming webhook notifications to Slack channels
-4. **OpenClaw** - Self-hosted HTTP or CLI command gateway
+4. **OpenClaw** - Self-hosted gateway (`notifications.openclaw.gateways + hooks`) with /hooks/agent delivery verification
 5. **Cross-cutting settings** - Verbosity, idle cooldown, profiles, reply listener
 6. **Disable all notifications** - Turn off all notification dispatching