oh-my-opencode 5.0.0-beta.8 → 5.0.0-beta.81

package/packages/omo-codex/scripts/install-generated-bundle.test.mjs

@@ -75,7 +75,7 @@ test("#given no root model #when generated bundle updates config #then it does n
 	// then
 	const config = await readFile(configPath, "utf8");
 	assert.doesNotMatch(config, /^\s*max_threads\s*=/m);
-	assert.match(config, /max_concurrent_threads_per_session = 16/);
+	assert.doesNotMatch(config, /max_concurrent_threads_per_session\s*=/);
 });
 
 test("#given an inline-commented V2 thread cap #when generated bundle updates config twice #then preserves the line and ordering byte-for-byte", async () => {
@@ -150,8 +150,7 @@ test("#given explicit v1 model_catalog_json and stale models_cache v2 #when gene
 	const config = await readFile(configPath, "utf8");
 	const v2Section = sectionText(config, "[features.multi_agent_v2]");
 	assert.match(v2Section, /^enabled = false$/m);
-	assert.match(config, /\[agents\][\s\S]*?max_threads = 1000/);
-	assert.doesNotMatch(config, /max_threads = 16/);
+	assert.match(config, /^\s*max_threads\s*=\s*16$/m);
 });
 
 test("#given explicit v2 model_catalog_json and stale models_cache v1 #when generated bundle updates config #then explicit catalog clears managed disable and cap", async () => {
@@ -190,7 +189,7 @@ test("#given explicit v2 model_catalog_json and stale models_cache v1 #when gene
 	const v2Section = sectionText(config, "[features.multi_agent_v2]");
 	assert.doesNotMatch(v2Section, /^enabled\s*=/m);
 	assert.doesNotMatch(config, /^\s*max_threads\s*=/m);
-	assert.match(v2Section, /max_concurrent_threads_per_session = 16/);
+	assert.doesNotMatch(v2Section, /max_concurrent_threads_per_session\s*=/);
 });
 
 function sectionText(config, header) {

package/packages/omo-codex/scripts/install-git-bash-mcp-env.test.mjs

@@ -62,30 +62,6 @@ test("#given a non-Windows install #when stamping #then the manifest stays byte-
 	assert.equal(await readFile(join(pluginRoot, ".mcp.json"), "utf8"), MANIFEST);
 });
 
-test("#given a package-relative CodeGraph MCP path #when stamping on non-Windows #then codegraph server arg becomes absolute", async (t) => {
-	const pluginRoot = await mkdtemp(join(tmpdir(), "git-bash-mcp-env-"));
-	t.after(() => rm(pluginRoot, { recursive: true, force: true }));
-	await writeFile(
-		join(pluginRoot, ".mcp.json"),
-		`${JSON.stringify(
-			{
-				mcpServers: {
-					codegraph: { args: ["components/codegraph/dist/serve.js"], command: "node" },
-					git_bash: { command: "node", args: ["../../git-bash-mcp/dist/cli.js", "mcp"] },
-				},
-			},
-			null,
-			"\t",
-		)}\n`,
-	);
-
-	const changed = await stampGitBashMcpEnv({ pluginRoot, env: {}, platform: "darwin" });
-
-	assert.equal(changed, true);
-	const parsed = JSON.parse(await readFile(join(pluginRoot, ".mcp.json"), "utf8"));
-	assert.deepEqual(parsed.mcpServers.codegraph.args, [join(pluginRoot, "components", "codegraph", "dist", "serve.js")]);
-});
-
 test("#given the override already stamped #when stamping again #then nothing changes", async (t) => {
 	const pluginRoot = await createPluginRoot();
 	t.after(() => rm(pluginRoot, { recursive: true, force: true }));
@@ -102,7 +78,7 @@ test("#given the override already stamped #when stamping again #then nothing cha
 test("#given a manifest without a git_bash server #when stamping #then the manifest stays byte-identical", async (t) => {
 	const pluginRoot = await mkdtemp(join(tmpdir(), "git-bash-mcp-env-"));
 	t.after(() => rm(pluginRoot, { recursive: true, force: true }));
-	const manifest = `${JSON.stringify({ mcpServers: { codegraph: { command: "node" } } }, null, "\t")}\n`;
+	const manifest = `${JSON.stringify({ mcpServers: { lsp: { command: "node" } } }, null, "\t")}\n`;
 	await writeFile(join(pluginRoot, ".mcp.json"), manifest);
 
 	const changed = await stampGitBashMcpEnv({

package/packages/omo-codex/scripts/install-lazycodex-version-stamp.test.mjs

@@ -77,8 +77,13 @@ test("#given sisyphuslabs lazycodex install #when installing locally #then stamp
 	assert.equal(manifest.version, "4.7.6");
 	assert.equal(packageJson.version, "4.7.6");
 	assert.equal(componentPackageJson.version, "4.7.6");
-	assert.equal(hooks.hooks.PostToolUse[0].hooks[0].statusMessage, "(OmO 4.7.6) Checking Comments");
-	assert.equal(componentHooks.hooks.UserPromptSubmit[0].hooks[0].statusMessage, "(OmO 4.7.6) Checking Ulw-Loop Steering");
+	for (const statusMessage of [
+		hooks.hooks.PostToolUse[0].hooks[0].statusMessage,
+		componentHooks.hooks.UserPromptSubmit[0].hooks[0].statusMessage,
+	]) {
+		assert.match(statusMessage, /^\(OmO 4\.7\.6\) \S/);
+		assert.doesNotMatch(statusMessage, /0\.1\.0/);
+	}
 	assert.deepEqual(snapshot, {
 		packageName: "lazycodex-ai",
 		version: "4.7.6",

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

@@ -104,42 +104,6 @@ test("#given plugin-local MCP runtime #when installing cached plugin #then manif
 	assert.deepEqual(cachedMcp.mcpServers.omo.args, [join(result.path, "dist", "cli.js")]);
 });
 
-test("#given CodeGraph MCP runtime in plugin cache #when installing cached plugin #then manifest points at cached plugin before bootstrap", async () => {
-	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: {
-			codegraph: {
-				command: "node",
-				args: ["components/codegraph/dist/serve.js"],
-				cwd: ".",
-				required: false,
-			},
-		},
-	});
-	await writeJson(join(sourceRoot, "components", "codegraph", "dist", "serve.js"), { executable: true });
-
-	const result = await installCachedPlugin({
-		codexHome,
-		marketplaceName: "sisyphuslabs",
-		name: "omo",
-		runCommand: async () => {},
-		sourcePath: sourceRoot,
-		version: "0.1.0",
-	});
-
-	const cachedMcp = JSON.parse(await readFile(join(result.path, ".mcp.json"), "utf8"));
-
-	assert.deepEqual(cachedMcp.mcpServers.codegraph.args, [join(result.path, "components", "codegraph", "dist", "serve.js")]);
-	assert.equal(Object.hasOwn(cachedMcp.mcpServers.codegraph, "cwd"), false);
-});
-
 test("#given external MCP package not in the generated bundled runtime set #when installing cached plugin #then manifest args point at source", async () => {
 	const repoRoot = await makeTempDir();
 	const codexHome = await makeTempDir();

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

@@ -58,18 +58,13 @@ test("#given packaged lazycodex adapter #when installing locally #then uses bund
 
 	assert.deepEqual(result.installed.map((plugin) => `${plugin.name}@${plugin.version}`), ["omo@0.1.2"]);
 	assert.equal(pluginCacheRoot, join(codexHome, "plugins", "cache", "sisyphuslabs", "omo", "0.1.2"));
-	assert.equal(commands.length, 2);
+	assert.equal(commands.length, 1);
 	const installCommand = commands.find((entry) => entry[0] === "npm");
 	assert.notEqual(installCommand, undefined);
 	const [command, args, cwd] = installCommand;
 	assert.equal(command, "npm");
 	assert.equal(args, "ci --omit=dev");
 	assert.equal(cwd.startsWith(join(codexHome, "plugins", "cache", "sisyphuslabs", "omo", ".tmp-0.1.2-")), true);
-	const sotCommand = commands.find((entry) => entry[1].includes("migrate-omo-sot.mjs"));
-	assert.notEqual(sotCommand, undefined);
-	assert.equal(sotCommand[0], process.execPath);
-	assert.equal(sotCommand[1].includes("--seed"), true);
-	assert.equal(sotCommand[2], repoRoot);
 	assert.deepEqual(cachedMcp.mcpServers.lsp.args, [cachedLspCli, "mcp"]);
 	assert.equal((await stat(cachedLspCli)).isFile(), true);
 });

package/packages/{omo-codex/plugin/components/ultrawork/skills/ultrawork/SKILL.md → prompts-core/prompts/ultrawork/codex.md}

@@ -1,10 +1,3 @@
----
-name: ultrawork
-description: Binding ultrawork mode directive for omo on Codex. When a prompt contains ultrawork or ulw, the omo UserPromptSubmit hook injects a short bootstrap that points at this file. Read the whole file and follow every rule in it for the rest of the task.
-metadata:
-  short-description: Binding ultrawork mode directive
----
-
 <ultrawork-mode>
 
 **MANDATORY**: First user-visible line this turn MUST be exactly:
@@ -53,8 +46,8 @@ first-class for CLI- or data-shaped work; self-review recorded in the
 notepad instead of the reviewer loop.
 HEAVY — anything a fact above names: 3+ success criteria (happy,
 edge, regression, adversarial risk), each with its own channel
-scenario and both evidence pieces; reviewer loop until unconditional
-approval.
+scenario and both evidence pieces; when the verification gate is
+triggered, run the reviewer loop until unconditional approval.
 
 # Manual-QA channels
 Run real-surface proof yourself through the channel that faithfully
@@ -69,11 +62,18 @@ exercises the surface; capture the artifact.
      for color / layout / CJK evidence, which degrades truecolor.
   3. Browser use — in Codex, use `browser:control-in-app-browser`
      first when available and no authenticated/persistent user browser
-     profile is required. Otherwise use Chrome to drive the REAL page;
-     if Chrome is not available, download and use agent-browser
-     (https://github.com/vercel-labs/agent-browser). Capture action
+     profile is required. Otherwise, or for Chrome semantics, stealth,
+     or trace, WRITE a `playwright-core` script and run it from js eval
+     against local Chrome (`chromium.launch({ channel: "chrome" })` /
+     `launchPersistentContext` on a CLONED profile). Capture action
      log + screenshot path. Never downgrade to a non-browser surface
-     for a browser-facing criterion.
+     for a browser-facing criterion. NEVER clear cookies, cache, or
+     site data (`Network.clearBrowserCookies`, `Storage.clearCookies`,
+     `chrome.browsingData.remove`, "clear browsing data") on the user's
+     real/main browser profile — it wipes their logged-in state. If you
+     need that profile's login state, clone it first (`rsync -a
+     <profile>/ <tmp-clone>/`) and launch Chrome against
+     the clone as the user-data-dir; run any clearing there only.
   4. Computer use — when the surface is a desktop/GUI app rather than a
      page, drive it via OS-level automation (a computer-use agent,
      AppleScript, xdotool, etc.) against the running app; capture
@@ -230,8 +230,8 @@ and utility functions to batch commands and reduce output. Keep direct calls
 when one result chooses the next action, outputs are already small, semantic
 judgment is required between calls, approval or side effects are involved,
 or native artifacts / citations must be preserved.
-- Architecture / flow / blast radius → `codegraph_explore` first when
-  `codegraph_*` exists; if unavailable, continue with repo tools and LSP.
+- Architecture / flow / blast radius → explore agents plus LSP references
+  and impact; do not guess from conventions.
 - **SYMBOLS REQUIRE LSP** — definitions, references, rename impact,
   workspace symbols, and diagnostics use the available `lsp_*` tools, not
   text search. Run diagnostics after edits and treat errors as blocking.
@@ -341,17 +341,26 @@ make the child continue old parent context instead of the delegated task.
 If your tool list has a flat `spawn_agent` with a required `task_name` instead of `multi_agent_v1.*` (`multi_agent_v2`), rewrite: `fork_context: false` becomes `fork_turns: "none"`, `send_input` becomes `send_message`, finished agents end on their own (no `close_agent`; `followup_task` re-tasks, `interrupt_agent` stops), and `wait_agent` takes only `timeout_ms`, returning on any child mailbox activity.
 
 # TOML-backed subagent routing compatibility
-Installed role TOMLs (`~/.codex/agents/`) bind ONLY via `agent_type`.
-`multi_agent_v1.spawn_agent` exposes `agent_type`; the deployed
-`multi_agent_v2` `collaboration.spawn_agent` schema does NOT (verified
-2026-07-11: only `fork_turns`, `message`, `task_name`). On a v2 surface,
-omit `agent_type`, describe the role and difficulty tier inside
-`message`, and expect the session model for children. Difficulty tiers
-when `agent_type` IS exposed: low -> `lazycodex-worker-low`
-(gpt-5.6-luna/high), medium -> `lazycodex-worker-medium`
-(gpt-5.6-luna/max), high -> `lazycodex-worker-high` (gpt-5.6-sol/max);
-explorer/librarian carry their own TOMLs (gpt-5.6-luna/low). Difficulty
-(model power) is orthogonal to LIGHT/HEAVY rigor (process size).
+Inspect the ACTUAL spawn tool schema, not a version or namespace assumption.
+When `agent_type` is exposed (V1 or V2), EVERY spawn MUST pass an exact
+LazyCodex role: `explorer`, `librarian`, `plan`, `metis`, `momus`,
+`lazycodex-worker-low`, `lazycodex-worker-medium`, `lazycodex-worker-high`,
+`lazycodex-code-reviewer`, `lazycodex-qa-executor`, `lazycodex-gate-reviewer`,
+or `lazycodex-clone-fidelity-reviewer`. Map implementation difficulty to
+worker low/medium/high; their installed TOMLs supply model and instructions.
+Never select generic `worker`/`default` or describe a role instead of selecting it.
+Use `fork_turns: "none"` on V2 or `fork_context: false` on V1 unless full
+history is deliberately required; even a deliberate fork MUST name its role.
+
+Legacy-schema exception: ONLY when `agent_type` is absent, omit that unsupported
+field and carry the role, difficulty, and complete instructions in `message`;
+explicitly disable history. This cannot select a specialized TOML. The managed
+`default` supplies the medium worker for unnamed non-forks, unless opted out or
+blocked by a preserved user default. The spawn guard cannot see the schema and
+rejects unnamed requests: report incompatible routing, do not retry generically.
+An unnamed full-history fork skips role application inside Codex; no LazyCodex
+config can fix that upstream gap. Never claim this path has been repaired.
+Difficulty (model power) is orthogonal to LIGHT/HEAVY rigor (process size).
 
 Treat child status as a progress signal, not a timeout counter. For
 work likely to exceed one wait cycle, tell the child to send
@@ -386,16 +395,17 @@ BLOCKED: <reason>`. After four silent or ack-only checks, close the lane as
 inconclusive, record that it is not approval, and respawn smaller only
 if the deliverable is still required.
 
-# Verification gate (TRIGGERED, NOT OPTIONAL)
+# Verification gate (TRIGGERED ONLY ON EXPLICIT DEMAND)
 
-Trigger when ANY apply:
-- Tier is HEAVY.
-- User demanded strict, rigorous, or proper review.
-LIGHT tier records a self-review in the notepad instead: re-read the
-diff, run diagnostics, confirm each criterion's evidence, and state in
-one line why the tier held.
+Trigger ONLY when the user explicitly demanded strict, rigorous, proper,
+or high-accuracy review of this work, in any language (for example,
+고정밀 or 엄격). The tier alone never triggers the gate. HEAVY without
+such a demand records the same self-review as LIGHT.
+LIGHT and non-triggered HEAVY work records a self-review in the notepad
+instead: re-read the diff, run diagnostics, confirm each criterion's
+evidence, and state in one line why the tier held.
 
-Procedure (NON-NEGOTIABLE):
+When triggered, follow this procedure (NON-NEGOTIABLE):
 1. Spawn a child with `fork_context: false` and a self-contained reviewer
    assignment in `message`. The `multi_agent_v1.spawn_agent` schema cannot select a
    TOML-backed reviewer role, so paste the reviewer requirements into

package/packages/shared-skills/package.json

@@ -8,12 +8,18 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./index.mjs"
+    },
+    "./skill-source-filter": {
+      "types": "./skill-source-filter.d.ts",
+      "import": "./skill-source-filter.mjs"
     }
   },
   "types": "./index.d.ts",
   "files": [
     "index.d.ts",
     "index.mjs",
-    "skills"
+    "skills",
+    "skill-source-filter.d.ts",
+    "skill-source-filter.mjs"
   ]
 }

package/packages/shared-skills/skill-source-filter.d.ts

@@ -0,0 +1,16 @@
+export const ignoredSkillSourceDirNames: readonly string[];
+export const ignoredSkillSourceFileNames: readonly string[];
+
+export interface SkillSourceCopyFilterOptions {
+	/** Additional file names (basename) to skip, merged with the shared defaults. */
+	ignoredFileNames?: readonly string[];
+}
+
+/**
+ * Returns an fs.cp-compatible filter for copying one skill source tree. Ignore rules are
+ * evaluated against the path RELATIVE to sourceRoot, never against the checkout's ancestors.
+ */
+export function createSkillSourceCopyFilter(
+	sourceRoot: string,
+	options?: SkillSourceCopyFilterOptions,
+): (sourcePath: string) => boolean;

package/packages/shared-skills/skill-source-filter.mjs

@@ -0,0 +1,44 @@
+/**
+ * Single source of truth for which files inside a skill source tree are copied into a
+ * harness plugin. Both omo-codex and omo-senpi sync-skills scripts consume this.
+ *
+ * Segments are tested RELATIVE to the copy root. The ignore list targets the skill tree's
+ * own cache directories; it must never react to where the repository happens to be checked
+ * out (a clone under ~/.omo/... or beneath any __pycache__-named ancestor still ships its
+ * skills). Testing the absolute path was the defect this module replaces.
+ */
+
+export const ignoredSkillSourceDirNames = Object.freeze([".mypy_cache", ".omo", ".pytest_cache", ".ruff_cache", "__pycache__"]);
+export const ignoredSkillSourceFileNames = Object.freeze([".gitignore", ".npmignore", "pyrightconfig.json"]);
+const sourceTestFilePattern = /\.test\.ts$/;
+
+function toSegments(path) {
+	return path.replaceAll("\\", "/").split("/").filter((segment) => segment.length > 0);
+}
+
+/**
+ * @param {string} sourceRoot absolute path of the directory being copied
+ * @param {{ ignoredFileNames?: readonly string[] }} [options]
+ * @returns {(sourcePath: string) => boolean} an fs.cp-compatible filter
+ */
+export function createSkillSourceCopyFilter(sourceRoot, options = {}) {
+	const rootSegments = toSegments(sourceRoot);
+	const ignoredFileNames = new Set([...ignoredSkillSourceFileNames, ...(options.ignoredFileNames ?? [])]);
+	const ignoredDirNames = new Set(ignoredSkillSourceDirNames);
+
+	return function shouldCopySkillSource(sourcePath) {
+		const pathSegments = toSegments(sourcePath);
+		if (pathSegments.length < rootSegments.length) return false;
+		for (let index = 0; index < rootSegments.length; index += 1) {
+			if (pathSegments[index] !== rootSegments[index]) return false;
+		}
+		const segments = pathSegments.slice(rootSegments.length);
+		if (segments.length === 0) return true;
+		const name = segments.at(-1) ?? "";
+		if (segments.some((segment) => ignoredDirNames.has(segment))) return false;
+		if (ignoredFileNames.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";
+	};
+}

package/packages/shared-skills/skills/ast-grep/AGENTS.md

@@ -0,0 +1,51 @@
+# ast-grep — Vendored Structural-Search Skill
+
+**Generated:** 2026-08-24 (f3642fcda)
+
+## OVERVIEW
+
+Vendored skill teaching agents ast-grep (`sg`) structural search/rewrite, plus a stdlib-Python helper CLI that wraps the `sg` binary. Vendoring pin in `SOURCE`: upstream `code-yeongyu/ast-grep-skill @ 3148c69` (ast-grep 0.45.0), "vendored as a sync; do not fork-drift". Earned this file: own executable surface (749-LOC helper + installers + smoke tests) and a no-fork-drift upstream contract that has no analogue elsewhere in `shared-skills`.
+
+## STRUCTURE
+
+```
+ast-grep/
+├── SKILL.md / README.md          # agent workflow / user overview
+├── SOURCE                        # upstream pin — the no-fork-drift contract
+├── scripts/ast_grep_helper.py    # 749-LOC stdlib CLI (argparse; no deps)
+├── install.sh / install.ps1      # macOS/Linux + Windows installers
+├── references/                   # cli, install, patterns, pitfalls, recipes, yaml-rules (510 LOC), sgconfig
+└── tests/smoke.{sh,ps1}          # POSIX + PowerShell smoke (also shell syntax + content checks)
+```
+
+## HELPER CLI (`scripts/ast_grep_helper.py`)
+
+Subcommands: `search`, `replace` (dry-run; `--apply` to write), `scan`, `test`, `new`, `langs`, `doctor`, `install`, `validate`. Resolves the `sg`/`ast-grep` binary across PATH, Homebrew, npm, and OMO caches, validates patterns before executing, and shells out — it never links ast-grep as a library. Internal handlers `cmd_*`; utilities `validate_pattern`, `normalize_lang`, `resolve_binary`, `run_sg`. Nothing in-repo imports it; docs and skills invoke it by path. `omo-opencode/src/cli/install-ast-grep-sg.ts` locates this skill dir to install the binary.
+
+## CONVENTIONS
+
+- AST patterns, never regex, for syntax-shaped queries; `$VAR` singles, `$$$` multis; patterns must parse as complete code in the target language.
+- Two-pass rewrites: preview with `--json=compact`, apply separately with `--update-all` — the flags are mutually exclusive in `sg`.
+- `sgconfig.yml` discovered upward; `ruleDirs`, optional `testConfigs`/`utilDirs`, language globs, custom languages, injections.
+- Upstream syncs land as whole vendored refreshes matching `SOURCE`; local edits ride along until the next sync absorbs or reverts them.
+
+## ANTI-PATTERNS
+
+- NO regex constructs (`.*`, `.+`, `\w`, `\d`, literal `|`) inside AST patterns — that is the skill's #1 pitfall.
+- No incomplete patterns (e.g. Python `def $F($$$):` without a body).
+- NEVER `--apply` a rewrite without the dry-run preview first.
+- Text/comment/byte queries go to `rg`, not structural matching.
+- Do not fork-drift from the `SOURCE` pin; a sync is a vendored refresh, not a merge.
+
+## COMMANDS
+
+```bash
+# from packages/shared-skills/skills/ast-grep/
+python3 scripts/ast_grep_helper.py search '<PATTERN>' --lang ts [path]
+python3 scripts/ast_grep_helper.py replace '<PATTERN>' '<REWRITE>' --lang ts   # dry-run; add --apply
+python3 scripts/ast_grep_helper.py doctor
+bash tests/smoke.sh          # or: pwsh tests/smoke.ps1
+# direct:  sg run -p '<PATTERN>' --lang ts path
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).

package/packages/shared-skills/skills/ast-grep/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ast-grep
-description: "Use ast-grep (sg) for AST-aware code search and rewrite across 25 languages. Trigger for structural code matching or deterministic codemods: find every function/call/class/import shaped like X, rewrite console.log to logger.info, strip `as any`, migrate require() to import, find empty catch blocks or missing await, and scan/apply YAML rules. Prefer this over rg/grep when the target is syntax shape rather than text; use rg for string contents, comments, filenames, or regex-style byte searches."
+description: "Searches and rewrites code by AST shape across 25 languages. Use when the target is a syntax pattern (every call/class/import shaped like X, a codemod, a YAML rule) rather than literal text; for plain strings, comments, or filenames, use rg."
 ---
 
 # ast-grep
@@ -11,6 +11,18 @@ This skill ships a Python wrapper at `scripts/ast_grep_helper.py` and platform i
 
 ---
 
+## OmO native: the ast-grep MCP tools (fastest path, no CLI needed)
+
+OmO native also registers a bundled ast-grep MCP server. Its three tools are **deferred**: they are absent from the resident tool list and activate automatically the first time you call them by name — no `tool_search` round trip needed.
+
+- `mcp__ast_grep_search({ pattern, language, paths })` — AST-shape search, the MCP equivalent of `sg run -p`. Prefer this over shelling out to `sg` for one-off lookups: no install, no PATH issues.
+- `mcp__ast_grep_rewrite({ pattern, rewrite, language, paths, apply })` — preview matches (`apply: false`, the default) or apply the rewrite (`apply: true`). Same two-pass discipline as `sg run -r`: preview first, then apply.
+- `mcp__ast_grep_scan({ paths })` — run project YAML rules (`sgconfig.yml`, `rules/`), the MCP equivalent of `sg scan`.
+
+Same pattern language as the CLI: `$VAR` matches one AST node, `$$$VAR` matches zero or more, and the pattern is code, not regex. `paths` accepts a file or directory list; `language` is required for patterns that are ambiguous across languages.
+
+---
+
 ## When to use this skill
 
 Use it whenever the user's question is about **code structure**, not bytes:

package/packages/shared-skills/skills/coding-agent-sessions/AGENTS.md

@@ -0,0 +1,62 @@
+# coding-agent-sessions — Cross-Platform Session Finder (Python)
+
+**Generated:** 2026-08-24 (f3642fcda)
+
+## OVERVIEW
+
+The only shared skill besides `ultimate-browsing` carrying a real sub-project: a Python package + CLI that finds, lists, searches, and reads local coding-agent session transcripts across ~25 platforms (Codex, Claude, OpenCode, OMO/Senpi/pi, and a long tail), normalizing them into one `Session` model. Earned this file: 33 files, 23 Python modules, own test suite, own `pyrightconfig.json`, own `.npmignore` (ships in the npm package minus tests/caches).
+
+## STRUCTURE
+
+```
+coding-agent-sessions/
+├── SKILL.md                      # router: platform table → references/<platform>.md
+├── references/                   # codex, claude, opencode, senpi, all-platforms (store layouts per platform)
+├── agents/openai.yaml            # Codex agent role declaration
+├── scripts/
+│   ├── find-agent-sessions.py    # thin shebang entry (PEP 723, >=3.11); runpy → agent_sessions.cli
+│   ├── agent_sessions/           # the package (12 modules)
+│   └── tests/                    # 6 pytest modules
+└── pyrightconfig.json            # extraPaths scripts/, excludes scripts/tests
+```
+
+## PUBLIC API (`scripts/agent_sessions/`)
+
+| Module | Key exports |
+|--------|-------------|
+| `scanners.py` | `scan`, `DEFAULT_PLATFORMS`, `PLATFORM_SCANNERS`, per-platform `scan_*` (codex, claude, opencode, senpi, oh_my_pi, gajae_code, …) |
+| `types.py` | `Session`, `Options`, `Json`, `JsonMap` — imported by nearly every module and test |
+| `transcript.py` | parallel file reads, normalization, timestamps, session ids; `recent`, `MAX_PLATFORM_FILES` |
+| `cli.py` | command parsing, filtering, payload construction, JSON emission (283 LOC — behavioral hotspot) |
+| platform adapters | `file_scanners.py` (file-backed providers), `opencode.py` (CLI/SQLite/storage fallbacks), `sqlite_scanners.py`, `sqlite_optional_scanners.py`, `pi_family.py`, `aside_scanner.py`, `kiro_scanner.py` |
+
+## CLI CONTRACT
+
+`python3 scripts/find-agent-sessions.py <command>`; aliases `find`=`search`, `read`=`get`. Commands: `list`, `find`/`search` (repeated `--query` lanes, `--from 7d`, repeated `--platform`, `--workers`, `--cwd/--model`, `--include-subagents`, `--limit`), `get`/`read <session-id>`. Output is JSON with `match_reasons` and reconstructed first/last user prompts — that JSON shape is the stable contract.
+
+## CONVENTIONS
+
+- Stdlib-only Python (`>=3.11`), `from __future__ import annotations`, pathlib everywhere; no third-party deps at runtime.
+- Probe-first, bounded discovery: platform-specific roots checked before broad globbing; optional platforms excluded from default search when they cannot reconstruct user prompts.
+- Main sessions hide subagent children by default but report child counts; `--include-subagents` flips it. Parent/child linkage preserved and records deduplicated.
+- Tests are pytest with `tmp_path` + `MonkeyPatch` isolation; in-file `# pyright: ignore[reportMissingImports]`-style relaxations for import diagnostics only.
+- `.npmignore` strips `scripts/tests/`, `pyrightconfig.json`, and caches from the shipped skill.
+
+## ANTI-PATTERNS
+
+- NEVER answer from normalized previews alone — pull the raw transcript (`read`/`get`) for exact evidence.
+- Usage-only stores are NOT transcript sources.
+- A Claude subagent's embedded `sessionId` is NOT its identity — use its `agentId` + parent-directory linkage.
+- Don't add a platform by globbing blindly; register it in `PLATFORM_SCANNERS`/`DEFAULT_PLATFORMS` with a bounded root probe.
+
+## COMMANDS
+
+```bash
+# from packages/shared-skills/skills/coding-agent-sessions/
+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 read <session-id>
+pytest scripts/tests
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).

package/packages/shared-skills/skills/coding-agent-sessions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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, OMO/Senpi/pi, oh-my-pi (omp), gajae-code (gjc), OpenClaw, Factory Droid, Amp, Gemini/Kimi/Qwen CLIs, Codebuff, Roo/Kilo/Cline, Kodu, Cursor CLI, Aider, Aside browser-agent sessions, 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/OMO/Senpi/pi/oh-my-pi/omp/gajae-code/gjc/OpenClaw/Droid/Amp/Kodu/Cursor/Aider/Aside sessions, transcript search, session history, session ID, read transcript, token usage, subagent sessions, what did I do yesterday, did we already do this."
+description: "Finds, reads, and reconstructs coding-agent sessions across Codex, Claude, OpenCode, OMO/Senpi, and other local agent logs. Use when asked to find or search past sessions, transcripts, or subagent runs, or to recover what an earlier session did."
 ---
 
 # Coding Agent Sessions