mirror-mind 0.33.3 → 0.34.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "mirror-mind",
+  "owner": {
+    "name": "Mirror Mind"
+  },
+  "plugins": [
+    {
+      "name": "mirror-mind",
+      "source": {
+        "source": "local",
+        "path": "./plugins/mirror-mind"
+      },
+      "description": "Mirror Mind — local-first memory and identity for agentic runtimes."
+    }
+  ]
+}

package/AGENTS.md

@@ -18,10 +18,10 @@ The mirror operates in four modes, chosen automatically based on context:
 Mirror, Builder, Explorer, and Soul.
 
 Each skill below is named three ways: `/mm-<skill>` in Pi and Gemini CLI,
-`$mm-<skill>` in Codex, `/mm:<skill>` in Claude Code. A Claude Code **plugin**
-install prefixes the plugin's name — `/mirror-mind:mm:<skill>` in the menu,
-`mirror-mind:mm-<skill>` as the skill's own name — and the forms below refer to
-the same skill.
+`$mm-<skill>` in Codex, `/mm:<skill>` in Claude Code. A **plugin** install
+prefixes the plugin's name — `/mirror-mind:mm:<skill>` in Claude Code's menu,
+`$mirror-mind:mm:<skill>` in Codex, `mirror-mind:mm-<skill>` as the skill's own
+name — and the forms below refer to the same skill.
 
 **Mirror Mode** — activate for: life decisions, feelings, business strategy,
 writing, mentoring, health, existential questions, sensemaking, psychological

package/docs/releases/index.md

@@ -12,6 +12,8 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.34.0 — Codex Through the Canonical Plugin](v0.34.0.md) — minor release closing CV21.DS4: Codex runs Mirror through the canonical plugin, installed in two commands from a marketplace the package ships, measured live at L4 on Codex 0.163.0. The v0.32.1 wrapper wiring no longer ships; `runtime diagnose` and `runtime update` say when Codex's cached plugin copy is behind and name the re-add that brings it level. No migration.
+- [v0.33.4 — A Name Is a Key](v0.33.4.md) — patch release of three first-run corrections: two from a contributor's PR #43 and CR141, which its review opened. `init --help` created a home named `--help`, `init ../escaped` created one outside `.mirror-minds`, and `init "My User"` put a space into `MIRROR_USER`; a user name is now a kebab-case key like a journey slug or a persona id, refused otherwise with a name that would work and nothing created. `identity edit` on Windows opens Notepad when no editor is named. Existing homes untouched. No migration.
 - [v0.33.3 — Mirror Finds Itself Under Any Path](v0.33.3.md) — patch release of one Change Request, CR140, carried by a contributor's PR #42: Mirror read its own install path from `URL.pathname`, so a checkout or package under a path with a space or a non-ASCII character read as `Install: unknown`, the welcome card showed no update, and `runtime update` refused. The path is now a filesystem path, a guard keeps the idiom out, and an `unknown` install names the path it looked up from. On Windows, npm's global layout is recognized and npm runs with no shell, verified on Windows in CI for the two files they touch; there is still no Windows product. Affected installs update once by hand. No migration.
 - [v0.33.2 — Git Runs Where Mirror Lives](v0.33.2.md) — patch release of one Change Request, CR138: on a clone install, `runtime status`, `version`, and `diagnose` describe the install from any directory, and `diagnose` grades Mirror's own tree. Git now runs only in the install's own checkout, so a checkout someone else made can no longer run a `core.fsmonitor` command through these commands; `version --start PATH` is the one explicit exception. Package installs were never exposed. No migration.
 - [v0.33.1 — The Install Answers For Itself](v0.33.1.md) — patch release of six RS010 Change Requests: the welcome card, the status line, and both `release-notes` readers answer for the install that is running, never for the cwd or the repository around the install. A package asks its own tree and the npm registry, a clone its own checkout and remote; `pending` says `unknown` when it cannot tell, and a `--ref` value can no longer run a command through git. No migration.

package/docs/releases/v0.33.4.md

@@ -0,0 +1,104 @@
+---
+digest: >
+  v0.33.4 is a maintenance release of three first-run corrections, two from a
+  contributor's PR #43 and one Change Request, CR141, that its review opened.
+  `mirror init --help` created a home named `--help`; `init ../escaped` created
+  one outside `.mirror-minds`; `init "My User"` put a space into `MIRROR_USER`
+  for every wiring command. A user name is now a kebab-case key, like a journey
+  slug or a persona id, refused otherwise with a name that would work and
+  nothing created. And `identity edit` on Windows opens Notepad when no editor
+  is named, instead of failing to start nano. Existing homes are untouched; no
+  migration.
+---
+
+# v0.33.4 — A Name Is a Key
+
+**Date:** 2026-10-17
+
+## Highlights
+
+- **`init` takes a kebab-case key for a user name, and nothing else** (CR141, from the
+  review of PR #43). `init ../escaped` created `~/escaped`, outside the directory the
+  product owns; `init "My User"` put a space into `MIRROR_USER`, which every wiring
+  command `init` prints then carried; `init a/b` nested. Each is refused before anything
+  is created, with the sentence `identity set` already uses: the consequence, the rule,
+  and a key that would work.
+- **`init --help` no longer creates a home named `--help`** (PR #43 by
+  @rodrigoimmaginario). The command has no flags; a word that starts with `-` gets the
+  usage line and exit 2.
+- **`identity edit` opens Notepad on Windows when no editor is named** (PR #43). The
+  order is unchanged, `EDITOR`, then `VISUAL`, then the platform's default: `notepad` on
+  Windows, where nano exists only inside Git Bash, `nano` elsewhere.
+- **Existing homes are untouched.** `init` only creates; a home with another kind of name
+  keeps it.
+
+## Where We Started
+
+A contributor's first run on Windows met two small things and sent a PR for each:
+`init --help` created a home, and `identity edit` with no `EDITOR` set failed to start
+nano. The first was not a Windows bug at all; it reproduced on macOS in a second.
+
+Its review asked what else `init` accepted. The answer was anything. The name becomes
+`~/.mirror-minds/<user>` and the value of `MIRROR_USER`, and the repository had already
+decided, in CR104, that a key which goes into paths and shell commands must be one plain
+word a shell cannot split, substitute, or read as an option. Journey slugs and persona
+ids had met that rule since `v0.32.0`. The user name was the last key of its kind that
+did not.
+
+## What Changed
+
+**One sentence for every key.** `newUserNameProblem` joins `newIdentityKeyProblem` in
+`ts/src/identity/identityKey.ts`, both over one builder, so `init`, `identity set`,
+`identity edit`, and `seed` refuse a non-key the same way. The key is printed escaped: a
+name with a newline or a `;` in it cannot forge output or a command. `runInit` asks before
+`initUserHome`, so a refusal leaves `$HOME` as it was: no home, no identity directory, no
+config file.
+
+**The test is the PR's, widened.** `../escaped`, `My User`, `a/b`, and an accented name go
+through the real front door; each asserts the exit, the sentence with its suggestion, and
+an empty home afterwards. PR #43's own `init --help` test stands beside it.
+
+**Notepad, with its evidence still owed.** The platform is a dependency of
+`resolveEditor`, so both defaults are tested on every OS. The PR verified the Windows
+round trip on an unchanged buffer, which prints `No changes detected.` whether Notepad
+blocked or returned at once; early Windows 11 Notepad did return at once. A round trip
+that changes the buffer is asked for on the PR, and the default ships as the better of
+the two available answers: nano could not start at all.
+
+### What you will notice
+
+- A first `mirror init` with a name that is not a plain lowercase word is refused with
+  a name that would work. `mirror init your-name`, as Getting Started has always said,
+  is unchanged.
+- On Windows, `mirror identity edit …` opens Notepad instead of failing.
+- Nothing else.
+
+## Upgrading
+
+```bash
+mirror runtime update          # or: npm install -g mirror-mind
+```
+
+There is no database migration and no runtime wiring change. If `v0.33.3`'s note applied
+to you, a Mirror under a path with a space or an accent, and you have not yet taken its
+one manual update, take it first; from `v0.33.3` on, `runtime update` works.
+
+## Conscious Exclusions
+
+- **Selecting an existing home by name.** `MIRROR_USER` pointing at a home created
+  before this rule, under whatever name, still selects it. Only creation is constrained.
+- **`init`'s wiring lines on Windows.** They print `ln -s`, which Windows has no answer
+  to; that waits for the runtimes to be verified there, as the contributor's PR says.
+- **Counting verdicts as front-door errors** (CR139), unchanged since `v0.33.2`.
+
+## What We Learned
+
+A fix for an instance invites the question "what else?", and the cheapest moment to ask
+it is the review. The `-` check was right; the class was one line away, and the rule
+already existed with its sentence, its escaping, and its tests. When a repository has
+decided something once, the second instance should cost a reference, not a decision.
+
+## Next Horizon
+
+CR139, the verdict loop, is the visible next step in RS010. The contributor's Windows
+series, if it comes, begins with the suite on `windows-latest`.

package/docs/releases/v0.34.0.md

@@ -0,0 +1,142 @@
+---
+digest: >
+  v0.34.0 is a minor release closing CV21.DS4: Codex runs Mirror through the
+  canonical plugin, the same one Claude Code loads. The package ships a Codex
+  marketplace; two commands install the plugin, Codex asks once to trust its
+  hooks, and from then on every session carries the skills, the Operating
+  Instructions, per-turn Mirror Mode injection, the MCP server, and logging as
+  `codex` with every reply beside its prompt — measured live at L4 on Codex
+  0.163.0. The v0.32.1 wrapper wiring is removed: `scripts/codex-mirror.sh`,
+  its hooks, and the JSONL backfill no longer ship. Because Codex copies the
+  plugin into a versioned cache, `runtime diagnose` and `runtime update` now
+  say when that copy is behind and name the one command that brings it level.
+  No migration.
+---
+
+# v0.34.0 — Codex Through the Canonical Plugin
+
+**Date:** 2026-10-17
+
+## Highlights
+
+- **Codex installs Mirror as a plugin, from a marketplace the package ships**
+  (CV21.DS4.US1). Two commands — `codex plugin marketplace add "<pkg>"`, then
+  `codex plugin add mirror-mind@mirror-mind` — and Codex asks once, at the
+  next session, to trust the plugin's hooks. `mirror init` prints exactly
+  these steps when it finds `codex` on the PATH.
+- **Codex is at L4, measured live** (CV21.DS4.US4, on Codex 0.163.0): all 25
+  skills, the Operating Instructions as a developer message, Mirror Mode on
+  an ordinary turn and on `$mirror-mind:mm:mirror`, the 7 MCP tools behind
+  Codex's `tool_search`, and every prompt and reply logged as `codex`. Codex
+  detaches the TUI on `/quit` and fires SessionEnd only when its daemon reaps
+  the idle thread, so Mirror gained a safety net for sessions that outlive
+  their TUI: session maintenance closes them as orphans
+  (`MIRROR_STALE_ORPHAN_MINUTES`, default 30).
+- **A bounded SessionEnd no longer cuts extraction** (CV21.DS4.TS2). Codex
+  bounds the hook at 1 s; the close now runs no LLM work, and the next
+  session start finishes the deferred tail. Grok's 1.5 s bound rides the same
+  change.
+- **`$`-skill turns are command turns** (CV21.DS4.TS3), as `/`-commands are
+  on every other runtime, with Mirror's explicit form the one exception.
+- **The v0.32.1 Codex wiring is removed** (CV21.DS4.TS5). What no longer
+  exists: `scripts/codex-mirror.sh`, `scripts/codex-hooks/`, the
+  `codex:session-*` hook entries, and
+  `conversation-logger backfill-codex-session` — the plugin logs Codex turns
+  as they happen, so nothing re-imports the transcript at exit. A
+  retired-surfaces guard keeps the wiring from drifting back.
+- **An updated Mirror now reaches Codex's plugin cache — or says so**
+  (CV21.DS4.TS6). Codex copies the plugin into its cache at a version, so an
+  npm update changes the install but not the copy Codex runs. `runtime
+  diagnose` reports `codex_plugin_cache_behind` naming both versions and the
+  measured command — `codex plugin add mirror-mind@mirror-mind`; re-adding
+  refreshes the cache in place, no remove needed — and a successful `runtime
+  update` prints the same line. A dangling Claude Code skills link is
+  reported too (`claude_plugin_link_dangling`). Absence is not drift: an
+  unwired machine stays green.
+
+## Where We Started
+
+v0.33.0 proved one plugin works as it is on Claude Code, Codex, and Grok.
+But a Codex user still wired Mirror by hand: a skills link, an `AGENTS.md`
+link, and a wrapper script around every session that imported the transcript
+from JSONL at exit — v0.32.1's wiring, built when Codex had no hook system.
+Codex 0.157 added plugins; DS4 asked whether the canonical plugin could be
+the whole answer, and set a gate: the old wiring retires only once parity is
+shown live.
+
+## What Changed
+
+**The install is two commands.** The npm package root carries
+`.agents/plugins/marketplace.json`, one local plugin — the same
+`plugins/mirror-mind` Claude Code loads. Codex copies it into its cache at
+the plugin's version and runs its Claude-family hooks as they are; runtime
+detection reads Codex's `turn_id` and labels the session `codex`.
+
+**The gate was met, so the old path is gone.** US4 measured L4 twice, live,
+through the shipped plugin alone. TS5 then removed the wrapper, its generated
+hooks, the `codex:*` hook family, the JSONL backfill (its only caller was the
+wrapper's exit hook; the plugin's SessionEnd closes without reading it),
+their pack-contents guards, and their CI step. The docs name the marketplace
+install and nothing else.
+
+**The one stale copy is watched.** Claude Code reads the plugin through a
+link, in place; Codex runs a versioned copy. TS6 taught `runtime diagnose`
+and `runtime update`'s post-update hints to compare that copy against the
+installed version — the landed version, read from the just-updated tree —
+and to print the one command that works on Codex 0.163.0, which has no
+plugin-update verb: the re-add.
+
+## Upgrading
+
+```bash
+npm install -g mirror-mind@latest    # or: mirror runtime update
+```
+
+**If Codex runs the plugin already:** after this update (and any future one),
+bring the cache level once:
+
+```bash
+codex plugin add mirror-mind@mirror-mind
+```
+
+`mirror runtime diagnose` will tell you whenever this is needed.
+
+**If you wired Codex before the plugin** (a skills link, an `AGENTS.md` link,
+the wrapper script): install the plugin with the two commands above, then
+undo the old wiring — the exact steps are in Getting Started's Codex section.
+If you do nothing, everything still works, at the cost of doubled skills and
+double logging where the old wrapper still runs; an older installed package
+keeps its own wrapper copy, but this version ships none.
+
+No migration. Existing homes, sessions, and memories are untouched.
+
+## Conscious Exclusions
+
+- **Codex logging is no longer end-to-end tested**, by decision: the retired
+  wrapper smoke was the only artifact-level Codex check. Confidence now rests
+  on the shared Claude-family hook path (smoked), runtime-detection units,
+  and US4's live measurement.
+- **Mirror never runs `codex` itself.** The cache readers are read-only
+  filesystem checks; the person runs the printed command.
+- **Two named silences in the wiring checks:** a cache *ahead* of the install
+  (a deliberate downgrade gets no advice from the older tree), and a Claude
+  link that resolves to another install tree (healthy means the target
+  reads). Both are recorded as decisions with tests.
+- **CR142 is captured, not fixed:** the Claude plugin smoke's negative probe
+  fails on a machine with a globally installed `mirror-hook` — a smoke
+  isolation bug found during TS5's validation, pre-existing, filed under
+  RS010.
+
+## What We Learned
+
+The gate ordering did the work: retiring the old wiring only after L4 was
+measured live meant the removal was a deletion, not a bet. And the one real
+surprise of the arc — Codex sessions outlive their TUI — was caught by the
+live measurement, not by any test, which is why the measurement is part of
+the method.
+
+## Next Horizon
+
+DS4 closes with this release. CV21's remaining runtime stories — Antigravity
+through a native layer (DS7), Grok (DS10) — are pulled deliberately from the
+CV21 index.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.33.3",
+  "version": "0.34.0",
   "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Gemini CLI, Codex)",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,7 @@
     ".claude/hooks",
     ".gemini/hooks",
     "plugins/mirror-mind",
-    "scripts/codex-hooks",
-    "scripts/codex-mirror.sh",
+    ".agents/plugins",
     "AGENTS.md",
     "README.md",
     "LICENSE"

package/plugins/mirror-mind/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.33.3",
+  "version": "0.34.0",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"

package/ts/src/conversation/backfill.ts

@@ -1,20 +1,17 @@
 // Session backfills from runtime-written JSONL (CV22.DS7.US10 slice E).
 //
-// Ports `backfill_pi_sessions` and `backfill_codex_session` from
-// `src/memory/cli/conversation_logger.py`. Both import a closed session the
-// live hooks never saw, through the atomic seam in `sessionImport.ts`, and
-// both are graded against `ts/test/goldens/backfill.golden.json`.
+// Ports `backfill_pi_sessions` from `src/memory/cli/conversation_logger.py`:
+// it imports closed sessions the live hooks never saw, through the atomic
+// seam in `sessionImport.ts`, and is graded against
+// `ts/test/goldens/backfill.golden.json`. (The Codex importer,
+// `backfill_codex_session`, was ported beside it and retired with the
+// v0.32.1 Codex wrapper by CV21.DS4.TS5: its only caller was the wrapper's
+// session-end hook, and the plugin logs Codex turns live.)
 //
-// The two are deliberately NOT unified beyond that seam, because Python's
-// asymmetries are the contract:
-//   * Pi titles through `set_provisional_title` (whitespace collapse plus
-//     `title_source`/`title_status` provenance in metadata); Codex titles
-//     through `_generate_title` and a bare column write with no provenance.
-//   * Pi tolerates a corrupt or structurally invalid file by skipping THAT
-//     file and continuing the walk; Codex gives up on its single file.
-//   * Pi parses every timestamp form (millisecond epoch, string, absent);
-//     Codex stores the raw `timestamp` value and lets the model reject a
-//     missing one.
+// Pi titles through `set_provisional_title` (whitespace collapse plus
+// `title_source`/`title_status` provenance in metadata), tolerates a corrupt
+// or structurally invalid file by skipping THAT file and continuing the
+// walk, and parses every timestamp form (millisecond epoch, string, absent).
 //
 // Nothing here touches a provider or the clock directly: `now` is injected
 // through `LoggerDeps`, which is what makes "no timestamp -> now" pinnable.
@@ -24,12 +21,11 @@
 // home meant the person's whole Pi history, copied and spent on before the
 // first prompt. The floor is explicit (`notBefore`), never defaulted, and
 // the rule fails closed: there is no value that means "everything" except
-// the epoch, which says so. The Codex importer is untouched: it imports the
-// one session the wrapper names, not a history.
+// the epoch, which says so.
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
-import { generateTitle, type LoggerDeps, setProvisionalTitle } from "#conversation/logger.ts";
+import { type LoggerDeps, setProvisionalTitle } from "#conversation/logger.ts";
 import { type ImportedMessage, importClosedConversation } from "#conversation/sessionImport.ts";
 import type { WritableDatabase } from "#db/database.ts";
 import { expandHome } from "#util/paths.ts";
@@ -76,13 +72,6 @@ function getFrom(container: unknown, key: string): unknown {
   return getOr(container, key, undefined);
 }
 
-/** Python truthiness for JSON values: empty containers are falsy too. */
-function pythonTruthy(value: unknown): boolean {
-  if (Array.isArray(value)) return value.length > 0;
-  if (isRecord(value)) return Object.keys(value).length > 0;
-  return Boolean(value);
-}
-
 /** Python `_parse_pi_content`: a string as-is, text blocks joined by `\n`, else `""`. */
 export function parsePiContent(content: unknown): string {
   if (typeof content === "string") return content;
@@ -280,108 +269,3 @@ export function backfillPiSessions(
   }
   return count;
 }
-
-interface CodexParse {
-  sessionId: string | null;
-  messages: { role: string; content: unknown; createdAt: unknown }[];
-}
-
-/**
- * Parse a Codex session file. Throws on the first line that is not valid
- * JSON or not the expected shape; Python's single `try` turns that into
- * "return 0". Values are collected raw: Python validates them only when the
- * import constructs its models.
- */
-function parseCodexSessionFile(path: string): CodexParse {
-  const parsed: CodexParse = { sessionId: null, messages: [] };
-  for (const line of readFileSync(path, "utf8").split(/\r?\n|\r/)) {
-    if (!line.trim()) continue;
-    const entry: unknown = JSON.parse(line);
-    const entryType = getFrom(entry, "type");
-    const payload = getOr(entry, "payload", {});
-    if (entryType === "session_meta") {
-      // Codex writes a UUID string; a non-string id is treated as absent
-      // (the same simplification the hook payloads make).
-      const id = getFrom(payload, "id");
-      parsed.sessionId = typeof id === "string" ? id : null;
-    } else if (entryType === "event_msg") {
-      const payloadType = getFrom(payload, "type");
-      if (payloadType === "user_message" || payloadType === "agent_message") {
-        const content = getOr(payload, "message", "");
-        // Python: `if content:` -- any truthy value is kept and validated later.
-        if (pythonTruthy(content)) {
-          parsed.messages.push({
-            role: payloadType === "user_message" ? "user" : "assistant",
-            content,
-            createdAt: getFrom(entry, "timestamp"),
-          });
-        }
-      }
-    }
-  }
-  return parsed;
-}
-
-export interface CodexBackfillOptions {
-  jsonlPath: string;
-  interface?: string;
-}
-
-/**
- * Python `backfill_codex_session`: import one Codex session file as a closed
- * conversation titled through `_generate_title`. Returns 1 on import, else 0.
- *
- * Throws when a kept event has a non-string `message` or `timestamp`: Python's
- * `Message(...)` model rejects those inside the import transaction, so the
- * database is left untouched and the caller sees the failure.
- */
-export function backfillCodexSession(
-  db: WritableDatabase,
-  options: CodexBackfillOptions,
-  deps: LoggerDeps,
-): number {
-  const jsonlPath = expandHome(options.jsonlPath);
-  if (!existsSync(jsonlPath) || !statSync(jsonlPath).isFile()) return 0;
-
-  let parsed: CodexParse;
-  try {
-    parsed = parseCodexSessionFile(jsonlPath);
-  } catch {
-    return 0;
-  }
-  if (!parsed.sessionId || parsed.messages.length === 0) return 0;
-  if (db.prepare("SELECT 1 FROM runtime_sessions WHERE session_id = ?").get(parsed.sessionId)) {
-    return 0;
-  }
-
-  const messages: ImportedMessage[] = parsed.messages.map((message) => {
-    if (typeof message.content !== "string") {
-      throw new TypeError("Codex event message must be a string");
-    }
-    if (typeof message.createdAt !== "string") {
-      throw new TypeError("Codex event timestamp must be a string");
-    }
-    return { role: message.role, content: message.content, createdAt: message.createdAt };
-  });
-
-  const conversationId = importClosedConversation(
-    db,
-    parsed.sessionId,
-    {
-      interface: options.interface ?? "codex",
-      messages,
-      endedAt: (messages.at(-1) as ImportedMessage).createdAt,
-    },
-    deps,
-  );
-  if (conversationId === null) return 0;
-
-  const firstUser = messages.find((message) => message.role === "user");
-  if (firstUser) {
-    db.prepare("UPDATE conversations SET title = ? WHERE id = ?").run(
-      generateTitle(firstUser.content),
-      conversationId,
-    );
-  }
-  return 1;
-}

package/ts/src/conversation/commandTurn.ts

@@ -0,0 +1,42 @@
+// A command turn: a prompt that opens with a skill invocation, in any runtime's
+// sigil (CV21.DS4.TS3).
+//
+// The prompt hook skips a command turn and records it, so the Stop hook skips
+// its reply too (`command_turn`, CV21.DS2.US8): a skill's rendering -- a
+// journey table, help text -- is not conversation, and extraction reading it
+// as if the person said it is noise. What you say to the mirror is remembered;
+// a skill you invoke is not. The one exception is the Mirror skill's explicit
+// form, whose question IS the conversation turn (`mirrorForm.ts`); the prompt
+// hook checks that form first, and a test holds every Mirror form to be a
+// command turn, so the exception always sits inside this rule.
+//
+// The two sides are deliberately asymmetric:
+//
+//   `/`  skips ANYTHING. Every runtime uses `/` for its own built-ins as well as
+//        for skills (`/hooks`, `/mcp`, `/compact`), so a prompt opening with it
+//        is a command whatever follows. This is the rule US8 inherited.
+//   `$`  skips only a SKILL NAME. `$` is Codex's skill sigil and nothing else
+//        (`$mirror-mind:mm:journeys` through the plugin, DS12.TS2 L10;
+//        `$mm-journeys` through a skills link), and `$5 a month` is English.
+//        The name is lowercase segments -- letters, digits, hyphens, and
+//        underscores after the first letter, since Codex discovers
+//        `~/.codex/skills/<dir>` by directory name -- with an optional
+//        plugin-name prefix joined by `:`, ending at whitespace or the end of
+//        the prompt, the boundary `mirrorForm` draws. A comma is not a boundary
+//        and a leading space is not a prompt start, as ` /help` is not a
+//        command today.
+//
+// One rule for every runtime: a Claude Code user who types `$mm-journeys`,
+// which Claude Code does not understand, is still invoking a skill, and that
+// turn is not conversation either. The rule has one home for every hook that
+// runs in our process (the Claude-family logger, the Gemini hook); the Pi
+// extension, a separate process in Pi's file, keeps its own `/` check.
+
+const SKILL_SEGMENT = "[a-z][a-z0-9_-]*";
+const DOLLAR_SKILL_FORM = new RegExp(`^\\$${SKILL_SEGMENT}(?::${SKILL_SEGMENT})*(?=\\s|$)`);
+
+/** Whether the prompt opens with a skill invocation in any runtime's sigil. */
+export function isCommandTurn(prompt: string): boolean {
+  if (prompt.startsWith("/")) return true;
+  return DOLLAR_SKILL_FORM.test(prompt);
+}