Skip to content

docs(help): document wait readiness and restart exhaustion #3098

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thymikee merged 1 commit into from
Oct 1, 2026
Merged

docs(help): document wait readiness and restart exhaustion #3098

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 7 additions & 10 deletions src/commands/schema/cli-help-topics.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,16 +237,13 @@ test('usageForCommand resolves workflow help topic', async () => {
);
assert.match(help, /run serially within one session/);
assert.match(help, /Wait failure contract:/);
assert.match(help, /wait_target_absent: a readable capture ran and found no match/);
assert.match(help, /wait_target_present: wait absent timed out with matches/);
assert.match(
help,
/predicate_failed: wait absent had no valid capture; final observation\/diagnostic is preserved/,
);
assert.match(help, /wait_capture_stalled: no readable capture finished before the deadline/);
assert.match(help, /wait_deadline_exceeded: a later capture used the remaining budget/);
assert.match(help, /wait_landmark_identity_mismatch: a replay destination guard/);
assert.match(help, /wait_stable_timeout: wait stable never saw a stable UI/);
assert.match(help, /wait_target_absent: readable capture, no match/);
assert.match(help, /wait_target_present: absence timeout/);
assert.match(help, /predicate_failed: no valid absence capture; observation\/diagnostic kept/);
assert.match(help, /wait_capture_stalled: no readable capture by deadline/);
assert.match(help, /wait_deadline_exceeded: later capture exhausted budget/);
assert.match(help, /wait_landmark_identity_mismatch: replay guard/);
assert.match(help, /wait_stable_timeout: no stable UI/);
assert.match(help, /Ambiguous find: add --first or --last/);
assert.match(help, /macOS context menus are secondary clicks \(help macos\)/);
assert.match(help, /Nearby mutation diff: diff snapshot -i/);
Expand Down
6 changes: 3 additions & 3 deletions src/commands/schema/cli-help-workflows.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,9 @@ test('usageForCommand resolves manual QA help topic', async () => {
assert.match(help, /Do not use placeholders such as @ref/);
assert.match(help, /wait text\/selector\/absent/);
assert.match(help, /wait absent 'label="Loading\.\.\."' 3000/);
assert.match(help, /wait_target_absent: a readable capture ran and found no match/);
assert.match(help, /wait_target_present: wait absent timed out with matches/);
assert.match(help, /wait_capture_stalled: no readable capture finished before the deadline/);
assert.match(help, /wait_target_absent: readable capture, no match/);
assert.match(help, /wait_target_present: absence timeout/);
assert.match(help, /wait_capture_stalled: no readable capture by deadline/);
});

test('usageForCommand resolves validate help topic', async () => {
Expand Down
18 changes: 10 additions & 8 deletions src/commands/schema/cli-help-workflows.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
export const WAIT_FAILURE_CONTRACT = `Wait failure contract:
Read error.details.reason in --json, not the message text.
wait_target_absent: a readable capture ran and found no match.
wait_target_present: wait absent timed out with matches; details include matches and firstMatch.
predicate_failed: wait absent had no valid capture; final observation/diagnostic is preserved.
wait_capture_stalled: no readable capture finished before the deadline -- retriable.
wait_deadline_exceeded: a later capture used the remaining budget after an earlier readable one.
wait_landmark_identity_mismatch: a replay destination guard found the selector but not the recorded identity.
wait_stable_timeout: wait stable never saw a stable UI -- not an absence verdict.
Read --json error.details.reason.
wait_target_absent: readable capture, no match.
wait_target_present: absence timeout; details.matches/firstMatch.
predicate_failed: no valid absence capture; observation/diagnostic kept.
wait_capture_stalled: no readable capture by deadline -- retriable.
wait_deadline_exceeded: later capture exhausted budget after a readable one.
wait_readiness_exhausted: readiness deadline; details.readinessPhase -- retriable.

@cubic-dev-ai cubic-dev-ai Bot Oct 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The two newly documented reasons (wait_readiness_exhausted, wait_runner_restart_exhausted) have no test assertion, while every other line of the contract is asserted in cli-help-topics.test.ts. A follow-up that drops or rewords them would pass silently, reintroducing the exact omission this PR fixes. Add assertions for both lines next to the other reason checks.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/commands/schema/cli-help-workflows.ts, line 8:

<comment>The two newly documented reasons (`wait_readiness_exhausted`, `wait_runner_restart_exhausted`) have no test assertion, while every other line of the contract is asserted in `cli-help-topics.test.ts`. A follow-up that drops or rewords them would pass silently, reintroducing the exact omission this PR fixes. Add assertions for both lines next to the other reason checks.</comment>

<file context>
@@ -1,12 +1,14 @@
+  predicate_failed: no valid absence capture; observation/diagnostic kept.
+  wait_capture_stalled: no readable capture by deadline -- retriable.
+  wait_deadline_exceeded: later capture exhausted budget after a readable one.
+  wait_readiness_exhausted: readiness deadline; details.readinessPhase -- retriable.
+  wait_runner_restart_exhausted: restart deadline -- retriable.
+  wait_landmark_identity_mismatch: replay guard: selector matched, recorded identity differed.
</file context>
Fix with cubic

wait_runner_restart_exhausted: restart deadline -- retriable.
wait_landmark_identity_mismatch: replay guard: selector matched, recorded identity differed.
wait_stable_timeout: no stable UI -- not absence.
`;

export const manualQaHelpTopics = {
Expand Down
Loading