oh-my-codex 0.22.6 → 0.22.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "oh-my-codex",
3
- "version": "0.22.6",
3
+ "version": "0.22.8",
4
4
  "description": "Multi-agent orchestration layer for OpenAI Codex CLI",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "oh-my-codex",
3
- "version": "0.22.6",
3
+ "version": "0.22.8",
4
4
  "description": "Multi-agent orchestration layer for OpenAI Codex CLI",
5
5
  "author": {
6
6
  "name": "Yeachan Heo",
@@ -48,8 +48,7 @@ Keep runtime marker contracts stable and non-destructive when overlays are appli
48
48
 
49
49
  ## Working agreements
50
50
  - For cleanup/refactor/deslop work, write a cleanup plan and lock behavior with regression tests before editing when coverage is missing.
51
- - Prefer deletion, existing utilities, and existing patterns before new abstractions; add dependencies only when explicitly requested.
52
- - Keep diffs small, reviewable, and reversible.
51
+ - Prioritize complete, maintainable repairs within the authorized scope over patch size: correctness, clear ownership, and total complexity rank ahead of diff size. Changes remain reviewable and reversible; unrelated work is excluded. Reuse sound existing patterns after checking them; repair at the owning boundary. Document any temporary mitigations with reason, limitation, and removal condition.
53
52
  - Verify with lint, typecheck, tests, and static analysis after changes; final reports include changed files, simplifications, and remaining risks.
54
53
 
55
54
 
@@ -191,7 +190,7 @@ Output contract: Default update/final shape: state current mode, action/result,
191
190
  Anti-slop workflow:
192
191
  - Cleanup/refactor/deslop work follows the same lightweight workflow (`understand -> execute -> verify -> report`); use `$ai-slop-cleaner` as a bounded helper inside the chosen execution lane, not as a competing top-level workflow.
193
192
  - Write a cleanup plan before modifying code; lock existing behavior with regression tests first, then make one smell-focused pass at a time.
194
- - Prefer deletion over addition, and prefer reuse plus boundary repair over new layers.
193
+ - Prioritize complete, maintainable repairs at the owning boundary ahead of patch minimization: prefer deletion over addition and reuse plus boundary repair over new layers. Temporary mitigations must document their reason, limitation, and removal condition.
195
194
  - No new dependencies without explicit request.
196
195
  - Run lint, typecheck, tests, and static analysis before claiming completion.
197
196
  - Keep writer/reviewer pass separation for cleanup plans and approvals; preserve writer/reviewer pass separation explicitly.
@@ -1,18 +1,18 @@
1
1
  ---
2
- description: "Build and compilation error resolution specialist (minimal diffs, no architecture changes)"
2
+ description: "Build and compilation error resolution specialist (focused, maintainable repairs within build scope; no architecture changes)"
3
3
  argument-hint: "task description"
4
4
  ---
5
5
  <identity>
6
- You are Build Fixer. Your mission is to get a failing build green with the smallest possible changes.
6
+ You are Build Fixer. Your mission is to get a failing build green with complete, maintainable repairs focused on the build scope.
7
7
  You are responsible for fixing type errors, compilation failures, import errors, dependency issues, and configuration errors.
8
8
  You are not responsible for refactoring, performance optimization, feature implementation, architecture changes, or code style improvements.
9
9
 
10
- A red build blocks the entire team. These rules exist because the fastest path to green is fixing the error, not redesigning the system. Build fixers who refactor "while they're in there" introduce new failures and slow everyone down. Fix the error, verify the build, move on.
10
+ A red build blocks the entire team. These rules exist because the fastest path to green is fixing the error, not redesigning the system. Build fixers who refactor "while they're in there" introduce new failures and slow everyone down. Fix the error completely and correctly, verify the build, move on.
11
11
  </identity>
12
12
 
13
13
  <constraints>
14
14
  <scope_guard>
15
- - Fix with minimal diff. Do not refactor, rename variables, add features, optimize, or redesign.
15
+ - Prioritize complete, maintainable repairs within the build scope over patch size: correctness and clarity rank above minimizing diff lines. Do not refactor, rename variables, add features, optimize, or redesign beyond the scope of fixing the build errors.
16
16
  - Do not change logic flow unless it directly fixes the build error.
17
17
  - Detect language/framework from manifest files (package.json, Cargo.toml, go.mod, pyproject.toml) before choosing tools.
18
18
  - Track progress: "X/Y errors fixed" after each fix.
@@ -18,7 +18,7 @@ Deliver finished, verified results while keeping coordination overhead low.
18
18
  <team_posture>
19
19
  - Respect the leader's plan, task boundaries, and lifecycle protocol.
20
20
  - Prefer direct completion over speculative fanout or reframing.
21
- - Treat low-confidence work conservatively: do the smallest correct change first.
21
+ - Prioritize complete, correct execution within task scope over patch minimization. Treat low-confidence work conservatively: understand the scope first, then implement the full correct change.
22
22
  - Preserve explicit user intent when the team was launched with a named agent type.
23
23
  </team_posture>
24
24
 
@@ -33,12 +33,12 @@ Deliver finished, verified results while keeping coordination overhead low.
33
33
  </constraints>
34
34
 
35
35
  <intent>
36
- Treat team tasks as execution requests. Explore enough to understand the assignment, then implement and verify the minimal correct change.
36
+ Treat team tasks as execution requests. Explore enough to understand the assignment, then implement and verify the complete, correct change within scope.
37
37
  </intent>
38
38
 
39
39
  <execution_loop>
40
40
  1. Read the assigned task and current repo state.
41
- 2. Implement the smallest correct change for the assigned lane.
41
+ 2. Implement the complete, correct change for the assigned lane.
42
42
  3. Verify with diagnostics/tests relevant to the touched area.
43
43
  4. Report concrete evidence back to the leader.
44
44
 
@@ -53,7 +53,7 @@ Use role to choose responsibility, tier to choose depth, and posture to choose o
53
53
 
54
54
  - `deep-worker`:
55
55
  - Best for implementation-heavy roles that should carry work to completion.
56
- - Prioritizes direct execution, minimal diffs, and strict verification.
56
+ - Prioritizes complete, maintainable repairs within scope; correctness and clarity ahead of patch minimization. Includes strict verification.
57
57
  - Typical roles: `executor`, `debugger`, `test-engineer`, `build-fixer`.
58
58
 
59
59
  - `fast-lane`:
@@ -0,0 +1,203 @@
1
+ import assert from "node:assert/strict";
2
+ import { mkdir, mkdtemp, readFile, rm, utimes, writeFile } from "node:fs/promises";
3
+ import { tmpdir } from "node:os";
4
+ import { join } from "node:path";
5
+ import { afterEach, describe, it } from "node:test";
6
+ import { dispatchCodexNativeHook } from "../codex-native-hook.js";
7
+ import { initTeamState, writeWorkerIdentity } from "../../team/state.js";
8
+
9
+ const roots: string[] = [];
10
+ afterEach(async () => {
11
+ await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
12
+ });
13
+
14
+ async function workspace(): Promise<string> {
15
+ const cwd = await mkdtemp(join(tmpdir(), "omx-issue-4086-stop-hook-lock-"));
16
+ roots.push(cwd);
17
+ return cwd;
18
+ }
19
+
20
+ async function staleLock(lockDir: string, token?: string): Promise<void> {
21
+ await mkdir(lockDir, { recursive: true });
22
+ if (token !== undefined) await writeFile(join(lockDir, 'owner'), token);
23
+ await writeFile(join(lockDir, 'lease'), 'abandoned');
24
+ const old = new Date(Date.now() - 10 * 60_000);
25
+ await utimes(join(lockDir, 'lease'), old, old);
26
+ await utimes(lockDir, old, old);
27
+ }
28
+
29
+ describe('issue #4086: stop hook with stale team lock', () => {
30
+ it('stop hook with stale team lock should return continue:false (terminal)', async () => {
31
+ const cwd = await workspace();
32
+ const team = 'audit';
33
+ const workerName = 'executor-1';
34
+
35
+ // Initialize team state
36
+ await initTeamState(team, 'stop hook lock test', 'executor', 1, cwd);
37
+
38
+ // Write worker identity to make this appear as a team worker
39
+ await writeWorkerIdentity(team, workerName, {
40
+ name: workerName,
41
+ index: 1,
42
+ role: 'executor',
43
+ assigned_tasks: [],
44
+ }, cwd);
45
+
46
+ // Create a stale team membership lock
47
+ const lockDir = join(cwd, '.omx/state/.team-locks', `${team}.membership`);
48
+ const staleLockToken = '99999999.0.dead';
49
+ await staleLock(lockDir, staleLockToken);
50
+
51
+ // Set up environment to identify as a team worker
52
+ const originalEnv = process.env;
53
+ process.env.OMX_TEAM_WORKER_NAME = workerName;
54
+ process.env.OMX_TEAM_WORKER_TEAM_NAME = team;
55
+ process.env.OMX_TEAM_WORKER_TEAM_LEADER = 'leader-1';
56
+ process.env.OMX_TEAM_WORKER_INTERNAL_CANONICAL = 'true';
57
+
58
+ try {
59
+ // Invoke Stop hook while team has a stale lock
60
+ const result = await dispatchCodexNativeHook(
61
+ {
62
+ hook_event_name: "Stop",
63
+ cwd,
64
+ session_id: "test-stop-hook",
65
+ stop_hook_active: false,
66
+ },
67
+ { cwd },
68
+ );
69
+
70
+ // Exact assertions for terminal output: continue:false, no decision, no reason
71
+ assert.ok(result.outputJson, 'outputJson must be present');
72
+ const outputJson = result.outputJson as Record<string, unknown>;
73
+
74
+ assert.strictEqual(
75
+ outputJson.continue,
76
+ false,
77
+ 'continue must be false to make Stop terminal'
78
+ );
79
+
80
+ assert.strictEqual(
81
+ outputJson.decision,
82
+ undefined,
83
+ 'decision must be undefined for terminal output (no decision property)'
84
+ );
85
+
86
+ assert.strictEqual(
87
+ outputJson.reason,
88
+ undefined,
89
+ 'reason must be undefined so model never receives recovery instructions'
90
+ );
91
+
92
+ assert.strictEqual(
93
+ outputJson.stopReason,
94
+ 'team_lock_recovery_required',
95
+ 'stopReason must identify the lock recovery issue'
96
+ );
97
+
98
+ // Recovery steps must be only in systemMessage, never exposed to model as decision/reason
99
+ const systemMessage = String(outputJson.systemMessage || '');
100
+ assert.ok(
101
+ systemMessage.length > 0,
102
+ 'systemMessage must contain recovery instructions'
103
+ );
104
+ assert.ok(
105
+ systemMessage.includes('stale lock') || systemMessage.includes(lockDir),
106
+ 'systemMessage must describe the stale lock location'
107
+ );
108
+ } finally {
109
+ process.env = originalEnv;
110
+ }
111
+ });
112
+
113
+ it('two consecutive Stop invocations are both terminal with lock preserved', async () => {
114
+ const cwd = await workspace();
115
+ const team = 'audit';
116
+ const workerName = 'executor-1';
117
+
118
+ // Initialize team state
119
+ await initTeamState(team, 'lock preservation test', 'executor', 1, cwd);
120
+
121
+ const lockDir = join(cwd, '.omx/state/.team-locks', `${team}.membership`);
122
+ const staleLockToken = '99999999.0.dead';
123
+ await staleLock(lockDir, staleLockToken);
124
+
125
+ // Write worker identity
126
+ await writeWorkerIdentity(team, workerName, {
127
+ name: workerName,
128
+ index: 1,
129
+ role: 'executor',
130
+ assigned_tasks: [],
131
+ }, cwd);
132
+
133
+ const originalEnv = process.env;
134
+ process.env.OMX_TEAM_WORKER_NAME = workerName;
135
+ process.env.OMX_TEAM_WORKER_TEAM_NAME = team;
136
+ process.env.OMX_TEAM_WORKER_TEAM_LEADER = 'leader-1';
137
+ process.env.OMX_TEAM_WORKER_INTERNAL_CANONICAL = 'true';
138
+
139
+ try {
140
+ // First Stop invocation
141
+ const result1 = await dispatchCodexNativeHook(
142
+ {
143
+ hook_event_name: "Stop",
144
+ cwd,
145
+ session_id: "test-stop-hook-1",
146
+ stop_hook_active: false,
147
+ },
148
+ { cwd },
149
+ );
150
+
151
+ assert.ok(result1.outputJson, 'First Stop result must have outputJson');
152
+ const output1 = result1.outputJson as Record<string, unknown>;
153
+ assert.strictEqual(
154
+ output1.continue,
155
+ false,
156
+ 'First Stop must have continue:false (terminal)'
157
+ );
158
+ assert.strictEqual(
159
+ output1.stopReason,
160
+ 'team_lock_recovery_required',
161
+ 'First Stop must identify lock recovery reason'
162
+ );
163
+
164
+ // Verify lock state is preserved after first Stop
165
+ let owner = await readFile(join(lockDir, 'owner'), 'utf8');
166
+ let lease = await readFile(join(lockDir, 'lease'), 'utf8');
167
+ assert.strictEqual(owner, staleLockToken, 'Lock owner must be preserved after first Stop');
168
+ assert.strictEqual(lease, 'abandoned', 'Lock lease must be preserved after first Stop');
169
+
170
+ // Second Stop invocation (simulating operator retrying after fixing)
171
+ const result2 = await dispatchCodexNativeHook(
172
+ {
173
+ hook_event_name: "Stop",
174
+ cwd,
175
+ session_id: "test-stop-hook-2",
176
+ stop_hook_active: false,
177
+ },
178
+ { cwd },
179
+ );
180
+
181
+ assert.ok(result2.outputJson, 'Second Stop result must have outputJson');
182
+ const output2 = result2.outputJson as Record<string, unknown>;
183
+ assert.strictEqual(
184
+ output2.continue,
185
+ false,
186
+ 'Second Stop must have continue:false (terminal)'
187
+ );
188
+ assert.strictEqual(
189
+ output2.stopReason,
190
+ 'team_lock_recovery_required',
191
+ 'Second Stop must identify lock recovery reason'
192
+ );
193
+
194
+ // Verify lock state is still preserved
195
+ owner = await readFile(join(lockDir, 'owner'), 'utf8');
196
+ lease = await readFile(join(lockDir, 'lease'), 'utf8');
197
+ assert.strictEqual(owner, staleLockToken, 'Lock owner must be preserved after second Stop');
198
+ assert.strictEqual(lease, 'abandoned', 'Lock lease must be preserved after second Stop');
199
+ } finally {
200
+ process.env = originalEnv;
201
+ }
202
+ });
203
+ });
@@ -2933,9 +2933,18 @@ async function resolveTeamStateDirForWorkerContext(
2933
2933
  cwd: string,
2934
2934
  workerContext: { teamName: string; workerName: string },
2935
2935
  ): Promise<string | null> {
2936
- const resolved = await resolveWorkerTeamStateRootPath(cwd, workerContext, process.env).catch(() => null);
2937
- if (resolved) return resolved;
2938
- return null;
2936
+ try {
2937
+ const resolved = await resolveWorkerTeamStateRootPath(cwd, workerContext, process.env);
2938
+ if (resolved) return resolved;
2939
+ return null;
2940
+ } catch (error) {
2941
+ // Re-throw team lock recovery errors so they're handled by the Stop hook error handler
2942
+ if (error instanceof Error && error.message.includes('team_lock_recovery_required')) {
2943
+ throw error;
2944
+ }
2945
+ // Suppress other errors (state root resolution failures)
2946
+ return null;
2947
+ }
2939
2948
  }
2940
2949
 
2941
2950
  async function isConfirmedTeamWorkerPromptSubmitPane(cwd: string): Promise<boolean> {
@@ -22891,41 +22900,51 @@ export async function dispatchCodexNativeHook(
22891
22900
  }
22892
22901
  outputJson ??= buildNativePostToolUseOutput(payload);
22893
22902
  } else if (hookEventName === "Stop") {
22894
- if (declaredTeamWorkerStopOnly) {
22895
- outputJson = await buildStopHookOutput(payload, cwd, stateDir, { teamWorkerOnly: true });
22896
- } else if (allowImplicitSessionSideEffects) {
22897
- const stopOutput = await buildStopHookOutput(payload, cwd, stateDir, {
22898
- canonicalSessionId: canonicalSessionId || undefined,
22899
- skipRalphStopBlock: isSubagentStop,
22900
- skipAutoNudge: isSubagentStop,
22901
- sessionScopedOnly: !allowGlobalSideEffects,
22902
- });
22903
- // Record bounded completion evidence for native subagent Stop events
22904
- if (isSubagentStop) {
22905
- const threadId = readPayloadThreadId(payload);
22906
- if (canonicalSessionId?.trim() && threadId?.trim()) {
22907
- await recordSubagentTurnForSession(cwd, {
22908
- sessionId: canonicalSessionId.trim(),
22909
- threadId: threadId.trim(),
22910
- turnId: readPayloadTurnId(payload) || undefined,
22911
- completed: true,
22912
- completionSource: 'native_stop_event',
22913
- timestamp: new Date().toISOString(),
22914
- }).catch(() => {});
22903
+ try {
22904
+ if (declaredTeamWorkerStopOnly) {
22905
+ outputJson = await buildStopHookOutput(payload, cwd, stateDir, { teamWorkerOnly: true });
22906
+ } else if (allowImplicitSessionSideEffects) {
22907
+ const stopOutput = await buildStopHookOutput(payload, cwd, stateDir, {
22908
+ canonicalSessionId: canonicalSessionId || undefined,
22909
+ skipRalphStopBlock: isSubagentStop,
22910
+ skipAutoNudge: isSubagentStop,
22911
+ sessionScopedOnly: !allowGlobalSideEffects,
22912
+ });
22913
+ // Record bounded completion evidence for native subagent Stop events
22914
+ if (isSubagentStop) {
22915
+ const threadId = readPayloadThreadId(payload);
22916
+ if (canonicalSessionId?.trim() && threadId?.trim()) {
22917
+ await recordSubagentTurnForSession(cwd, {
22918
+ sessionId: canonicalSessionId.trim(),
22919
+ threadId: threadId.trim(),
22920
+ turnId: readPayloadTurnId(payload) || undefined,
22921
+ completed: true,
22922
+ completionSource: 'native_stop_event',
22923
+ timestamp: new Date().toISOString(),
22924
+ }).catch(() => {});
22925
+ }
22915
22926
  }
22927
+ outputJson = stopOutput ?? (
22928
+ allowGlobalSideEffects
22929
+ ? await buildCompletedGoalCleanupStopOutput(payload, cwd)
22930
+ : null
22931
+ );
22932
+ } else {
22933
+ // Authorization failure never grants continuation authority. It also must not
22934
+ // inject a repair request: the same provenance failure can deny every tool the
22935
+ // model would need to repair it, turning a Stop denial into an unbounded loop.
22936
+ // Returning no hook output permits termination while preserving the denial of
22937
+ // all session-scoped and global side effects above.
22938
+ outputJson = null;
22939
+ }
22940
+ } catch (err) {
22941
+ // Handle errors from Stop hook processing, particularly manual recovery errors
22942
+ // like team_lock_recovery_required that should not result in continuation
22943
+ if (isTeamLockRecoveryRequiredError(err)) {
22944
+ outputJson = buildTeamLockRecoveryStopOutput(err);
22945
+ } else {
22946
+ throw err;
22916
22947
  }
22917
- outputJson = stopOutput ?? (
22918
- allowGlobalSideEffects
22919
- ? await buildCompletedGoalCleanupStopOutput(payload, cwd)
22920
- : null
22921
- );
22922
- } else {
22923
- // Authorization failure never grants continuation authority. It also must not
22924
- // inject a repair request: the same provenance failure can deny every tool the
22925
- // model would need to repair it, turning a Stop denial into an unbounded loop.
22926
- // Returning no hook output permits termination while preserving the denial of
22927
- // all session-scoped and global side effects above.
22928
- outputJson = null;
22929
22948
  }
22930
22949
  }
22931
22950
 
@@ -23194,7 +23213,36 @@ function isPostCancelCommitTestTrigger(payload: CodexHookPayload, output: Record
23194
23213
  }
23195
23214
 
23196
23215
 
23216
+ function isTeamLockRecoveryRequiredError(error: unknown): boolean {
23217
+ if (!(error instanceof Error)) return false;
23218
+ return error.message.includes('team_lock_recovery_required');
23219
+ }
23220
+
23221
+ function extractTeamLockDirFromError(error: unknown): string | null {
23222
+ if (!(error instanceof Error)) return null;
23223
+ const match = error.message.match(/team_lock_recovery_required:([^:]+):/);
23224
+ return match ? match[1] : null;
23225
+ }
23226
+
23227
+ function buildTeamLockRecoveryStopOutput(error: unknown): Record<string, unknown> {
23228
+ const lockDir = extractTeamLockDirFromError(error);
23229
+ const systemMessage = lockDir
23230
+ ? `OMX Stop terminal: stale team lock at ${lockDir} requires manual recovery. ` +
23231
+ `Confirm no other operations are accessing the lock, then remove: rm -rf "${lockDir}"`
23232
+ : `OMX Stop terminal: stale team lock requires manual recovery.`;
23233
+ return {
23234
+ continue: false,
23235
+ stopReason: "team_lock_recovery_required",
23236
+ systemMessage,
23237
+ };
23238
+ }
23239
+
23197
23240
  function buildStopDispatchFailureOutput(error: unknown): Record<string, unknown> {
23241
+ // Check if this is a manual recovery error that should be treated as terminal
23242
+ if (isTeamLockRecoveryRequiredError(error)) {
23243
+ return buildTeamLockRecoveryStopOutput(error);
23244
+ }
23245
+
23198
23246
  const detail = error instanceof Error ? error.message : String(error);
23199
23247
  const reason =
23200
23248
  "OMX native Stop hook failed before normal continuation handling. Continue once more, preserve runtime state, inspect the hook logs, and retry with a valid Stop JSON response.";
@@ -48,8 +48,7 @@ Keep runtime marker contracts stable and non-destructive when overlays are appli
48
48
 
49
49
  ## Working agreements
50
50
  - For cleanup/refactor/deslop work, write a cleanup plan and lock behavior with regression tests before editing when coverage is missing.
51
- - Prefer deletion, existing utilities, and existing patterns before new abstractions; add dependencies only when explicitly requested.
52
- - Keep diffs small, reviewable, and reversible.
51
+ - Prioritize complete, maintainable repairs within the authorized scope over patch size: correctness, clear ownership, and total complexity rank ahead of diff size. Changes remain reviewable and reversible; unrelated work is excluded. Reuse sound existing patterns after checking them; repair at the owning boundary. Document any temporary mitigations with reason, limitation, and removal condition.
53
52
  - Verify with lint, typecheck, tests, and static analysis after changes; final reports include changed files, simplifications, and remaining risks.
54
53
 
55
54
 
@@ -191,7 +190,7 @@ Output contract: Default update/final shape: state current mode, action/result,
191
190
  Anti-slop workflow:
192
191
  - Cleanup/refactor/deslop work follows the same lightweight workflow (`understand -> execute -> verify -> report`); use `$ai-slop-cleaner` as a bounded helper inside the chosen execution lane, not as a competing top-level workflow.
193
192
  - Write a cleanup plan before modifying code; lock existing behavior with regression tests first, then make one smell-focused pass at a time.
194
- - Prefer deletion over addition, and prefer reuse plus boundary repair over new layers.
193
+ - Prioritize complete, maintainable repairs at the owning boundary ahead of patch minimization: prefer deletion over addition and reuse plus boundary repair over new layers. Temporary mitigations must document their reason, limitation, and removal condition.
195
194
  - No new dependencies without explicit request.
196
195
  - Run lint, typecheck, tests, and static analysis before claiming completion.
197
196
  - Keep writer/reviewer pass separation for cleanup plans and approvals; preserve writer/reviewer pass separation explicitly.