codex-orchestrator 0.1.23 → 0.1.25

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.
Files changed (40) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +136 -282
  3. package/dist/src/config/schema.d.ts +26 -0
  4. package/dist/src/config/schema.d.ts.map +1 -1
  5. package/dist/src/config/schema.js +54 -0
  6. package/dist/src/config/schema.js.map +1 -1
  7. package/dist/src/runner/daemon-command.d.ts.map +1 -1
  8. package/dist/src/runner/daemon-command.js +25 -1
  9. package/dist/src/runner/daemon-command.js.map +1 -1
  10. package/dist/src/runner/durable-run-summary.d.ts +41 -0
  11. package/dist/src/runner/durable-run-summary.d.ts.map +1 -0
  12. package/dist/src/runner/durable-run-summary.js +66 -0
  13. package/dist/src/runner/durable-run-summary.js.map +1 -0
  14. package/dist/src/runner/fresh-context-review.d.ts +22 -0
  15. package/dist/src/runner/fresh-context-review.d.ts.map +1 -0
  16. package/dist/src/runner/fresh-context-review.js +157 -0
  17. package/dist/src/runner/fresh-context-review.js.map +1 -0
  18. package/dist/src/runner/handoff-evidence.d.ts +16 -0
  19. package/dist/src/runner/handoff-evidence.d.ts.map +1 -1
  20. package/dist/src/runner/handoff-evidence.js +62 -0
  21. package/dist/src/runner/handoff-evidence.js.map +1 -1
  22. package/dist/src/runner/plan-auto-command.d.ts.map +1 -1
  23. package/dist/src/runner/plan-auto-command.js +134 -28
  24. package/dist/src/runner/plan-auto-command.js.map +1 -1
  25. package/dist/src/runner/review-gate-policy.d.ts.map +1 -1
  26. package/dist/src/runner/review-gate-policy.js +14 -2
  27. package/dist/src/runner/review-gate-policy.js.map +1 -1
  28. package/dist/src/runner/rework-policy.d.ts +3 -0
  29. package/dist/src/runner/rework-policy.d.ts.map +1 -0
  30. package/dist/src/runner/rework-policy.js +20 -0
  31. package/dist/src/runner/rework-policy.js.map +1 -0
  32. package/dist/src/runner/scoped-auto-command.d.ts.map +1 -1
  33. package/dist/src/runner/scoped-auto-command.js +99 -27
  34. package/dist/src/runner/scoped-auto-command.js.map +1 -1
  35. package/dist/src/setup/project-config.d.ts.map +1 -1
  36. package/dist/src/setup/project-config.js +58 -0
  37. package/dist/src/setup/project-config.js.map +1 -1
  38. package/docs/deep-dive.md +364 -0
  39. package/package.json +2 -1
  40. package/prompts/workflows/scoped-implementation.md +9 -3
package/CHANGELOG.md CHANGED
@@ -6,6 +6,26 @@ The format is based on Keep a Changelog, and this project follows SemVer.
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.1.25] - 2026-05-15
10
+
11
+ ### Added
12
+ - Runner-owned Loop Policy controls for daemon priority selection, bounded
13
+ rework, optional Fresh-Context Review, Durable Run Summaries, and
14
+ non-mutating Policy Suggestions.
15
+
16
+ ### Changed
17
+ - Scoped and issue-tree handoff reports now include stronger runner-owned
18
+ evidence before draft PR publication, while keeping GitHub publication,
19
+ labels, comments, merges, releases, and deploys outside Agent authority.
20
+
21
+ ## [0.1.24] - 2026-05-14
22
+
23
+ ### Changed
24
+ - Mobile UI verification guidance now gives an explicit adb/emulator preflight
25
+ for Android mobile app work, prefers a connected device before emulator
26
+ fallback, tells agents to try loading Test Android Apps when unavailable, and
27
+ treats missing plugin/device targets as a warning rather than a blocker.
28
+
9
29
  ## [0.1.23] - 2026-05-14
10
30
 
11
31
  ### Added
package/README.md CHANGED
@@ -1,162 +1,94 @@
1
1
  # codex-orchestrator
2
2
 
3
- `codex-orchestrator` is a reusable GitHub Issues runner for Codex.
3
+ `codex-orchestrator` turns GitHub Issues into controlled Codex work.
4
4
 
5
- It lets a maintainer turn selected GitHub Issues into controlled Codex work:
6
- the runner prepares an isolated workspace, gives Codex the issue context and
7
- project policy, checks the result, and hands the work back as a reviewable draft
8
- pull request.
5
+ Instead of starting a new Codex chat for every issue, you label the work you
6
+ want automated. The runner creates an isolated workspace, gives Codex the issue
7
+ and your repo rules, checks the result, and hands it back as a draft pull
8
+ request.
9
9
 
10
- For larger features, it can start from one parent issue, ask Codex to plan the
11
- work, create or update child issues, run the safe child issues in dependency
12
- order, and open one integration draft PR.
10
+ For bigger features, it can start from one parent issue, ask Codex to plan the
11
+ work, create or update child issues, run the safe children in order, and open
12
+ one integration draft PR.
13
13
 
14
- The package is designed to be installed into any repository. The generic
15
- orchestration lives in this npm package; each target repository keeps its own
16
- policy in `.codex-orchestrator/`.
14
+ The package is installed into any repository. The reusable runner lives in this
15
+ npm package; each target repository keeps its own rules in
16
+ `.codex-orchestrator/`.
17
17
 
18
- ## Why Use It
18
+ For a technical walkthrough of the runner lifecycle, policy model, review
19
+ gates, and recovery behavior, see [docs/deep-dive.md](docs/deep-dive.md).
19
20
 
20
- Codex is useful for implementation work, but coordinating it manually does not
21
- scale well:
21
+ ## Why This Exists
22
22
 
23
- - a maintainer has to start a new chat for every small issue;
24
- - large features need PRD, issue breakdown, triage, child issue execution, and
25
- final integration;
26
- - concurrent agent work can conflict if multiple tasks touch the same files;
27
- - agents should not decide by themselves which linked issues are authorized;
28
- - publication should be consistent: branch, commit, push, and pull request
29
- creation should follow one project policy;
30
- - humans still need review control before anything is merged.
23
+ Codex can write useful code, but running it manually gets messy fast:
31
24
 
32
- `codex-orchestrator` solves the coordination layer. GitHub Issues become the
33
- work queue, GitHub labels become the state machine, isolated worktrees become
34
- the agent workspaces, and draft pull requests become the handoff point back to
35
- humans.
25
+ - every small issue needs a new chat and repeated context;
26
+ - large features need planning, child issues, triage, execution, and final
27
+ integration;
28
+ - parallel agent work can conflict when tasks touch the same files;
29
+ - someone still needs to decide what is allowed, what is blocked, and what needs
30
+ review;
31
+ - branches, commits, checks, PRs, and labels should follow one project policy.
36
32
 
37
- ## Feature Overview
33
+ `codex-orchestrator` is the coordination layer.
38
34
 
39
- `codex-orchestrator` is designed for maintainers who want Codex to do useful
40
- work without giving up control of the repository.
35
+ GitHub Issues become the work queue. Labels decide what Codex may run. Isolated
36
+ worktrees keep runs separate. Review gates check the result. Draft PRs return
37
+ control to humans before anything is merged.
41
38
 
42
- ### Issue-Driven Work Queue
39
+ ## What You Get
43
40
 
44
- GitHub Issues are the source of truth. A maintainer adds `agent:auto` to one
45
- issue, or `agent:plan-auto` to a larger parent issue. The runner only starts
46
- issues that are explicitly authorized and skips issues that are manual, blocked,
47
- already running, already under review, or closed.
41
+ - A repeatable way to send selected GitHub Issues to Codex.
42
+ - One-off autonomous runs for scoped implementation tasks.
43
+ - Parent planning for larger features, with child issues executed in safe waves.
44
+ - Project-owned rules for labels, branches, prompts, checks, review gates, and
45
+ blocked actions.
46
+ - Full change-set checks, including local commits, staged files, unstaged files,
47
+ and untracked files.
48
+ - Durable logs and summaries when a run is interrupted, blocked, or ready for
49
+ review.
50
+ - Draft PR handoff by default. No auto-merge.
48
51
 
49
- ### Scoped Autonomous Issues
52
+ ## How It Works
50
53
 
51
- Use `agent:auto` for one well-scoped task. The runner creates a branch and
52
- worktree, runs Codex with the issue context, validates the work, then opens a
53
- draft PR for human review.
54
-
55
- Codex may change files and, when project policy allows it, make local commits in
56
- the issue branch. The runner still owns external publication: push, draft PR
57
- creation, labels, comments, merges, publishing, and deploys.
58
-
59
- ### Parent Planning and Child Waves
60
-
61
- Use `agent:plan-auto` for larger work. The runner asks Codex to plan the parent
62
- issue, produce a child issue tree, mark safe child issues, and execute those
63
- children in dependency-aware waves.
64
-
65
- Only runner-marked child issues belong to the autonomous tree. A link, milestone,
66
- project field, or casual reference is not enough. Successful tree execution
67
- opens one integration draft PR.
68
-
69
- ### Review Gates Before Handoff
70
-
71
- The runner checks the work before it opens a draft PR. By default, runtime
72
- changes need test evidence, code review evidence, and for larger changes cleanup
73
- review evidence. UI work can require visual proof such as screenshots or a
74
- runner-owned browser validation command.
75
-
76
- ### Full Change-Set Awareness
77
-
78
- The runner treats the agent result as a full local change set. That includes
79
- local commits, staged files, unstaged files, and untracked files. Safety checks
80
- and review gates are applied to the whole result, not just to whatever happens
81
- to be left uncommitted.
82
-
83
- ### Durable Logs and Recovery
84
-
85
- Runs keep local state and durable evidence so interrupted or blocked work can be
86
- inspected. Agent output, validation results, skipped checks, residual risks,
87
- visual artifacts, and preserved worktrees are surfaced in review or blocked
88
- reports where relevant.
89
-
90
- ### Project-Owned Policy
91
-
92
- Each target repository owns its policy in `.codex-orchestrator/`: labels,
93
- branches, checks, prompts, review gates, deny rules, visual proof settings, and
94
- runner behavior. The npm package provides the reusable runner; the repository
95
- decides how strict the automation should be.
96
-
97
- ### PR-First by Design
98
-
99
- The package does not auto-merge. It opens draft PRs and moves issues to a review
100
- state so humans can inspect the result before anything lands on the base branch.
101
-
102
- ## What Happens During a Run
103
-
104
- For a normal `agent:auto` issue, the runner:
105
-
106
- 1. Reads the issue and checks that its labels allow autonomous work.
107
- 2. Claims the issue so another runner does not start it at the same time.
108
- 3. Creates an isolated git worktree and branch.
109
- 4. Builds a project-aware Codex prompt from the issue and local policy.
110
- 5. Runs Codex and captures the result.
111
- 6. Collects the full local change set, including local commits when allowed.
112
- 7. Blocks unsafe paths, missing reports, failed checks, missing review evidence,
113
- or skipped required proof.
114
- 8. Pushes the branch and opens a draft PR only after validation passes.
115
- 9. Posts a review report and moves the issue to `agent:review`.
116
-
117
- ## Authorization Modes
118
-
119
- There are two main labels.
54
+ There are two main modes.
120
55
 
121
56
  ### `agent:auto`
122
57
 
123
- Use `agent:auto` for one scoped implementation issue.
58
+ Use `agent:auto` for one clear implementation issue.
124
59
 
125
- Example:
126
-
127
- ```sh
128
- codex-orchestrator run --target . --issue 123
129
- ```
60
+ The runner:
130
61
 
131
- The runner checks that issue `#123` is eligible, creates a worktree and branch,
132
- runs Codex, validates the result, pushes the branch, and opens one draft PR.
62
+ 1. Checks that the issue is allowed to run.
63
+ 2. Claims the issue so another runner does not start it too.
64
+ 3. Creates a branch and isolated git worktree.
65
+ 4. Runs Codex with the issue context and repo policy.
66
+ 5. Validates the full local change set.
67
+ 6. Pushes the branch and opens a draft PR only after the gates pass.
68
+ 7. Moves the issue to review and posts the run report.
133
69
 
134
70
  ### `agent:plan-auto`
135
71
 
136
- Use `agent:plan-auto` for a larger parent issue.
137
-
138
- This mode is for work that should be planned before implementation. The runner
139
- asks Codex to produce or update the PRD, break the work into child issues,
140
- review the breakdown, triage the children, and execute the autonomous children
141
- in waves.
72
+ Use `agent:plan-auto` for work that needs planning first.
142
73
 
143
- Only explicitly marked child issues belong to the autonomous tree. A child issue
144
- must have the configured child label and the runner-owned parent marker. A link,
145
- milestone, project, or casual reference is not enough.
74
+ The runner asks Codex to plan the parent issue, break it into child issues,
75
+ triage them, run safe children in dependency order, and then open one
76
+ integration draft PR.
146
77
 
147
- Successful tree execution opens one integration draft PR.
78
+ Only child issues explicitly marked by the runner belong to the autonomous tree.
79
+ Ordinary links, milestones, project fields, or casual references are not enough.
148
80
 
149
81
  ## Basic Workflow
150
82
 
151
83
  1. Install the package.
152
84
  2. Run `setup` in the repository you want to automate.
153
- 3. Commit the generated `.codex-orchestrator/` policy into that repository.
85
+ 3. Commit the generated `.codex-orchestrator/` policy.
154
86
  4. Add `agent:auto` or `agent:plan-auto` to a GitHub Issue.
155
87
  5. Run `status` to see what is eligible or blocked.
156
88
  6. Run one selected issue with `run`, or let `daemon` poll for eligible work.
157
89
  7. Review the draft PR created by the runner.
158
90
 
159
- The runner does not auto-merge.
91
+ The runner never auto-merges.
160
92
 
161
93
  ## Installation
162
94
 
@@ -221,9 +153,15 @@ Run one issue:
221
153
  codex-orchestrator run --target . --issue 123
222
154
  ```
223
155
 
156
+ Run the daemon:
157
+
158
+ ```sh
159
+ codex-orchestrator daemon --target .
160
+ ```
161
+
224
162
  ## Agent-Assisted Setup
225
163
 
226
- A user does not need a long prompt. They can ask an agent:
164
+ You do not need a long prompt. You can ask an agent:
227
165
 
228
166
  ```text
229
167
  Set up codex-orchestrator for this repo.
@@ -244,70 +182,44 @@ codex-orchestrator --help
244
182
 
245
183
  The package also ships a setup prompt in `prompts/setup-skill.md`. Setup copies
246
184
  that prompt into `.codex-orchestrator/prompts/setup-skill.md`, so future agents
247
- working in the repository can find the repository-local setup guidance.
185
+ working in the repository can find repository-local setup guidance.
248
186
 
249
187
  Use `--dry-run` only when you want a preview without writing files or creating
250
188
  labels.
251
189
 
252
190
  ## Project Policy
253
191
 
254
- See `CHANGELOG.md` for release-by-release notes.
255
-
256
- Every installed repository owns its own config:
192
+ Every installed repository owns its config:
257
193
 
258
194
  ```sh
259
195
  .codex-orchestrator/config.json
260
196
  ```
261
197
 
262
- That config controls:
263
-
264
- - GitHub owner and repo;
265
- - labels used for the runner state machine;
266
- - base branch and branch name templates;
267
- - whether implementation agents may create local commits;
268
- - validation checks such as `npm test`;
269
- - review gates, including strict TDD, code review, cleanup review, and visual
270
- proof requirements;
271
- - deny rules for secrets and unsafe actions;
272
- - concurrency for child issue execution;
273
- - durable run logs and recovery state;
274
- - pull request title templates;
275
- - prompts used for PRD, issue breakdown, triage, scoped implementation, and
276
- issue-tree orchestration.
277
-
278
- The package ships fallback prompts so a user does not need to already have a
279
- local Codex skill pack installed. During setup, compatible existing local skills
280
- can be reused; missing workflows fall back to package-owned prompts.
281
-
282
- Configured checks run before publication. By default, missing `npm run <script>`
283
- checks are treated as skipped warnings (not failures). You can override this
284
- behavior with `checksPolicy.missingNpmScript`.
198
+ That config is where the repo decides how strict automation should be. It
199
+ controls the GitHub repo, labels, base branch, branch names, validation checks,
200
+ review gates, blocked paths, child issue concurrency, durable logs, PR titles,
201
+ and the prompts used for planning and implementation.
285
202
 
286
- For repos with existing lint debt, `checksPolicy.lintBaseline.mode` can be set
287
- to `touched-only` so a failing repo-wide lint check can be downgraded when a
288
- separate “touched files” lint command passes.
203
+ The package ships fallback prompts, so a repository does not need a local Codex
204
+ skill pack before setup. If compatible local skills already exist, setup can
205
+ reuse them.
289
206
 
290
- For runtime code changes, the default quality gate blocks review handoff unless
291
- the completion report contains passed validation for:
207
+ Configured checks run before publication. By default, missing
208
+ `npm run <script>` checks are reported as skipped warnings, not failures. You can
209
+ change that with `checksPolicy.missingNpmScript`.
292
210
 
293
- - strict TDD red-to-green evidence: a focused behavior test failed before the
294
- implementation and passed after the implementation;
295
- - a changed test file for the runtime change;
296
- - `code-review` for every runtime change;
297
- - `cleanup-review` when the change touches at least three runtime files.
211
+ For repos with existing lint debt, `checksPolicy.lintBaseline.mode` can be set
212
+ to `touched-only`. That lets a repo-wide lint failure be downgraded when a
213
+ separate touched-files lint command passes.
298
214
 
299
- These are runner-enforced checks, not only prompt guidance. They apply to the
300
- full local change set, including local commits when they are allowed by policy.
301
- Runtime and test paths are configurable through
302
- `reviewGates.quality.runtimeChangedPathGlobs` and
303
- `reviewGates.quality.testChangedPathGlobs`.
215
+ The default quality gate is conservative for runtime code changes. It can
216
+ require TDD evidence, changed tests, code review, cleanup review for larger
217
+ changes, and visual proof for UI work.
304
218
 
305
- For UI or frontend issues, visual proof is runner-owned via a configurable
306
- command (typically Playwright). Screenshot artifacts should be saved under
307
- `.codex-orchestrator/proofs/issue-<number>/`; the runner includes them in the PR
308
- and issue review report.
219
+ ## Visual Proof
309
220
 
310
- Configure a runner-owned command:
221
+ For browser UI work, configure a runner-owned proof command, usually a
222
+ Playwright script:
311
223
 
312
224
  ```json
313
225
  {
@@ -324,107 +236,68 @@ Configure a runner-owned command:
324
236
  }
325
237
  ```
326
238
 
327
- The runner executes this command from the issue worktree after Codex finishes and
328
- before review-gate evaluation. It also sets
329
- `CODEX_ORCHESTRATOR_ISSUE_NUMBER`, `CODEX_ORCHESTRATOR_ARTIFACT_DIR`,
330
- `CODEX_ORCHESTRATOR_PROOF_DIR`,
331
- `CODEX_ORCHESTRATOR_PLAYWRIGHT_PROFILE_DIR`,
332
- `CODEX_ORCHESTRATOR_WORKTREE_PATH`, and `CODEX_ORCHESTRATOR_CHANGED_FILES`.
333
- Use `CODEX_ORCHESTRATOR_PLAYWRIGHT_PROFILE_DIR` as the Playwright user data
334
- directory when proof scripts need a stable browser profile; this runtime
335
- directory and `PLAYWRIGHT_BROWSERS_PATH` are kept outside the worktree so browser
336
- cache and session files are not committed. Screenshot files
337
- created or updated under
338
- `CODEX_ORCHESTRATOR_PROOF_DIR` are attached to the PR and issue review report as
339
- runner-owned proof artifacts. A zero-exit proof command that does not create or
340
- update the configured minimum number of screenshots is reported as a warning.
341
-
342
- If the target UI requires login, keep credentials outside the config and expose
343
- only their variable names through `envPassthrough`. The visual proof script can
344
- read those values, sign in with the browser automation tool it uses, and fail
345
- with a clear message when a required login variable is missing.
346
-
347
- The default Codex command loads the user's Codex config so installed plugins
348
- remain available to the child agent. It also enables network access for the
349
- `workspace-write` sandbox so local dev servers can bind to `localhost` during
350
- browser validation.
351
-
352
- ## Local Commits vs Publication
353
-
354
- `codex-orchestrator` separates local implementation work from external
355
- publication.
356
-
357
- Implementation agents may be allowed to create local commits in their issue
358
- worktree. This can make larger sessions easier to inspect because the branch
359
- contains meaningful checkpoints. Local commits are still treated as untrusted
360
- agent output until the runner validates them.
361
-
362
- The runner remains the only owner of external publication:
363
-
364
- - pushing branches;
365
- - opening draft pull requests;
366
- - moving GitHub labels;
367
- - posting issue comments;
368
- - merging child branches into an integration branch;
369
- - publishing packages or deploying.
370
-
371
- If an agent tries to bypass those boundaries, the run is blocked instead of
372
- published.
373
-
374
- ## Labels
375
-
376
- Default labels:
239
+ The runner executes this command from the issue worktree after Codex finishes
240
+ and before review-gate evaluation. It sets environment variables for the issue
241
+ number, artifact directory, proof directory, Playwright profile directory,
242
+ worktree path, and changed files.
377
243
 
378
- - `agent:auto` - a scoped issue is authorized for autonomous implementation;
379
- - `agent:plan-auto` - a parent issue is authorized for planning and issue-tree
380
- execution;
381
- - `agent:child` - a child issue belongs to an autonomous parent tree;
382
- - `agent:running` - the runner is currently working on the issue;
383
- - `agent:blocked` - the runner needs maintainer input;
384
- - `agent:manual` - the issue is reserved for human work;
385
- - `agent:review` - the result is ready for human review.
244
+ Screenshots created under `CODEX_ORCHESTRATOR_PROOF_DIR` are attached to the PR
245
+ and issue review report. Keep login credentials outside config and expose only
246
+ their variable names through `envPassthrough`.
386
247
 
387
- `setup --prepare-labels` creates missing labels through `gh`.
248
+ For Android UI work, the implementation prompt asks Codex to use `adb` or an
249
+ emulator-backed proof path instead of browser proof. Missing Android tooling or
250
+ no usable device is reported as a warning with the concrete reason, not as an
251
+ automatic release blocker.
388
252
 
389
253
  ## Safety Model
390
254
 
391
- The package is intentionally PR-first and human-reviewed.
255
+ The package is PR-first and human-reviewed. The important guardrails are:
392
256
 
393
- Important guardrails:
394
-
395
- - no automatic merge;
396
- - draft PRs only;
397
- - Codex may change files and local commits, but the runner owns remote
398
- publication and GitHub state;
257
+ - no automatic merge, and only draft PRs are opened;
258
+ - Codex may change files, but the runner owns remote publication and GitHub
259
+ state;
260
+ - only explicitly authorized issues run;
399
261
  - child issues are never inferred from ordinary links or references;
400
- - manual, blocked, running, review, and closed issues are not started;
401
- - child implementations run in isolated worktrees;
402
- - parallel child work is limited and avoids overlapping ownership scopes;
403
262
  - committed and uncommitted changes are checked before publication;
404
- - secret files are blocked by policy;
405
- - destructive database/cache actions and production deploy/release actions are
406
- blocked by default;
263
+ - secret files, destructive data/cache actions, and production deploy/release
264
+ actions are blocked by default;
407
265
  - malformed or missing completion reports block publication;
266
+ - bounded rework stops at the configured limit;
267
+ - Policy Suggestions are recommendations only;
408
268
  - underspecified work can be blocked for maintainer clarification instead of
409
269
  letting Codex invent product decisions.
410
270
 
271
+ ## Labels
272
+
273
+ Default labels:
274
+
275
+ - `agent:auto` - run one scoped issue;
276
+ - `agent:plan-auto` - plan and run a parent issue tree;
277
+ - `agent:child` - child issue in an autonomous tree;
278
+ - `agent:running` - runner is working;
279
+ - `agent:blocked` - maintainer input needed;
280
+ - `agent:manual` - reserved for human work;
281
+ - `agent:review` - ready for human review.
282
+
283
+ `setup --prepare-labels` creates missing labels through `gh`.
284
+
411
285
  ## CLI Reference
412
286
 
413
287
  ```sh
414
288
  codex-orchestrator --help
415
289
  codex-orchestrator --version
416
290
  codex-orchestrator health
417
- codex-orchestrator setup [--target <path>] [--github-owner <owner>] [--github-repo <repo>] [--dry-run] [--prepare-labels]
291
+ codex-orchestrator setup [--target <path>] [--github-owner <owner>] \
292
+ [--github-repo <repo>] [--dry-run] [--prepare-labels]
418
293
  codex-orchestrator status --target <path> [--dry-run]
419
294
  codex-orchestrator run --target <path> --issue <number>
420
- codex-orchestrator daemon --target <path> [--once] [--interval-seconds <seconds>] [--max-runs <count>]
295
+ codex-orchestrator daemon --target <path> [--once] \
296
+ [--interval-seconds <seconds>] [--max-runs <count>]
421
297
  ```
422
298
 
423
- ### `setup`
424
-
425
- Creates project-local config and prompt files under `.codex-orchestrator/`.
426
-
427
- Useful flags:
299
+ `setup` creates project-local config and prompt files under
300
+ `.codex-orchestrator/`. Useful flags:
428
301
 
429
302
  - `--dry-run` - show the setup plan without writing files or creating labels;
430
303
  - `--prepare-labels` - create missing GitHub labels;
@@ -436,42 +309,21 @@ Useful flags:
436
309
 
437
310
  Setup does not launch Codex, commit changes, or open pull requests.
438
311
 
439
- ### `status`
440
-
441
- Shows eligible issues, skipped issues with reasons, and local recovery state.
442
-
443
- `status` is read-only. It does not launch Codex and does not mutate GitHub.
444
-
445
- ### `run`
446
-
447
- Executes one selected issue if its labels and state authorize autonomous work.
312
+ `status` is read-only. It shows eligible issues, skipped issues with reasons,
313
+ and local recovery state.
448
314
 
449
- For `agent:auto`, it runs one scoped implementation and opens one draft PR.
315
+ `run` executes one selected issue when labels and state allow it. `agent:auto`
316
+ opens one scoped draft PR. `agent:plan-auto` runs parent planning, child waves,
317
+ final validation, and one integration draft PR.
450
318
 
451
- For `agent:plan-auto`, it runs parent planning, child issue management,
452
- dependency-aware child waves, final validation, and one integration draft PR.
453
-
454
- ### `daemon`
455
-
456
- Polls GitHub Issues for eligible `agent:auto` or `agent:plan-auto` work and runs
457
- one issue at a time.
458
-
459
- After each polling cycle, the daemon also cleans up runner-owned worktrees when
460
- all of these are true:
461
-
462
- - the worktree is under `runner.workspaceRoot`;
463
- - the worktree is not listed in local runner state as active;
464
- - the worktree branch has a merged GitHub pull request;
465
- - the worktree has no uncommitted or untracked changes.
466
-
467
- Dirty, blocked, active, or unpublished worktrees are preserved for maintainer
468
- inspection. Cleanup is built into the daemon; there is intentionally no separate
469
- cleanup CLI command.
319
+ `daemon` polls for eligible work and runs one issue at a time. It also cleans up
320
+ runner-owned worktrees after their PRs are merged, while preserving dirty,
321
+ blocked, active, or unpublished worktrees for inspection.
470
322
 
471
323
  ## Current Scope
472
324
 
473
- The package focuses on local runner workflows: explicit one-off runs, daemon
474
- polling, project-local configuration, and runner-owned worktree cleanup. Hosted
325
+ The package focuses on local runner workflows: one-off runs, daemon polling,
326
+ project-local configuration, and runner-owned worktree cleanup. Hosted
475
327
  infrastructure is not part of this package today.
476
328
 
477
329
  Non-GitHub trackers and non-Codex agents are also out of scope for the current
@@ -488,3 +340,5 @@ npm run typecheck
488
340
  Publishing is configured through GitHub Actions. A push to `main` runs tests and
489
341
  publishes the package to npm only when the current package version is not already
490
342
  published. The repository must provide the GitHub secret `NPM_KEY`.
343
+
344
+ See `CHANGELOG.md` for release-by-release notes.
@@ -4,6 +4,9 @@ export type LabelPreparationPolicy = 'report-only' | 'create-missing';
4
4
  export type WorkflowId = (typeof workflowKeys)[number];
5
5
  export type WorkflowSource = (typeof workflowSources)[number];
6
6
  export type ClarificationGate = 'block-and-comment';
7
+ export type IssueSelectionTieBreaker = 'issue-number-asc';
8
+ export type RetryableReworkBlocker = 'missing-completion-report' | 'invalid-completion-report' | 'no-changed-files' | 'failed-configured-checks' | 'missing-quality-gate-evidence';
9
+ export type FreshContextReviewMode = 'advisory';
7
10
  export interface LabelDefinition {
8
11
  name: string;
9
12
  color: string;
@@ -15,6 +18,28 @@ export interface WorkflowConfig {
15
18
  promptPath?: string;
16
19
  skillPath?: string;
17
20
  }
21
+ export interface LoopPolicyConfig {
22
+ issueSelection: {
23
+ priorityLabels: string[];
24
+ tieBreaker: IssueSelectionTieBreaker;
25
+ };
26
+ rework: {
27
+ maxAttempts: number;
28
+ retryableBlockers: RetryableReworkBlocker[];
29
+ };
30
+ freshContextReview: {
31
+ enabled: boolean;
32
+ mode: FreshContextReviewMode;
33
+ blockOnHighConfidencePolicyViolations: boolean;
34
+ };
35
+ durableRunSummaries: {
36
+ enabled: boolean;
37
+ };
38
+ policySuggestions: {
39
+ enabled: boolean;
40
+ maxSuggestions: number;
41
+ };
42
+ }
18
43
  export interface CodexOrchestratorConfig {
19
44
  version: 1;
20
45
  github: {
@@ -103,6 +128,7 @@ export interface CodexOrchestratorConfig {
103
128
  };
104
129
  };
105
130
  };
131
+ loopPolicy: LoopPolicyConfig;
106
132
  deny: {
107
133
  secretFiles: string[];
108
134
  destructiveDbOrCache: boolean;
@@ -1 +1 @@
1
- {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/config/schema.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/config/schema.ts"],"names":[],"mappings":"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"}