oh-my-opencode 4.13.0 → 4.14.0

package/packages/omo-codex/scripts/install-local-git-bash-preflight.test.mjs

@@ -21,7 +21,7 @@ async function withBundledLspRuntimeForTest(run) {
 	return run();
 }
 
-test("#given Windows without Git Bash and auto install skip env #when installing local marketplace #then rejects before marketplace or config mutation", async () => {
+test("#given Windows without Git Bash #when installing local marketplace #then rejects before marketplace or config mutation", async () => {
 	const repoRoot = await mkdtemp(join(tmpdir(), "omo-codex-script-git-bash-missing-repo-"));
 	const codexHome = await mkdtemp(join(tmpdir(), "omo-codex-script-git-bash-missing-home-"));
 	const commands = [];
@@ -31,7 +31,6 @@ test("#given Windows without Git Bash and auto install skip env #when installing
 			repoRoot,
 			codexHome,
 			platform: "win32",
-			env: { OMO_CODEX_SKIP_GIT_BASH_AUTO_INSTALL: "1" },
 			gitBashResolver: () => ({
 				found: false,
 				checkedPaths: [windowsGitBashPath],
@@ -53,29 +52,39 @@ test("#given Windows without Git Bash and auto install skip env #when installing
 	await assert.rejects(stat(join(codexHome, "config.toml")), /ENOENT/);
 });
 
-test("#given Windows without Git Bash #when winget succeeds and resolver recovers #then install continues", async () => {
+test("#given Windows without Git Bash #when installing local marketplace #then winget is not run and install stops with guidance", async () => {
 	const runCalls = [];
-	const resolutions = [
-		{ found: false, checkedPaths: [windowsGitBashPath], installHint: "install hint before winget" },
-		{ found: true, path: windowsGitBashPath, source: "program-files" },
-	];
+	const missingResolution = {
+		found: false,
+		checkedPaths: [windowsGitBashPath],
+		installHint: [
+			"Git Bash is required.",
+			"winget install --id Git.Git -e --source winget",
+			"OMO_CODEX_GIT_BASH_PATH=C:\\path\\to\\bash.exe",
+			"rerun `npx lazycodex-ai install`",
+		].join("\n"),
+	};
 	let resolveCallCount = 0;
+	const codexHome = await mkdtemp(join(tmpdir(), "omo-codex-script-git-bash-no-auto-home-"));
 
-	const result = await withBundledLspRuntimeForTest(async () => installMarketplaceLocally({
+	await assert.rejects(withBundledLspRuntimeForTest(async () => installMarketplaceLocally({
 		repoRoot: process.cwd(),
-		codexHome: await mkdtemp(join(tmpdir(), "omo-codex-script-git-bash-auto-home-")),
-		binDir: await mkdtemp(join(tmpdir(), "omo-codex-script-git-bash-auto-bin-")),
+		codexHome,
+		binDir: await mkdtemp(join(tmpdir(), "omo-codex-script-git-bash-no-auto-bin-")),
 		platform: "win32",
-		gitBashResolver: () => resolutions[resolveCallCount++] ?? resolutions[resolutions.length - 1],
+		gitBashResolver: () => {
+			resolveCallCount += 1;
+			return missingResolution;
+		},
 		runCommand: async (command, args, options) => {
 			runCalls.push([command, ...args, options.cwd].join(" "));
 		},
 		log: () => {},
-	}));
+	})), /winget install --id Git\.Git -e --source winget/);
 
-	assert.equal(resolveCallCount, 2);
-	assert.match(runCalls.join("\n"), /^winget install --id Git\.Git -e --source winget /m);
-	assert.equal(result.gitBashPath, windowsGitBashPath);
+	assert.equal(resolveCallCount, 1);
+	assert.deepEqual(runCalls, []);
+	await assert.rejects(stat(join(codexHome, "config.toml")), /ENOENT/);
 });
 
 test("#given non-Windows install #when running installer #then winget is never called", async () => {

package/packages/omo-codex/scripts/install-local.test.mjs

@@ -161,6 +161,7 @@ test("#given plugin hooks #when installing #then records trusted hook hashes", a
 	const pluginRoot = join(codexPackageRoot, "plugin");
 	await writePluginAt(pluginRoot, "alpha", "1.2.3");
 	await writeFile(join(pluginRoot, "dist", "cli.js"), "console.log('plugin cli')\n");
+	await writeFile(join(pluginRoot, "dist", "cli.ps1"), "Write-Output 'plugin cli'\n");
 	await writeJson(join(pluginRoot, "hooks", "hooks.json"), {
 		hooks: {
 			UserPromptSubmit: [
@@ -169,6 +170,7 @@ test("#given plugin hooks #when installing #then records trusted hook hashes", a
 						{
 							type: "command",
 							command: "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit",
+							commandWindows: 'powershell -File "${PLUGIN_ROOT}\\dist\\cli.ps1" hook user-prompt-submit',
 							timeout: 10,
 							statusMessage: "checking alpha",
 						},
@@ -181,13 +183,15 @@ test("#given plugin hooks #when installing #then records trusted hook hashes", a
 	await installMarketplaceLocally({
 		repoRoot,
 		codexHome,
+		platform: "win32",
+		gitBashResolver: () => ({ found: true, path: "C:\\Program Files\\Git\\bin\\bash.exe", source: "program-files" }),
 		runCommand: async () => {},
 		log: () => {},
 	});
 
 	const config = await readFile(join(codexHome, "config.toml"), "utf8");
 	assert.match(config, /\[hooks\.state\."alpha@debug-marketplace:hooks\/hooks\.json:user_prompt_submit:0:0"\]/);
-	assert.match(config, /trusted_hash = "sha256:[a-f0-9]{64}"/);
+	assert.match(config, /trusted_hash = "sha256:605b27c7b1f93c02aa2f8052fd9df870a221c3dc432795c48b223fe48afcebc0"/);
 });
 
 test("#given bad plugin source path #when installing #then rejects traversal", async () => {

package/packages/omo-codex/scripts/install-mcp-context7-runtime.test.mjs

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+
+import { installCachedPlugin } from "./install-dist/install-local.mjs";
+import { makeTempDir, writeJson } from "./install-test-fixtures.mjs";
+
+async function installContext7RuntimeFixture(context7) {
+	const repoRoot = await makeTempDir();
+	const codexHome = await makeTempDir();
+	const sourceRoot = join(repoRoot, "packages", "omo-codex", "plugin");
+
+	await writeJson(join(sourceRoot, "package.json"), { name: "@example/omo", version: "0.1.0" });
+	await writeJson(join(sourceRoot, ".mcp.json"), { mcpServers: { context7 } });
+
+	const result = await installCachedPlugin({
+		codexHome,
+		marketplaceName: "sisyphuslabs",
+		name: "omo",
+		runCommand: async () => {},
+		sourcePath: sourceRoot,
+		version: "0.1.0",
+	});
+
+	const rawManifest = await readFile(join(result.path, ".mcp.json"), "utf8");
+	return { cachedMcp: JSON.parse(rawManifest), rawManifest };
+}
+
+test("#given Context7 placeholder auth in generated installer path #when installing cached plugin #then placeholder auth is stripped", async () => {
+	const { cachedMcp, rawManifest } = await installContext7RuntimeFixture({
+		command: "bunx",
+		args: ["--bun", "-y", "@upstash/context7-mcp", "--api-key", "your api key"],
+		cwd: ".",
+		env: { CONTEXT7_API_KEY: "<YOUR_API_KEY>", SAFE_FLAG: "1" },
+	});
+
+	assert.deepEqual(cachedMcp.mcpServers.context7.args, ["--bun", "-y", "@upstash/context7-mcp"]);
+	assert.deepEqual(cachedMcp.mcpServers.context7.env, { SAFE_FLAG: "1" });
+	assert.equal(Object.hasOwn(cachedMcp.mcpServers.context7, "cwd"), false);
+	assert.doesNotMatch(rawManifest, /your api key/i);
+	assert.doesNotMatch(rawManifest, /YOUR_API_KEY/);
+	assert.doesNotMatch(rawManifest, /--api-key/);
+});
+
+test("#given real Context7 auth in generated installer path #when installing cached plugin #then user auth is preserved", async () => {
+	const { cachedMcp } = await installContext7RuntimeFixture({
+		command: "bunx",
+		args: ["--bun", "-y", "@upstash/context7-mcp", "--api-key", "ctx7sk_real_user_key"],
+		cwd: ".",
+		env: { CONTEXT7_API_KEY: "ctx7sk_real_env_key" },
+	});
+
+	assert.deepEqual(cachedMcp.mcpServers.context7.args, [
+		"--bun",
+		"-y",
+		"@upstash/context7-mcp",
+		"--api-key",
+		"ctx7sk_real_user_key",
+	]);
+	assert.deepEqual(cachedMcp.mcpServers.context7.env, { CONTEXT7_API_KEY: "ctx7sk_real_env_key" });
+	assert.equal(Object.hasOwn(cachedMcp.mcpServers.context7, "cwd"), false);
+});
+
+test("#given env-only Context7 placeholder auth in generated installer path #when installing cached plugin #then placeholder env is stripped", async () => {
+	const { cachedMcp, rawManifest } = await installContext7RuntimeFixture({
+		url: "https://mcp.context7.com/mcp",
+		env: { CONTEXT7_API_KEY: "YOUR_API_KEY", SAFE_FLAG: "1" },
+	});
+
+	assert.deepEqual(cachedMcp.mcpServers.context7.env, { SAFE_FLAG: "1" });
+	assert.doesNotMatch(rawManifest, /YOUR_API_KEY/);
+});
+
+test("#given dangling Context7 api-key flag in generated installer path #when installing cached plugin #then blank auth flag is stripped", async () => {
+	const { cachedMcp, rawManifest } = await installContext7RuntimeFixture({
+		command: "bunx",
+		args: ["--bun", "-y", "@upstash/context7-mcp", "--api-key"],
+	});
+
+	assert.deepEqual(cachedMcp.mcpServers.context7.args, ["--bun", "-y", "@upstash/context7-mcp"]);
+	assert.equal(Object.hasOwn(cachedMcp.mcpServers.context7, "env"), false);
+	assert.doesNotMatch(rawManifest, /--api-key/);
+});

package/packages/shared-skills/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/shared-skills/skills/coding-agent-sessions/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "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/shared-skills/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/shared-skills/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/shared-skills/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/shared-skills/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/shared-skills/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/shared-skills/skills/coding-agent-sessions/scripts/agent_sessions/__init__.py

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

package/packages/shared-skills/skills/coding-agent-sessions/scripts/agent_sessions/claude.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+from .jsonio import as_map, iter_jsonl, read_json, text
+from .timeparse import file_time
+from .transcript import content_text, env_path, existing, jsonl_parallel, recent
+from .types import Session
+
+
+def scan_claude(extra_roots: tuple[Path, ...], workers: int) -> list[Session]:
+    appdata = env_path("APPDATA")
+    roots = existing([Path.home() / ".claude", *(path / "Claude" for path in (appdata,) if path is not None), *extra_roots])
+    mains: list[Path] = []
+    subagents: list[Path] = []
+    for root in roots:
+        mains.extend((root / "transcripts").glob("*.jsonl"))
+        mains.extend((root / "projects").glob("*/*.jsonl"))
+        mains.extend((root / "pre-compact-session-histories").glob("*.jsonl"))
+        subagents.extend((root / "projects").glob("*/*/subagents/**/agent-*.jsonl"))
+    sessions = jsonl_parallel(recent(mains), workers, "claude", lambda path: path.stem)
+    sessions.extend(_subagent_parallel(recent(subagents), workers))
+    return sessions
+
+
+def _subagent_parallel(paths: list[Path], workers: int) -> list[Session]:
+    if not paths:
+        return []
+    sessions: list[Session] = []
+    with ThreadPoolExecutor(max_workers=min(workers, max(len(paths), 1))) as pool:
+        futures = [pool.submit(_subagent_session, path) for path in paths]
+        for future in as_completed(futures):
+            session = future.result()
+            if session is not None:
+                sessions.append(session)
+    return sessions
+
+
+def _subagent_session(path: Path) -> Session | None:
+    parts = path.parts
+    if "subagents" not in parts:
+        return None
+    parent_sid = parts[parts.index("subagents") - 1]
+    meta = as_map(read_json(path.with_name(path.stem + ".meta.json"))) or {}
+    first = next(iter_jsonl(path), None) or {}
+    message = as_map(first.get("message")) or {}
+    description = text(meta.get("description")) or ""
+    task = content_text(message.get("content"))
+    prompt = "\n".join(part for part in (description, task) if part)
+    created = text(first.get("timestamp")) or file_time(path)
+    return Session(
+        "claude",
+        path.stem.removeprefix("agent-"),
+        str(path),
+        text(first.get("cwd")),
+        created,
+        file_time(path) or created,
+        None,
+        None,
+        prompt,
+        {},
+        parent_sid,
+        text(meta.get("agentType")),
+        prompt,
+    )