feat: add OMP (Oh My Pi) as a new session backend

[timkjr]

Summary

Adds omp (Oh My Pi, https://github.com/can1357/omp) as an eighth CLI backend,
alongside Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi, Grok and DeepSeek
Harness. It follows the existing external-CLI pattern exactly (own PTY, own tmux
session, own tab identity, isExternalCliMode()), and gets full support across
every surface that pattern touches: schemas, spawn-command building, Docker cases,
remote-SSH cases, multi-user clamping, the UI run-mode picker, and skill docs.

Two things make this more than routine plumbing:

• Exact-conversation pinning.--continue alone is ambiguous the moment any
  other omp conversation has touched the same working directory more recently.
  omp-session-resolver.ts resolves and pins the real session id once, so every
  later respawn uses --resume <id> instead of re-guessing.
• Kill-survival.omp-transcript.ts scans ~/.omp/agent/sessions/**/*.jsonl
  directly, so a conversation's history is recoverable in Past Sessions even when
  both the Codeman session record and the underlying tmux pane are gone —
  verified live against a full OS reboot, not just a killed pane.

Notable bugs found and fixed along the way

• A boot-recovery bug where claudeSessionId (the field also used to alias an
  OMP session's own id) failed to resolve on a plain-reattach path. Root cause
  was two compounding issues: an unconditional second assignment that clobbered
  the correctly-resolved value, and a directory-mangling helper that assumed omp
  mirrors Claude Code's naming convention (keeps the $HOME prefix) when omp
  actually strips $HOME first. This second bug meant continuation pinning was
  silently a no-op for every real case directory under $HOME — only /tmp-based
  manual testing had ever exercised the code path, and it happened to produce the
  right answer there by coincidence.
• OMP was never actually installed in docker/agent.Dockerfile, and had no
  credential-isolation entry, despite the docs already claiming full Docker
  support. Both fixed and verified against a real --no-cache image build.
  OMP is also the one CLI in this family where sessions/ needs to be a
  shared mount rather than seeded, since Codeman reads it host-side for the
  resume-pinning and history-recovery mechanisms above.

Note for reviewers: while verifying the Docker changes above, I found the
agent image's DeepSeek (dsh) plugin-install step currently fails on a fresh
build against unmodified master ("pnpm not found on PATH") — confirmed via
git diff origin/master that the failing line is untouched by this branch.
Unrelated to OMP; filed separately as #352.

Testing

• Full suite: 6317 passed, 0 failures (npm test)
• lint, typecheck, check:frontend-syntax, check:public-assets,
  check:lockfile all clean
• Live-tested: session create/respawn/resume, TUI-exit + remove-tab,
  TUI-exit + tmux kill-session + restart, and a full server/OS reboot —
  all recover correctly, including first-turn content
• Docker: verified omp/18.0.8 installs and runs inside a freshly built
  agent image

Known limitations (documented in docs/omp-integration.md)

• No idle/completion hook — falls back to output-stabilization like every
  other external CLI
• Killing a pane mid-turn (before an in-TUI /exit) loses the conversation for
  real; omp hasn't flushed its session file yet at that point. This isn't
  something Codeman can compensate for from outside the process.
• Directory-mangling behavior on a symlinked $HOME is unverified

[timkjr]

Pushed one more fix after opening this PR: 13a19f7. A fresh "Run OMP" click was silently resuming an old conversation instead of starting clean, in any working directory with prior OMP history — found live while testing, root-caused, fixed, and verified in production. Full details in the commit message; test suite still green (6319 passed).

[Ark0N]

Thanks for this, and for the write-up. The core is in good shape: it follows the external-CLI pattern faithfully, the resolver reuses createCliExecutableResolver instead of hand-rolling a fifth copy, the Docker cred-store entry reasons correctly about shared-vs-seeded, and omp-transcript.ts reading the session header instead of reverse-engineering the mangled directory name is exactly right (dsh taught us that mangling changes form). CI is green and the tests you added cover what you built.

I read the diff against omp upstream too (the repo is can1357/oh-my-pi, 28k stars, MIT, releasing daily, so a backend for it is worth having). A few things need to change first, and one of them is a correctness bug.

1. The newest-mtime pin breaks with two omp tabs in one case

findLatestOmpSessionId() is "newest file in the directory, full stop", and the comment argues callers only invoke it where that is unambiguous. Two of them are not:

• _resolvedOmpRespawnConfig() runs from the eager respawnPaneOptions: this._buildRespawnPaneOptions() in startInteractive(), and your own guard comment notes _muxSession is already set on a boot-recovery reattach. So on every server restart it resolves and pins for each recovered omp session, including ones whose pane is alive and whose file is not the newest. Two omp sessions in the same case (w1-foo, w2-foo, the normal fan-out shape here) both alias onto the same id, and a later respawn of one resumes the other's conversation, with two processes appending to one session file.
• _maybeCaptureOmpSessionId() on first idle is the same race in a narrower window.

This is the rule CLAUDE.md already carries for dsh: pair by the transcript's own header plus a launch window, never by newest mtime, because newest-mtime handed a fresh worker its predecessor's answer in the same case dir. You already parse that header in omp-transcript.ts ({"type":"session","id","cwd"}), so the pieces are there: snapshot the directory at spawn, accept only a file whose header cwd matches and that appeared after this session launched, and skip an id a live sibling already pinned.

Related: the pin is a side effect of building respawn options, which is what bit you in 13a19f7. Resolving where the respawn is actually issued would remove that whole class of bug rather than guarding it.

2. The env-allowlist and clamp claims do not match omp's docs

docs/omp-integration.md says omp "has no documented vendor-key namespace of its own (its provider credentials live in ~/.omp config files, not environment variables)", and CLAUDE.md gains "the multi-user clamp has nothing to gate". Per omp's own docs/environment-variables.md, neither holds:

• omp reads roughly 40 provider keys from the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, HF_TOKEN, ...). That is pi's 34-key problem in the same shape. Keeping them out of the allowlist is correct, the stated reason is not.
• omp's own knobs are mostly PI_*, not OMP_*, and PI_ is already allowlisted globally because pi mode needs it. So an omp session today already accepts PI_CONFIG_DIR ("config root dirname under home, default .omp"), PI_CODING_AGENT_DIR, PI_CODING_AGENT_SESSION_DIR, OMP_PROFILE/PI_PROFILE, PI_SUBPROCESS_CMD ("overrides subagent spawn command") and PI_SHELL_PREFIX. The first three also move the tree omp-session-resolver.ts and omp-transcript.ts hardcode, so pinning and history quietly stop working, which makes resolveOmpHome()'s "no known env override exists (unlike DSH_HOME); revisit if omp adds one" wrong as of today.
• The OMP_ prefix this PR adds brings in OMP_AUTH_BROKER_URL + OMP_AUTH_BROKER_TOKEN, which is where omp resolves credentials from. That is the shape DEEPSEEK_BASE_URL gets dropped for in clampEnvOverridesForOwner().

None of this matters in single-user mode. It matters for a non-granted owner in multi-user mode, which is why pi and dsh both have explicit clamp branches. Please make the decision explicit instead of "nothing to gate": either add the config-root and broker keys to the clamp for omp, or write down why they are acceptable. Worth stating in the doc as well that omp's documented default tools.approvalMode is yolo, so an omp pane auto-approves exec with no flag from us.

3. Three changes in one PR

Besides the omp backend there are two riders:

• resumeHistorySession() now creates the session in the row's own mode and DELETEs the old row. That changes behavior for opencode, pi, grok, deepseek, codex, gemini and antigravity users, not just omp. Mode fidelity is a real improvement (resuming a codex row as claude was silly). But codex, gemini and antigravity are not in the modeConfigKey map, so for them Resume now starts a fresh session with no continuation and retires the row it came from, which is a strange pairing. Either give those three their continuation flag, or only retire the row when the new session actually continues something.
• DELETE /api/sessions/:id gained the persisted-only fallback that the above needs, and reimplements the ownership check inline rather than going through findSessionOrFail. I would rather extend the helper, since that function is where ownership enforcement is supposed to live. The persisted branch also does not broadcast session_deleted, so other tabs keep the row until their next fetch.
• The per-device "Hide CLI buttons" setting is a feature of its own. Its mode list is ['claude','opencode','codex','gemini','antigravity','pi','omp'] in both the load and the save path, so grok and deepseek cannot be hidden.

I would rather take these as two or three PRs. If they stay together, the changeset has to describe all of it: right now it covers only the backend and lists the siblings as "Claude Code, OpenCode, Codex, Gemini, and Antigravity" with Pi, Grok and DeepSeek missing. That text lands verbatim in the release notes.

4. Smaller, all concrete

• https://github.com/can1357/omp 404s. It is can1357/oh-my-pi, in the PR body and in docs/omp-integration.md.
• CLAUDE.md now links #external-cli-modes-...-deepseek-omp, but docs/architecture-invariants.md still carries the -deepseek heading and is not touched by this PR, so the link is dead and omp has no entry in the deep-detail doc every other CLI has.
• The doc says the installer places the binary in ~/.omp/bin, but your own Dockerfile comment says that guess was wrong, and upstream's installer is INSTALL_DIR="${PI_INSTALL_DIR:-$HOME/.local/bin}". The resolver's search order should probably lead with ~/.local/bin.
• omp is the ninth CLI backend and tenth SessionMode, not the eighth (docs and changeset).
• The case 'omp' added to appendResumeFlag() looks unreachable: it keys off the top-level resumeSessionId, which is validated against ~/.claude/projects for every mode, while the omp pin lands in ompConfig.resumeSessionId. Docker panes are built from defaultDockerCommandForMode and never see ompConfig, so the Docker section overstates it: host-side history recovery works there, --resume pinning does not reach the in-container omp. Worth a live check.
• scanOmpSessionsHistory() is fully synchronous (readdirSync plus readFileSync of whole files, up to 2MB each, up to 2000 of them) inside gatherUnifiedInputs(), which the home screen hits on every visit. The claude scanner beside it is async with 16KB/128KB head windows for exactly that reason.
• Stray comment fragment landed in the quick-start docker branch: // configured project. Skipped for external CLIs (they use their own systems). right after if (docker && docker.hooksEnabled && mode === 'claude') {.
• Two jammed CSS lines survive from the block-closing commit: color: #eef2ff; transform: translateY(-1px); and color: #eef2ff;}.
• The doc's version example says omp/17.4.0 while you tested 18.0.8.

Things I would keep as they are: the version probe demanding omp/<semver> (right instinct for a three-letter binary name), the $HOME-stripping mangling comment with the "silently returns null" warning, the shared-vs-seeded reasoning in CRED_STORES, and the honest Known Gaps section including the mid-turn kill.

Also: thanks for filing the dsh plugin-install breakage separately as #352 instead of folding it in here.

[timkjr]

Pushed an update (ab83d8f) addressing the scope-creep part of #3: the per-device "Hide CLI buttons" setting is pulled out of this PR entirely (both commits dropped, force-pushed, 14 commits left, all OMP). That was a personal-fork feature of mine that never should have ridden along here — apologies for the noise. I'll bring it back as its own small PR if/when it's ready, with grok/deepseek included in the mode list.

On the other two riders in #3: I'm going to keep those in this PR rather than split them, because they're bug fixes I found live-testing OMP, not features bolted on alongside it — resumeHistorySession() was silently opening a plain Claude session for every non-claude "Resume" click (reproduced with OMP, but it hits opencode/pi/grok/deepseek/codex/gemini/antigravity too), and the DELETE fallback exists to support retiring the stale row that bug leaves behind. I'll fix the gaps you found instead: give codex/gemini/antigravity a continuation flag (or only retire the row when the new session actually continues something), extend findSessionOrFail rather than reimplementing the ownership check inline, and add the missing session_deleted broadcast on the persisted-delete path.

Will follow up with fixes for #1 (mtime-pin correctness bug) and #2 (env clamp) as separate commits, plus the #4 items, shortly.

[timkjr]

Pushed fixes for all four items:

#1 (mtime-pin correctness bug) — c4f6eb1e. Moved session-id resolution out of the eager _buildRespawnPaneOptions() builder (which ran on every boot-recovery reattach regardless of whether the pane was actually dead) into _pinOmpRespawnId(), called only at the two places a respawn is confirmed. Added resolveAndClaimOmpSessionId(): verifies each candidate's own file header (not just the mangled-directory match) and tracks claimed ids in a process-wide registry so two omp tabs in the same case dir can't alias onto each other's conversation.

#2 (env-allowlist claims) — 2ee2eacb. You were right on both counts. Added OMP_AUTH_BROKER_URL/OMP_AUTH_BROKER_TOKEN to the multi-user clamp (same shape DEEPSEEK_BASE_URL gets) and corrected the false "nothing to gate" / "no env override exists" claims in CLAUDE.md, docs/omp-integration.md, and the resolveOmpHome() comment. Also documented the tools.approvalMode: yolo default and the shared PI_* config-root gap (left unfixed — it's pi's pre-existing issue surfacing through the shared prefix, flagged rather than silently widening scope).

#3 (resumeHistorySession + DELETE) — f18dccac. For the missing continuation on codex/gemini/antigravity: rather than guess at whether the unified history list's sessionId reliably carries each CLI's own native conversation id (unverified for those three, unlike omp/claude), I took the safer option you offered — row retirement is now gated on continuesSomething, so those three rows are left alone (duplicate stays) instead of being deleted out from under a conversation with no continuation. DELETE's ownership check is deduplicated into a new findPersistedSessionOrFail() alongside findSessionOrFail(), and the persisted-only delete path now broadcasts session:deleted.

#4 (small items) — 65e994d2. Dead URL, CLI count (ninth backend / tenth SessionMode, not eighth — changeset and docs), OMP_SEARCH_DIRS now leads with ~/.local/bin matching the real installer target, version example updated to the actually-tested 18.0.8, stray comment and the two jammed CSS lines removed, and docs/architecture-invariants.md gets an OMP section (the heading was missing , OMP too, so the anchor CLAUDE.md already linked to was dead).

One thing I did NOT fix, flagged instead: appendResumeFlag()'s case 'omp' for Docker is confirmed unreachable in practice — Docker panes never see ompConfig, only the top-level resumeSessionId, which nothing populates for omp. Host-side history/pinning via the shared sessions/ mount still works; in-container --resume doesn't. Now documented in docs/omp-integration.md's Docker section rather than guessed at.

Full CI-equivalent gate (typecheck/lint/format/frontend-syntax/public-assets/lockfile) plus the full test suite (6330 passed) green after each commit.

One more, found after the above while double-checking the sibling-CLI counts: install.sh never had check_omp/get_omp_path at all — every other CLI (claude/opencode/codex/gemini/antigravity/pi/grok/dsh) has detection wired into the installer, omp didn't. A user with only omp installed would've been told no CLI was found and offered Claude Code/OpenCode instead. Fixed in b6d0f1fa, along with the same missing-DeepSeek-and-OMP gap in the top-level README (English and the existing Chinese translation).