Race-condition and concurrency fixes must include reporter-verified repro confirmation before the originating issue is closed. Adds the checklist and rationale grounded in recent incident examples.
Closes MEDIUM-12
Documents the reservation-based duplicate-injection guard introduced in v4.2.0 with accepted status, exported API signatures, release semantics, migration notes, and commit references.
Closes MEDIUM-11
PR #3825 introduced a delegated child-session bootstrap to capture first-prompt retry payloads before history is persisted, addressing the empty-history fallback gap. After merge the PR's own regression test failed on clean root bun test (6828 pass / 1 fail), so PR #4044 reverted it. Ship v4.2.0 with the bug documented and a workaround so users have an explicit story for the unfixed delegated child-session early-failure path. Reland will target v4.2.1.
Closes BLOCKER-4 (Path B - reland deferred to v4.2.1)
PR #3825 added a shared bootstrap context to capture delegated
child-session retry payloads before the first prompt dispatch, so
empty-history failures could still retry through the fallback chain.
The PR's own regression test failed on clean root bun test after merge
(6828 pass / 1 fail). PR #4044 reverted the merge to keep dev green.
Ship v4.2.0 with the bug documented and a workaround so users have an
explicit story for the unfixed delegated child-session early-failure
path. Reland targets v4.2.1 once the regression test is stabilized.
Closes BLOCKER-4 (Path B - documentation, reland deferred to v4.2.1)
Race-condition and concurrency fixes must include reporter-verified repro
confirmation before the originating issue is closed. CI green is necessary
but not sufficient.
Closes M12
PR #3825's fac90d69f introduced a shared bootstrap context to fix delegated child-session fallback when the first prompt fails before any session history is persisted. PR #4044 reverted that fix because its own regression test failed on a clean root suite (6828 pass / 1 fail). The bug remains unaddressed in v4.2.0; reland is deferred.
This commit documents the symptom, history, workaround, and tracking issue so users have visibility.
Closes BLOCKER-4 via Path B (documentation).
Refs PR #3825, PR #4044, issue #4059.
PR #3825 introduced a delegated child-session bootstrap to capture first-prompt retry payloads before history is persisted, addressing the empty-history fallback gap. After merge the PR's own regression test failed on clean root bun test (6828 pass / 1 fail), so PR #4044 reverted it. Ship v4.2.0 with the bug documented and a workaround so users have an explicit story for the unfixed delegated child-session early-failure path. Reland will target v4.2.1.
Closes BLOCKER-4 (Path B - reland deferred to v4.2.1)
Follow-up pass to catch drift my earlier docs commit missed:
docs/reference/features.md:
- 'Architecture Snapshot': 5-tier hook composition '52 base / 59 with team mode'
to '54 base / 61 with team mode' (matches actual ToolGuard +2 from
fsync-skip-warning + bash-file-read-guard).
docs/reference/cli.md:
- Add 'boulder' subcommand to Commands table (inspects boulder work-state).
docs/reference/configuration.md:
- Code comment example 'Kimi K2.5 work best' to 'Kimi K2.6 work best' to match
current primary Sisyphus fallback chain.
docs/guide/installation.md:
- Add 'Kimi K2.6 (opencode-go, vercel)' row to the provider availability table
above the existing K2.5 row.
- Selection priority footnote and 'Safe Overrides' chains updated to mention
K2.6 alongside K2.5 in Sisyphus and Atlas chains.
docs/guide/agent-model-matching.md:
- Provider table 'Kimi K2.5' row to 'Kimi K2.6 / K2.5'.
- Atlas fallback chain mentions K2.6 instead of K2.5 alone.
Align README.md, CONTRIBUTING.md, and docs/ with the same ground truth used
in the hierarchical AGENTS.md regeneration commit 1e7a7600a:
- README.md: '25+ built-in hooks' was undercounted by ~30 hooks; now reads
'54+ lifecycle hooks (61 with Team Mode)' to match actual tier composition.
- CONTRIBUTING.md: src/hooks/ '52 hooks across 55 modules' -> '54 base (61 team) across 58 dirs';
src/tools/ '26 tools across 16 directories' -> '20-39 tools (config-gated)';
src/features/ '19 feature modules' -> '20 feature modules' (boulder-state, team-mode added).
- docs/reference/features.md: Core-agent order indices were off-by-one;
Sisyphus 1/Hephaestus 2/Prometheus 3/Atlas 4 -> 0/1/2/3 (matches installAgentSortShim).
- docs/guide/overview.md: Sisyphus model recommendations now mention Kimi K2.6 alongside K2.5
since K2.6 is the active default fallback in the primary Sisyphus chain
(see src/shared/model-requirements.ts).
The manifesto's project-context block carried the typo `oh-my-openagent.com`.
The actual canonical domain has no dashes:
- DNS: `ohmyopenagent.com` resolves (Cloudflare).
- DNS: `oh-my-openagent.com` does not resolve.
- web/wrangler.toml routes ohmyopenagent.com + ohmyopencode.org.
- web/middleware.ts redirects ohmyopencode.org -> ohmyopenagent.com.
Same fix for the legacy alias (ohmyopencode.org, also no dashes) plus an
explicit note that the legacy host 308-redirects to the canonical one so
nobody pastes the dashed form anywhere.
The project-context block had been sitting as a stale local working-tree
edit from earlier audit work and never landed on dev. Promoting it as a
clean commit so the manifesto carries the same project-context summary
the README does.
In #3859 I bulk-replaced `oh-my-opencode.schema.json` ->
`oh-my-openagent.schema.json` across docs/, on the false assumption
that the schema file had been renamed alongside the package.
It hadn't. Repo state on dev:
- assets/oh-my-opencode.schema.json (only file present)
- package.json export `./schema.json` -> `./dist/oh-my-opencode.schema.json`
- script/build-schema.ts emits the same legacy basename
- root AGENTS.md line 135 documents the same legacy URL
So every doc that pointed at `oh-my-openagent.schema.json` was
returning HTTP 404 for any user copying the example into their config.
Verified live:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json -> 404
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json -> 200
Files reverted to canonical legacy URL:
- docs/examples/{coding,default,planning}-focused.jsonc
- docs/guide/{overview,installation,agent-model-matching}.md
- docs/reference/configuration.md (2 occurrences)
Hephaestus's fallbackChain in src/shared/model-requirements.ts has a
single entry: gpt-5.5. The previous wording said "GPT-5.4/5.5" which
implied either was acceptable; only gpt-5.5 is. Note OpenAI API access
as an alternative to ChatGPT Plus/Pro for clarity.
Audit pass against root AGENTS.md (regenerated 2026-05-08) and the
canonical sources in src/shared/model-requirements.ts,
src/features/team-mode/, src/cli/, src/config/schema/. Each touched file
keeps its existing tone but corrects stale facts:
- guide/overview.md: project name + dual-package transition reality
- guide/installation.md: bun-only invocation, dual oh-my-openagent /
oh-my-opencode CLI surface, current doctor categories
- guide/orchestration.md: 11 agents, category routing through
sisyphus-junior, background concurrency, team-mode link
- guide/agent-model-matching.md: Metis primary -> claude-sonnet-4-6
(matches src/shared/model-requirements.ts fallback chain)
- guide/team-mode.md: full schema, member eligibility tiers, 12 team_*
tools added when enabled
- reference/cli.md: trim to current Commander surface (install, doctor,
run, mcp-oauth, refresh-model-capabilities, get-local-version)
- reference/configuration.md: trim to schema-driven reference, JSONC
rules, multi-level merge order, mcp_env_allowlist user-only constraint
- reference/features.md: 5-tier hook composition counts, 3-tier MCPs,
hashline edit, IntentGate, OpenClaw bidirectional dispatcher
Cross-cutting: every `oh-my-opencode.schema.json` URL replaced with
the canonical `oh-my-openagent.schema.json` (legacy package name in
text bodies preserved where it documents the dual-publish transition).
Source code change:
- src/shared/model-requirements.ts: prepend claude-sonnet-4-6 to metis fallback
chain so Sonnet becomes the default. Opus 4.7 max remains as the immediate
fallback for callers who want extra reasoning.
- src/shared/model-requirements.test.ts: update assertion to expect Sonnet
primary + Opus secondary.
AGENTS.md accuracy fixes (verified against source):
- Agent modes: Sisyphus/Hephaestus are 'primary' (not 'all'); Sisyphus-Junior
is 'subagent' (not 'all'). Confirmed via 'const MODE: AgentMode = ...' in
each agent file. Also clarified Prometheus has no agentSources factory and
is built via buildPrometheusAgentConfig.
- Sisyphus fallback chain: corrected order to kimi-k2.6 → k2p5 → kimi-k2.5
→ gpt-5.5 medium → glm-5 → big-pickle (was missing kimi-k2.5).
- Librarian/Explore: added missing minimax-m2.7 step between -highspeed and
claude-haiku-4-5.
- Metis chain: removed fictitious gemini-3.1-pro entry.
- Sisyphus-Junior chain: spelled out the actual fallback (was 'user-configurable').
- Temperatures: Sisyphus/Hephaestus do not set explicit temperature (model
default); Sisyphus-Junior is 0.1 via SISYPHUS_JUNIOR_DEFAULTS.
- Quick category default: gpt-5.4-mini (not gpt-5.4-mini-fast).
Team-mode corrections:
- Eligibility registry has 3 verdicts: eligible (sisyphus, atlas, sisyphus-junior),
conditional (hephaestus — needs D-36 teammate permission), hard-reject
(oracle, librarian, explore, multimodal-looker, metis, momus, prometheus).
- Schema has 11 fields, not 4: added max_messages_per_run, max_wall_clock_minutes,
max_member_turns, base_dir, message_payload_max_bytes, recipient_unread_max_bytes,
mailbox_poll_interval_ms.
- Hooks: 'team-session-events' is 4 sub-handlers in src/plugin/event.ts
(team-idle-wake-hint, team-lead-orphan-handler, team-member-error-handler,
team-member-status-handler), not a single Continuation-tier hook.
- Tier counts now show base + team-mode: ToolGuard 14/15, Transform 5/7.
- Total: 52 base hooks, 59 with team-mode.
Doc cascade for the Metis change:
- docs/guide/orchestration.md, agent-model-matching.md, installation.md
- docs/reference/configuration.md, features.md
The caller-facing description told orchestrators WHAT `deep` is but
never specified goal cardinality, so they bundled multiple goals into
one call (e.g. "fix X + merge Y + deploy Z"). The deep agent's own
prompt was already configured to refuse such bundles, but only after
they arrived. The rule now lives on the caller side: ONE goal + ONE
deliverable per call; multiple goals must fan out as parallel `deep`
calls.
The documented chains were missing entries and had wrong providers:
- Librarian was missing openai/gpt-5.4-mini-fast, vercel/minimax-m2.7-highspeed,
and the last two entries. Also had opencode/ instead of vercel/ for
minimax-m2.7-highspeed.
- Explore had github-copilot|xai/grok-code-fast-1 as primary (which doesn't
exist in the fallback chain) and was missing openai/gpt-5.4-mini-fast.
Both now match the exact runtime chains from model-requirements.ts.
Update the README quick-overview bullet and the dedicated File Locations
section in docs/reference/configuration.md to describe the walk-up
behaviour added in #417: configs under `.opencode/` are discovered by
walking from the working directory up to $HOME, with closer configs
winning.
Includes a hierarchical example (`~/.config/opencode/` global,
`~/work/.opencode/` work overrides, repo-specific overrides under that)
and a security note explaining why `mcp_env_allowlist` remains
extensible only from the canonical user config.
YeonGyu-Kim