oh-my-opencode 4.12.1 → 4.14.0

package/packages/omo-codex/plugin/scripts/migrate-codex-config.mjs

@@ -6,9 +6,12 @@ import { pathToFileURL } from "node:url";
 
 import { FALLBACK_CATALOG, readModelCatalog } from "./migrate-codex-config/catalog.mjs";
 import { configPaths } from "./migrate-codex-config/config-paths.mjs";
+import { removeStaleContext7PlaceholderMcpServer } from "./migrate-codex-config/context7-placeholder-guard.mjs";
+import { removeUnsupportedRootMultiAgentMode } from "./migrate-codex-config/multi-agent-mode-guard.mjs";
 import { forceDisableMultiAgentV2 } from "./migrate-codex-config/multi-agent-v2-guard.mjs";
 import { ensureCodexReasoningConfig as applyReasoningProfile, readRootSettings } from "./migrate-codex-config/root-settings.mjs";
 import { readState, resolveStatePath, writeState } from "./migrate-codex-config/state.mjs";
+import { ensureSubagentConcurrencyLimit } from "./migrate-codex-config/subagent-limit-guard.mjs";
 
 export { readModelCatalog } from "./migrate-codex-config/catalog.mjs";
 
@@ -22,6 +25,7 @@ export async function migrateCodexConfig({ env = process.env, cwd = process.cwd(
 	const state = await readState(statePath);
 	const paths = await configPaths({ env, cwd });
 	const changed = [];
+	const modeChanged = [];
 	const nextState = { catalogVersion: catalog.version, files: {} };
 	for (const configPath of paths) {
 		const result = await migrateConfigFile(configPath, {
@@ -29,6 +33,7 @@ export async function migrateCodexConfig({ env = process.env, cwd = process.cwd(
 			previousState: state.files?.[configPath],
 		});
 		if (result.changed) changed.push(configPath);
+		if (result.multiAgentModeChanged) modeChanged.push(configPath);
 		nextState.files[configPath] = {
 			catalogVersion: catalog.version,
 			written: result.written,
@@ -36,7 +41,7 @@ export async function migrateCodexConfig({ env = process.env, cwd = process.cwd(
 		};
 	}
 	await writeState(statePath, nextState);
-	return { changed };
+	return { changed, modeChanged };
 }
 
 export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG, previousState } = {}) {
@@ -55,7 +60,19 @@ export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG
 	const multiAgentChanged = afterMultiAgentGuard !== config;
 	if (multiAgentChanged) config = afterMultiAgentGuard;
 
-	const changed = reasoningApplied || multiAgentChanged;
+	const afterMultiAgentModeGuard = removeUnsupportedRootMultiAgentMode(config);
+	const multiAgentModeChanged = afterMultiAgentModeGuard !== config;
+	if (multiAgentModeChanged) config = afterMultiAgentModeGuard;
+
+	const afterContext7PlaceholderGuard = removeStaleContext7PlaceholderMcpServer(config);
+	const context7PlaceholderChanged = afterContext7PlaceholderGuard !== config;
+	if (context7PlaceholderChanged) config = afterContext7PlaceholderGuard;
+
+	const afterSubagentLimit = ensureSubagentConcurrencyLimit(config);
+	const subagentLimitChanged = afterSubagentLimit !== config;
+	if (subagentLimitChanged) config = afterSubagentLimit;
+
+	const changed = reasoningApplied || multiAgentChanged || multiAgentModeChanged || context7PlaceholderChanged || subagentLimitChanged;
 	if (changed) {
 		await mkdir(dirname(configPath), { recursive: true });
 		await writeFile(configPath, `${config.trimEnd()}\n`);
@@ -63,7 +80,7 @@ export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG
 
 	const written = decision.apply ? catalog.current : readRootSettings(config);
 	const managed = decision.apply ? true : decision.managed;
-	return { changed, written, managed };
+	return { changed, written, managed, multiAgentModeChanged };
 }
 
 function shouldApplyCatalog(config, catalog, previousState) {

package/packages/omo-codex/plugin/scripts/sync-skills.mjs

@@ -8,6 +8,8 @@ const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const sharedSkillsRoot = sharedSkillsRootPath();
 const skillsRoot = join(root, "skills");
 const sourceTestFilePattern = /\.test\.ts$/;
+const ignoredSkillSourceDirNames = new Set([".mypy_cache", ".omo", ".pytest_cache", ".ruff_cache", "__pycache__"]);
+const ignoredSkillSourceFileNames = new Set([".gitignore", ".npmignore", "pyrightconfig.json"]);
 const skillSources = [
 	["comment-checker", "components/comment-checker/skills/comment-checker"],
 	["lsp", "components/lsp/skills/lsp"],
@@ -19,6 +21,17 @@ const skillSources = [
 const componentSkillNames = new Set(skillSources.map(([name]) => name));
 const skillDisplayPrefix = "(OmO) ";
 
+function shouldCopySkillSource(source) {
+	const normalized = source.replaceAll("\\", "/");
+	const segments = normalized.split("/");
+	const name = segments.at(-1) ?? "";
+	if (segments.some((segment) => ignoredSkillSourceDirNames.has(segment))) return false;
+	if (ignoredSkillSourceFileNames.has(name)) return false;
+	if (sourceTestFilePattern.test(name) || name.endsWith(".pyc")) return false;
+	const scriptsIndex = segments.lastIndexOf("scripts");
+	return scriptsIndex === -1 || segments[scriptsIndex + 1] !== "tests";
+}
+
 const opencodeOnlyOrchestrationPattern = /\b(?:call_omo_agent|background_output|team_[a-z_]+|task)\s*\(/;
 
 const codexHarnessToolCompatibility = `## Codex Harness Tool Compatibility
@@ -37,12 +50,17 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained \`message\`. Use \`fork_context: false\` to start the child with only the initial prompt (no parent history); use \`fork_context: true\` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's \`message\`. OMO installs these selectable agent roles into \`~/.codex/agents/\`: \`explorer\`, \`librarian\`, \`plan\`, \`momus\`, \`metis\`, \`lazycodex-code-reviewer\`, \`lazycodex-qa-executor\`, and \`lazycodex-gate-reviewer\` - pass the matching name as \`agent_type\` so the child gets that role's model and instructions. If the spawn tool exposes no \`agent_type\` parameter, omit it and describe the role inside \`message\`. If a code block below conflicts with this section, this section wins.
 
+On \`multi_agent_v2\` sessions the same \`agent_type\` applies (the OMO installer exposes it) with \`fork_turns\` instead of \`fork_context\`. If a code block below conflicts with this section, this section wins.
+
+When translating \`load_skills=[...]\`, include the requested skill names in the spawned agent's \`message\`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send \`WORKING: <task> - <current phase>\` before long passes and \`BLOCKED: <reason>\` only when progress stops. A \`multi_agent_v1.wait_agent\` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly \`BLOCKED:\`, or no longer running.
 
 `;
 
 const codexCompatibilityEndMarkers = [
 	"For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.\n\n",
+	"On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.\n\n",
 	"Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
 	"When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
 	"When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
@@ -103,26 +121,26 @@ export function insertCodexCompatibilityGuidance(content) {
 const startWorkOriginalCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
 
 1. Run the plan's final verification commands.
-2. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+2. For PR/branch work, finish the lifecycle from the task-owned worktree: sync \`.omo/\` state back to the main repo, create or update the PR, wait for review/verification gates, merge by default unless explicitly opted out, and remove the worktree only after successful merge or explicit handoff.
 3. Remove or mark the Boulder work as completed.
 4. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, artifacts, and cleanup receipts.`;
 
 const startWorkCodexCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
 
 1. Run the plan's final verification commands.
-2. Complete the **Global Review and Debugging Gate** before any completion claim, PR handoff, or branch handoff:
+2. Complete the **Global Review and Debugging Gate** before any completion claim, PR creation, PR handoff, branch handoff, or merge:
    - Invoke the \`review-work\` skill with the final diff, changed files, user goal, constraints, run command, and verification evidence. All five review lanes must return PASS. A timeout, missing deliverable, ack-only child, \`BLOCKED:\`, or inconclusive lane is a gate failure, not approval.
    - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append the ruled-out or confirmed result to \`.omo/start-work/ledger.jsonl\`.
    - If any review lane or debugging hypothesis fails, invoke the \`debugging\` skill, confirm root cause with runtime evidence, add the minimal failing test or reproduction, fix it, rerun the affected verification, then rerun the Global Review and Debugging Gate.
    - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing \`.omo/start-work/ledger.jsonl\`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
-   - If the work includes creating, updating, or handing off a PR, refresh \`git status\` and the PR/branch state after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
-3. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+   - If the work includes creating, updating, or handing off a PR, refresh \`git status\` and the PR/branch state from the task-owned worktree after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
+3. Finish the PR/branch lifecycle from its task-owned worktree: sync \`.omo/\` state back to the main repo, create or update the PR when requested, wait for CI/review/Cubic gates, merge by default unless explicitly opted out, and remove the worktree only after successful merge or explicit handoff.
 4. Remove or mark the Boulder work as completed.
 5. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, Global Review and Debugging Gate verdict, artifacts, and cleanup receipts.`;
 
-const startWorkOriginalHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+const startWorkOriginalHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No PR/branch implementation, review, or merge in the main worktree; use the task-owned git worktree.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
 
-const startWorkCodexHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No `ORCHESTRATION COMPLETE`, final response, PR creation, or PR handoff before the Global Review and Debugging Gate passes with recorded evidence.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+const startWorkCodexHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No `ORCHESTRATION COMPLETE`, final response, PR creation, PR handoff, or merge before the Global Review and Debugging Gate passes with recorded evidence.\n- No PR/branch implementation or review in the main worktree; create or use a task-owned git worktree first.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
 
 const reviewWorkAnchor = "Launch 5 specialized sub-agents in parallel to review completed implementation work from every angle. All 5 must pass for the review to pass. If even ONE fails, the review fails.\n";
 
@@ -132,7 +150,11 @@ gate, it is blocking. A timeout, missing deliverable, ack-only response,
 explicit \`BLOCKED:\`, or inconclusive lane is not a pass. Treat that lane as
 failed, investigate the underlying uncertainty with the \`debugging\` skill when
 runtime behavior may be wrong, fix with evidence, and rerun the affected lane
-before claiming completion or handing off a PR.
+before claiming completion, creating or handing off a PR, or merging.
+
+When reviewing a PR or branch, collect diff, file contents, and verification
+results from a dedicated review worktree attached to that branch. Never
+checkout, test, or edit the review branch in the main worktree.
 
 Review evidence must be safe to share. Redact or mask secrets and sensitive
 user data before including evidence in logs, PR bodies, or handoffs. Never
@@ -215,7 +237,7 @@ async function syncSkills() {
 	for (const skillName of sharedSkillNames) {
 		if (componentSkillNames.has(skillName)) continue;
 		await cp(join(sharedSkillsRoot, skillName), join(skillsRoot, skillName), {
-			filter: (source) => !sourceTestFilePattern.test(source),
+			filter: shouldCopySkillSource,
 			recursive: true,
 		});
 		await adaptSkillForCodex(skillName);

package/packages/omo-codex/plugin/shared/src/config-loader.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os"
+
 import {
 	loadOmoConfig,
 	type LoadOmoConfigOptions,
@@ -9,20 +11,36 @@ export type CodexOmoConfigOptions = Omit<LoadOmoConfigOptions, "harness">
 
 export type CodexOmoConfig = OmoConfig & {
 	readonly sources: readonly OmoConfigSource[]
+	readonly trustedCodegraphInstallDir?: string
 	readonly warnings: readonly string[]
 }
 
 export function getCodexOmoConfig(options: CodexOmoConfigOptions = {}): CodexOmoConfig {
+	const env = options.env ?? process.env
+	const homeDir = resolveHomeDir(options)
 	const result = loadOmoConfig({
 		...(options.cwd === undefined ? {} : { cwd: options.cwd }),
-		...(options.env === undefined ? {} : { env: options.env }),
-		...(options.homeDir === undefined ? {} : { homeDir: options.homeDir }),
+		env,
+		homeDir,
+		harness: "codex",
+	})
+	const trustedConfig = loadOmoConfig({
+		cwd: homeDir,
+		env,
+		homeDir,
 		harness: "codex",
 	})
+	const trustedCodegraphInstallDir = trustedConfig.config.codegraph?.install_dir
 
 	return {
 		...result.config,
 		sources: result.sources,
+		...(trustedCodegraphInstallDir === undefined ? {} : { trustedCodegraphInstallDir }),
 		warnings: result.warnings,
 	}
 }
+
+function resolveHomeDir(options: CodexOmoConfigOptions): string {
+	const env = options.env ?? process.env
+	return options.homeDir ?? env["HOME"] ?? env["USERPROFILE"] ?? homedir()
+}

package/packages/omo-codex/plugin/shared/test/config-loader.test.ts

@@ -49,6 +49,22 @@ describe("getCodexOmoConfig", () => {
 			install_dir: "/base",
 			telemetry: false,
 		})
+		expect(result.trustedCodegraphInstallDir).toBe("/base")
+	})
+
+	it("#given project SOT sets install_dir #when loading config #then only the effective value changes while trusted install root stays global", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-shared-trusted-home-")
+		const cwd = createTemporaryDirectory("omo-codex-shared-trusted-project-")
+		writeOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: true, install_dir: "/global-codegraph" } }))
+		writeOmoConfig(cwd, JSON.stringify({ codegraph: { install_dir: "/project-codegraph" } }))
+
+		// when
+		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
+
+		// then
+		expect(result.codegraph?.install_dir).toBe("/project-codegraph")
+		expect(result.trustedCodegraphInstallDir).toBe("/global-codegraph")
 	})
 
 	it("#given legacy env override and SOT value #when loading config #then env wins over the SOT", () => {

package/packages/omo-codex/plugin/skills/coding-agent-sessions/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: coding-agent-sessions
+description: "MUST USE when asked to find, read, list, search, inspect, fetch, export, or reconstruct coding-agent sessions across Codex, Claude Code/Desktop, OpenCode, Senpi/pi, OpenClaw, Factory Droid, Amp, Gemini/Kimi/Qwen CLIs, Codebuff, Roo/Kilo/Cline, Kodu, Cursor CLI, Aider, or unknown local agent logs. Covers transcripts, session IDs, rollout JSONL, state SQLite, Claude projects/pre-compact histories, OpenCode messages/parts, child/subagent linkage, cwd/model/time/token filters, archives, and cost clues. Expands fuzzy recall into parallel query lanes and first probes known stores so absent platforms are skipped cheaply. Triggers: coding agent sessions, Codex/Claude/OpenCode/Senpi/pi/OpenClaw/Droid/Amp/Kodu/Cursor/Aider sessions, transcript search, session history, session ID, read transcript, token usage, subagent sessions, what did I do yesterday, did we already do this."
+---
+
+# Coding Agent Sessions
+
+Find local coding-agent sessions across agent products before answering from memory. Prefer the bundled finder for broad cross-platform search, then read the selected session or raw file when you need exact evidence.
+
+## PHASE 0 - PLATFORM ROUTER
+
+1. **IF the user names a platform, load its reference first.**
+
+   | Platform | Read |
+   |---|---|
+   | Codex / OpenAI Codex CLI | `references/codex.md` |
+   | Claude Code / Claude Desktop histories | `references/claude.md` |
+   | Senpi / pi coding-agent logs | `references/senpi.md` |
+   | OpenCode / oh-my-openagent (formerly oh-my-opencode) storage | `references/opencode.md` |
+   | OpenClaw, Droid, Amp, Gemini, Kimi, Qwen, Codebuff, Roo/Kilo/Cline, Kodu, Cursor CLI, Aider, Kiro, Goose, Hermes, Crush, Zed | `references/all-platforms.md` |
+   | Unknown / "any session" / cross-agent search | `references/all-platforms.md` |
+
+2. **Run the broad finder first unless the user gave an exact file path. For fuzzy recall, expand the query first.**
+
+When the user remembers a task vaguely ("that OpenCode bug", "the dashboard PR", "when did we fix X"), derive 3-6 short query lanes before searching: product/tool aliases, repo/package names, exact error text, issue/PR/session IDs, English/Korean phrasing, and likely verbs such as `fix`, `review`, `plan`, `deploy`, or `merge`. Run the lanes together with repeated `--query` so `match_reasons` shows which wording found the hit.
+
+```bash
+python3 scripts/find-agent-sessions.py list --limit 20
+python3 scripts/find-agent-sessions.py find "commit" --from 7d --platform senpi --platform opencode
+python3 scripts/find-agent-sessions.py find "proxy" --platform openclaw --platform droid --platform amp
+python3 scripts/find-agent-sessions.py find --query "deploy" --query "token usage" --workers 64
+python3 scripts/find-agent-sessions.py find --query "opencode bug" --query "fix opencode" --query "OpenCode parent session" --include-subagents --workers 64
+python3 scripts/find-agent-sessions.py read <session-id>
+```
+
+Use `python` instead of `python3` on systems where that is the available executable.
+
+3. **Use explorer-style parallel lanes when one query batch is not enough.**
+
+If scope is broad (multi-month, many repos/platforms, or a vague "what happened with X"), split independent searches by names/errors, repos/cwds, platforms/models, and time windows. Use available subagent/delegation tools for these lanes when they exist; otherwise run the finder calls in parallel. Merge candidates by `id`/`path`, then read the most likely sessions.
+
+4. **Read details from search results before ad hoc digging.** Search results include `detail_hint`; run that `read <session-id> --platform <platform>` command to see the first user prompt, last user prompt, events, and child sessions together.
+
+5. **Verify by opening raw transcripts for claims.** The finder normalizes formats; the raw `path` remains the source of truth.
+
+## Output Contract
+
+The finder prints JSON for stdout and `jq`. Every result includes:
+
+| Field | Meaning |
+|---|---|
+| `platform` | Registered platform key such as `codex`, `claude`, `opencode`, `openclaw`, `droid`, `amp`, `kodu`, `cursor-cli`, `aider`, `roo-code`, `kilo-code`, `kilo-cli`, or `kiro` |
+| `id` | Session ID or stable file-derived ID |
+| `path` | Raw transcript/index file |
+| `cwd` | Working directory when recoverable |
+| `created_at`, `updated_at` | ISO-like timestamps when recoverable |
+| `provider`, `model` | Model metadata when recoverable |
+| `first_user_message` | First user prompt preview (for subagents: task description + delegated prompt) |
+| `last_user_message` | Last user prompt preview when recoverable |
+| `usage` | Token/cost clues when present in the platform log |
+| `parent_id` | Parent session/thread ID when this is a subagent or child session, else `null` |
+| `agent` | Subagent label (Claude `agentType`, Codex `nickname (role)`, OpenCode agent name) |
+| `subagent_count` | Number of child sessions spawned by this session |
+| `detail_hint` | Ready-to-run `read` command for detailed inspection |
+| `match_reasons` | Search-only array explaining which field/content matched each query |
+
+Each `match_reasons` entry includes `query`, `platform`, `field`, and `snippet`, so you can tell which platform matched and what content caused the hit without opening every transcript.
+
+## Filters
+
+`list` and `search` share these filters:
+
+| Filter | Meaning |
+|---|---|
+| `--platform` | Repeatable platform filter; pass one platform per flag |
+| `--root` | Extra root to scan, repeatable |
+| `--from`, `--to` | Date bounds: `YYYY-MM-DD`, `YYYY-MM`, `YYYY`, `today`, `yesterday`, `7d` |
+| `--cwd` | Working-directory substring |
+| `--model` | Model substring |
+| `--limit` | Maximum results |
+| `--query` | Repeatable search query; multiple queries return per-query groups plus a de-duplicated merged result list |
+| `--workers` | Parallel worker count for platform scans, transcript parsing, OpenCode message joins, and multi-query matching |
+| `--include-subagents` | Include subagent/child sessions as standalone `list`/`search` results (hidden by default) |
+
+When `--platform` is omitted, the finder searches every registered platform in parallel. Each optional platform first probes fixed, known transcript roots and returns immediately when the product has no local store, so broad default searches stay cheap. Use repeatable flags such as `--platform openclaw --platform droid` only when narrowing. Comma-separated platform values are intentionally unsupported.
+
+For OpenCode, the finder uses `opencode db path` plus direct SQLite queries first, then `opencode session list --format json` as a fallback. It avoids heavy `messages/` or `parts/` scans during normal list/search, and only falls back to file joins when the OpenCode DB/CLI is unavailable or explicit `--root` values request a nonstandard store.
+
+Usage-only sources such as Copilot OTEL, Mux, Antigravity tokscale cache rows, Synthetic provider retagging, and Cursor IDE usage CSV are excluded from default transcript search because they do not reconstruct user prompts.
+
+## Subagent / Child Sessions
+
+`list` and `find`/`search` return main sessions only by default, each annotated with `subagent_count`. `read <main-session-id>` (alias: `get`) always returns a `prompts` object and a `subagents` array containing every child session (id, agent label, parent_id, prompt preview, raw path), so opening a main session reveals its whole delegation tree. `read <child-id>` works too and returns that child's own events.
+
+| Platform | Where children live | Linkage |
+|---|---|---|
+| Claude Code | `projects/<proj>/<session-id>/subagents/agent-*.jsonl` (Task tool) and `.../subagents/workflows/wf_*/agent-*.jsonl` (Workflow) | Directory name = parent session ID; `agent-*.meta.json` holds `agentType` + task description |
+| Codex | Regular threads in `state_*.sqlite` + own rollout JSONL | `thread_spawn_edges` table and `threads.source` / rollout `session_meta.payload.source.subagent.thread_spawn` |
+| OpenCode | Regular sessions in `opencode.db` / `storage/session/` | `session.parent_id` column / `parentID` field; `agent` column names the subagent |
+
+When the user asks whether some specific work was ever done, search with `--include-subagents` — delegated work often lives only in child transcripts, not in the main session. Workflow `journal.jsonl` files are orchestration logs, not sessions.
+
+## Codex Notes
+
+For Codex sessions, use the same broad finder. It reads `state_*.sqlite`, rollout JSONL, and archived rollout files:
+
+```bash
+python3 scripts/find-agent-sessions.py list --platform codex --from 7d
+python3 scripts/find-agent-sessions.py find "deploy" --platform codex
+python3 scripts/find-agent-sessions.py read <session-id> --platform codex
+```
+
+Use `references/codex.md` for Codex storage details.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| Missing Codex sessions | Set `CODEX_HOME` or pass `--root /path/to/.codex`. |
+| Missing OpenCode sessions | Pass the data dir that contains `messages/` and `parts/`, often `~/.opencode` or `~/.local/share/opencode`. |
+| Missing Claude sessions | Search `~/.claude/projects`, `~/.claude/transcripts`, and `~/.claude/pre-compact-session-histories`; use `--root` for nonstandard config dirs. |
+| Missing optional platform sessions | Check `references/all-platforms.md` for the exact local store. For project-local tools such as Aider, pass `--root /path/to/workspace` if the repo is outside the bounded default roots. |
+| Date filter misses local sessions | Timestamps are compared as UTC instants when parseable; otherwise file mtime is used. |
+| Search is slow | Narrow with repeated `--platform` flags or date/cwd filters. Optional stores are probed before parsing; avoid passing your whole home as `--root` unless you really want every bounded project-local scan. |
+
+## Activation
+
+Use this skill for any request to find, read, or inspect a local coding-agent session, regardless of product name — including memory-recall questions ("what did I work on a few days ago", "did we already migrate X", "when did I fix Y"). If the user only says "that session where we did X", do not rely on one literal query: expand to multiple discriminative terms first, add `--include-subagents` when the work may have been delegated, then narrow by `--platform`, `cwd`, `model`, and time (`--from 7d` for "a few days ago"). Prefer the `detail_hint` from the chosen search result for the next read step. If the first query batch is still ambiguous, use explorer-style lanes by keyword, repo/cwd, platform/model, and time window before summarizing.

package/packages/omo-codex/plugin/skills/coding-agent-sessions/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "(OmO) coding-agent-sessions"
+  short_description: "Find local coding-agent session history"
+  default_prompt: "Use $coding-agent-sessions to find the coding-agent session where I worked on a recent bug."

package/packages/omo-codex/plugin/skills/coding-agent-sessions/references/all-platforms.md

@@ -0,0 +1,71 @@
+# Cross-Platform Session Search
+
+## Default locations
+
+Search these first, then add user-supplied roots with `--root`:
+
+Registered platform keys: `codex`, `claude`, `senpi`, `opencode`, `openclaw`, `droid`, `amp`, `gemini`, `kimi`, `qwen`, `codebuff`, `roo-code`, `kilo-code`, `cline`, `kodu`, `cursor-cli`, `aider`, `kilo-cli`, `hermes`, `goose`, `crush`, `zed`, `kiro`.
+
+| Platform | Unix/macOS | Windows |
+|---|---|---|
+| Codex | `$CODEX_HOME`, `~/.codex` | `%CODEX_HOME%`, `%USERPROFILE%\.codex` |
+| Claude | `~/.claude` | `%USERPROFILE%\.claude`, `%APPDATA%\Claude` |
+| Senpi / pi | `~/.senpi/agent`, `~/.pi/agent` | `%USERPROFILE%\.senpi\agent`, `%USERPROFILE%\.pi\agent` |
+| OpenCode | `$OPENCODE_HOME`, `~/.opencode`, `~/.local/share/opencode` | `%OPENCODE_HOME%`, `%APPDATA%\opencode`, `%USERPROFILE%\.opencode` |
+| OpenClaw | `~/.openclaw/agents/*/sessions`, `~/.openclaw/session-backups` | pass `--root` |
+| Factory Droid | `~/.factory/sessions/*/*.jsonl` | pass `--root` |
+| Amp | `~/.local/share/amp/threads/T-*.json` | pass `--root` |
+| Gemini / Kimi / Qwen | `~/.gemini/tmp/*/chats`, `~/.kimi/sessions/*/*/wire.jsonl`, `~/.qwen/projects/*/chats` | pass `--root` |
+| Codebuff | `~/.config/manicode*/projects/*/chats/*/chat-messages.json` | pass `--root` |
+| Roo Code (`roo-code`) / Kilo Code (`kilo-code`) / Cline | VS Code `globalStorage/<extension>/tasks/*` | VS Code `globalStorage\<extension>\tasks\*` |
+| Kodu | VS Code `globalStorage/kodu-ai.claude-dev-experimental/db/Azad.db` | VS Code `globalStorage\kodu-ai.claude-dev-experimental\db\Azad.db` |
+| Cursor CLI | `~/.cursor/chats/*/*/store.db`, `~/.cursor/prompt_history.json` | `%USERPROFILE%\.cursor\chats` |
+| Aider | bounded project roots containing `.aider.chat.history.md`; use `--root` for other repos | pass `--root` |
+| Kilo CLI (`kilo-cli`) / Hermes / Goose / Crush / Zed | Known SQLite roots are probed cheaply; unsupported schemas return empty | pass `--root` |
+| Kiro | `~/.kiro/sessions/cli/*.json` plus paired `*.jsonl` prompt events | pass `--root` |
+
+## Excluded usage-only sources
+
+Do not add these as default transcript platforms without a separate prompt-reconstruction source:
+
+| Source | Why excluded |
+|---|---|
+| Copilot OTEL | Token/telemetry rows, not prompts |
+| Mux | `session-usage.json` usage buckets only |
+| Antigravity | tokscale cache/RPC data, not raw chat transcripts |
+| Synthetic | Provider retagging over another platform, not an independent session store |
+| Cursor IDE usage CSV | Usage accounting; use `cursor-cli` for local CLI chat stores |
+
+## Workflow
+
+1. Run `scripts/find-agent-sessions.py search <query>` across all platforms, or repeat `--query` for several searches in one scan. Add `--include-subagents` when the work may have run inside a delegated agent — child transcripts are excluded from `list`/`search` by default.
+2. If results are noisy, add `--cwd`, `--model`, `--from`, or repeated `--platform` filters.
+3. Run `get <session-id>` on likely hits. The result includes a `subagents` array: every child session (Claude Task/workflow agents, Codex thread spawns, OpenCode child sessions) with its own id, `agent` label, and raw path — follow up with `get <child-id>` for a child's events.
+4. Open raw `path` files for exact quotes, tool calls, and evidence.
+
+## Subagent linkage cheat sheet
+
+| Platform | Child identity | Parent linkage | Agent label |
+|---|---|---|---|
+| Claude | `projects/<proj>/<sid>/subagents/**/agent-<agentId>.jsonl` | directory `<sid>` | `agent-*.meta.json` `agentType` |
+| Codex | thread row + own rollout JSONL | `thread_spawn_edges` / `source.subagent.thread_spawn.parent_thread_id` | `agent_nickname (agent_role)` |
+| OpenCode | `session` table row / `storage/session/**.json` | `parent_id` column / `parentID` field | `agent` column |
+
+## Parallelism
+
+The finder scans selected platforms concurrently, parses transcript files concurrently, joins OpenCode message/part files concurrently, and evaluates repeated `--query` values concurrently. Increase `--workers` for large local stores:
+
+```bash
+python3 scripts/find-agent-sessions.py search --query "commit" --query "deploy" --workers 64
+python3 scripts/find-agent-sessions.py search --query "commit" --platform senpi --platform opencode --workers 64
+```
+
+Omit `--platform` for the full multi-platform search. Add repeated platform flags such as `--platform openclaw --platform droid` only when the user already knows the likely stores. Comma-separated platform values are intentionally unsupported.
+
+The default scan is intentionally probe-first: optional platforms check for exact store roots before globbing or opening files. This avoids expensive home-wide searches while still making newly installed local agents visible without changing the command.
+
+OpenCode is optimized differently from raw JSONL stores: it calls `opencode db path`, reads the SQLite session table directly, falls back to `opencode session list --format json`, and only scans `messages/` / `parts/` when the DB/CLI is unavailable or explicit `--root` values force a file-store lookup.
+
+## Evidence rule
+
+Never answer "what happened in a session" from the normalized preview alone. Use the preview to locate candidates, then inspect the raw transcript or `get` output.

package/packages/omo-codex/plugin/skills/coding-agent-sessions/references/claude.md

@@ -0,0 +1,32 @@
+# Claude Session Stores
+
+Observed Claude formats:
+
+- `~/.claude/projects/<encoded-cwd>/*.jsonl`: Claude Code project sessions (main sessions; filename = session ID).
+- `~/.claude/transcripts/ses_*.jsonl`: compact transcript exports with simple `type`, `timestamp`, `content`, and tool fields.
+- `~/.claude/pre-compact-session-histories/*.jsonl`: pre-compaction histories with `sessionId`, `cwd`, `message`, `uuid`, `parentUuid`, and tool result metadata.
+
+For project files, `sessionId`, `cwd`, `version`, `gitBranch`, and `message.model` are usually embedded in each line. For transcript exports, the filename may be the only stable session ID.
+
+When reconstructing a Claude session, preserve the event order from the JSONL file and distinguish assistant text, thinking, tool use, tool result, and progress events.
+
+## Subagent transcripts (per-session directory)
+
+Each main session may own a sibling directory named after the session ID:
+
+```
+projects/<encoded-cwd>/<session-id>/
+├── subagents/
+│   ├── agent-<agentId>.jsonl        # Task-tool subagent transcript
+│   ├── agent-<agentId>.meta.json    # {"agentType", "description", "toolUseId"}
+│   └── workflows/wf_<id>/
+│       ├── agent-<agentId>.jsonl    # Workflow-spawned agent transcripts
+│       ├── agent-<agentId>.meta.json
+│       └── journal.jsonl            # workflow orchestration journal — NOT a session
+├── workflows/wf_<id>.json           # workflow run metadata
+└── tool-results/*.txt               # persisted oversized tool outputs
+```
+
+Subagent JSONL lines look like main-session lines but carry `isSidechain: true`, `agentId`, `promptId`, and `sessionId` pointing at the PARENT session — never treat a subagent file's `sessionId` as its own identity; use the `agentId` (also in the filename) and take the parent from the directory path. The first line's user message is the delegated task prompt; `agent-*.meta.json` gives the human-readable `description` and `agentType`.
+
+The finder models these as `platform: claude` sessions with `id = <agentId>`, `parent_id = <session-id>`, `agent = agentType`. `get <main-session-id>` lists them under `subagents`; `get <agentId>` returns the child transcript events. Older Claude Code versions inlined sidechains in the main JSONL (`isSidechain: true` lines) instead of separate files.

package/packages/omo-codex/plugin/skills/coding-agent-sessions/references/codex.md

@@ -0,0 +1,30 @@
+# Codex Sessions
+
+Codex has two useful surfaces:
+
+- `$CODEX_HOME/state_*.sqlite` stores thread metadata.
+- `$CODEX_HOME/sessions/**/rollout-*.jsonl` and archived rollout files store event transcripts.
+
+Use the broad finder for Codex discovery:
+
+```bash
+python3 scripts/find-agent-sessions.py list --platform codex --limit 10
+python3 scripts/find-agent-sessions.py search "deploy" --platform codex
+python3 scripts/find-agent-sessions.py search --query "deploy" --query "token usage" --platform codex --workers 32
+python3 scripts/find-agent-sessions.py get <session-id> --platform codex
+```
+
+Important filters: `--from`, `--to`, `--cwd`, `--model`, `--root`, `--limit`, and `--include-subagents`.
+
+## Spawned (subagent) threads
+
+Codex subagent threads are ordinary rows in `threads` with their own rollout files. Two linkage sources:
+
+- `thread_spawn_edges(parent_thread_id, child_thread_id, status)` — authoritative parent→child table.
+- `threads.source` — `cli` / `exec` / `vscode` for user-started threads, or JSON for spawned ones:
+  - `{"subagent": "review"}`, `{"subagent": "memory_consolidation"}` — built-in side threads.
+  - `{"subagent": {"thread_spawn": {"parent_thread_id": "...", "depth": 1, "agent_nickname": "Tesla", "agent_role": "explorer"}}}` — collab/multi-agent spawns (depth can exceed 1: children spawn grandchildren).
+
+`threads` also carries `agent_nickname`, `agent_role`, `model`, `first_user_message`, `tokens_used`. Without the SQLite DB, the same linkage is in each rollout file's first line: `type: "session_meta"` whose `payload` has `id`, `cwd`, `model_provider`, `forked_from_id`, and the same `source.subagent.thread_spawn` object.
+
+The finder maps these to `parent_id` and `agent = "nickname (role)"`; `get <parent-thread-id>` lists children under `subagents`, and `get <child-thread-id>` returns the child's rollout events.

package/packages/omo-codex/plugin/skills/coding-agent-sessions/references/opencode.md

@@ -0,0 +1,43 @@
+# OpenCode Session Stores
+
+## Fast path
+
+Prefer the OpenCode CLI index before touching session files:
+
+```bash
+opencode db path
+sqlite3 "$(opencode db path)" 'select id, title, directory, time_updated from session order by time_updated desc limit 2000'
+opencode session list --format json --max-count 100
+```
+
+Use direct SQLite via `opencode db path` for ordinary `list` and title/session-ID/cwd searches. It queries OpenCode's own indexed session database and avoids expensive scans across `messages/` and `parts/`. Use `opencode session list --format json` as the next fallback when direct DB access is unavailable.
+
+Only fall back to file joins when `opencode` is not installed, the command fails, or the user passes an explicit `--root` for a nonstandard store.
+
+## Subagent (child) sessions
+
+Child sessions spawned by the task tool / subagents are ordinary rows in the `session` table:
+
+- `session.parent_id` — parent session ID (`NULL` for main sessions). Tens of thousands of child rows are normal.
+- `session.agent` — subagent name (`explore`, `plan`, `librarian`, `Sisyphus-Junior`, ...).
+- Child titles often end with the convention `"... (@<agent> subagent)"`.
+
+```bash
+sqlite3 "$(opencode db path)" "select id, agent, title from session where parent_id='<parent-id>' order by time_created"
+```
+
+In the file store, the same linkage is the `parentID` field of `storage/session/<project-hash>/ses_*.json` info files. The finder surfaces children with `parent_id` + `agent` set; `get <parent-id>` lists them under `subagents`.
+
+## File fallback
+
+Observed OpenCode layouts vary by version:
+
+- `~/.opencode/messages/ses_*/*.json`: message metadata.
+- `~/.opencode/parts/msg_*/*.json`: message parts, including text and synthetic compaction context.
+- `~/.opencode/sessions/**`: newer session indexes or compatibility storage.
+- `~/.local/share/opencode/storage/session/<project-hash>/ses_*.json`: session info files (`id`, `parentID`, `title`, `directory`, `time.created/updated`) — sibling `storage/message/` and `storage/part/` (singular) dirs hold content.
+- `~/.local/share/opencode/storage/**`: older or Linux/XDG storage, often with session/message JSON or SQLite-backed data.
+
+Message metadata usually contains `sessionID`, `role`, `time.created`, `agent`, `model.providerID`, `model.modelID`, and `path.cwd`. Text content may live in `parts/<message-id>/*.json`.
+
+When answering from OpenCode, join messages to parts by `messageID` and order by `time.created` or part time. Compaction injections are useful for continuity but should be labeled as synthetic.

package/packages/omo-codex/plugin/skills/coding-agent-sessions/references/senpi.md

@@ -0,0 +1,17 @@
+# Senpi / pi Coding-Agent Sessions
+
+Observed Senpi layout:
+
+- `~/.senpi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`
+- `~/.senpi/agent/settings.json`, `models.json`, and `auth.json` provide environment context.
+- `~/.pi/agent/sessions/**` can use the same family of JSONL formats.
+
+Common event types:
+
+- `session`: includes `id`, `timestamp`, and `cwd`.
+- `model_change`: includes `provider` and `modelId`.
+- `thinking_level_change`: includes effort metadata.
+- `message`: wraps provider-native messages, tool calls, usage, and costs.
+- `custom` with `customType: senpi.todo-state`: stores todo state.
+
+Prefer Senpi usage fields when present: `usage.input`, `usage.output`, `usage.cacheRead`, `usage.cacheWrite`, `usage.totalTokens`, and `usage.cost.total`.

package/packages/omo-codex/plugin/skills/coding-agent-sessions/scripts/agent_sessions/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations