fix(apple-runner): restart without resending a command written then lost

[thymikee]

Summary

A mutating command whose reply stays lost now fails with details.reason: runner_reply_lost and dispatched: "unknown". This covers a runner that dies mid-command, and every status-recovery verdict that finds neither a retained result nor a runner answer: completed without a retained reply, still accepted or started, notAccepted, an unknown or missing lifecycle state, a failed status probe, and a command with no id to probe. The command is sent once and never replayed, and the next command starts a new runner. One builder makes this error. The transport's own reason stays under details.transportReason. A read keeps its transport error, so the read-only resend loop resends it, and the read never carries the reason.

The restart-and-resend rule after a connect failure is owned by shouldRestartRunnerBeforeCommandSend(error, command). The rule restarts only when no attempt could have written the command (resolveFirstAttemptDispatch(error) === 'no') or when the command is read-only. A simctl curl exit-28 POST carries dispatched: unknown, so it never restarts a mutation. The restart carries the first attempt's DispatchDisclosure, not a boolean.

agent-device longpress @e3 5000 --json   # runner killed mid-press: runner_reply_lost, sent once

Closes #3074. Part of #3069. Stacked on #3071. 14 files touched.

Validation

Tested commit: 4e88908.

pnpm check:affected --run (fail-open full set): every runnable check passed. In vitest-related, 1333 of 1334 files passed. The one failure was a 5 s timeout under host load in a file this PR does not touch (screenshot-density.test.ts, and press-target-readiness.test.ts on the run before). Each passes alone. The checks after vitest-related were then run on the same commit, and all passed. Also run: pnpm typecheck, pnpm lint, apple runner vitest (167 files, 1704 tests), check:layering, check:fallow, format:check, the eager-closure budget test, and the runner read-only parity test.

Live on f52f120 (iPhone 17 Pro simulator, iOS 26.2, Release test app): longpress @e3 5000 --debug, with the runner process killed 1.3 s after the runner accepted the command. The request log has one ios_runner_command_send for longPress, then a failed status probe, invalidation_decision status_probe_failed, and ios_runner_session_invalidated transport_error_after_command_send. The error has reason: runner_reply_lost, recovery: status_probe_failed, dispatched: unknown, and no runnerRestarted. snapshot -i then succeeded, and the next runner command started a new runner session (port 61516, was 61032). The structural changes after that commit do not change this path.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.92 MB	4.92 MB	+561 B
Package (unpacked)	4.92 MB	4.92 MB	+561 B
Package (download)	1.47 MB	1.47 MB	+155 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.6 ms	26.3 ms	-1.3 ms
CLI --help	81.1 ms	81.1 ms	-0.0 ms

[cubic-dev-ai]

1 issue found across 9 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. 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. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/platform-apple/src/runner/runner-lifecycle.ts">

<violation number="1" location="packages/platform-apple/src/runner/runner-lifecycle.ts:542">
P3: `discloseRestartDispatch` now reports `dispatched: "no"` for read-only commands when the restart's resend fails with an already-disclosed `"unknown"` verdict (the `ios-runner.transport.read-only-written-then-lost` fixture asserts this). The parallel status-recovery path in `runner-command-recovery.ts` still discloses the same user-visible case as `"unknown"` (`handleCompletedRunnerStatus`'s `read_only_completed_without_retained_response` branch, and the fallthrough after a `notAccepted` probe for `lifecycle_state_not_recoverable`), so an agent deciding whether to retry on `details.dispatched` sees different values for the same class of failure depending on which recovery flow fired. Decide one semantics for read-only lost replies and pin both paths (and the fixture) to it.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P3: discloseRestartDispatch now reports dispatched: "no" for read-only commands when the restart's resend fails with an already-disclosed "unknown" verdict (the ios-runner.transport.read-only-written-then-lost fixture asserts this). The parallel status-recovery path in runner-command-recovery.ts still discloses the same user-visible case as "unknown" (handleCompletedRunnerStatus's read_only_completed_without_retained_response branch, and the fallthrough after a notAccepted probe for lifecycle_state_not_recoverable), so an agent deciding whether to retry on details.dispatched sees different values for the same class of failure depending on which recovery flow fired. Decide one semantics for read-only lost replies and pin both paths (and the fixture) to it.

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 packages/platform-apple/src/runner/runner-lifecycle.ts, line 542:

<comment>`discloseRestartDispatch` now reports `dispatched: "no"` for read-only commands when the restart's resend fails with an already-disclosed `"unknown"` verdict (the `ios-runner.transport.read-only-written-then-lost` fixture asserts this). The parallel status-recovery path in `runner-command-recovery.ts` still discloses the same user-visible case as `"unknown"` (`handleCompletedRunnerStatus`'s `read_only_completed_without_retained_response` branch, and the fallthrough after a `notAccepted` probe for `lifecycle_state_not_recoverable`), so an agent deciding whether to retry on `details.dispatched` sees different values for the same class of failure depending on which recovery flow fired. Decide one semantics for read-only lost replies and pin both paths (and the fixture) to it.</comment>

<file context>
@@ -500,21 +525,23 @@ function markRunnerRestartError(
 ): AppError {
-  if (!restartedSession) return discloseDispatch(error, firstAttemptUnwritten ? 'no' : 'unknown');
-  if (!firstAttemptUnwritten) return discloseDispatch(error, 'unknown');
+  if (isReadOnlyRunnerCommand(evidence.command)) return discloseDispatch(error, 'no');
+  if (!evidence.firstAttemptUnwritten) return discloseDispatch(error, 'unknown');
+  if (!restartedSession) return discloseDispatch(error, 'no');
</file context>

[thymikee]

[claude-fable-5-1] responding on behalf of @thymikee

Head is now 4758d2786d.

1. Read-only restart discloses no but status recovery says unknown (runner-lifecycle.ts ~L542): fixed in be1b89f.
Both runner paths now report the transport fact. If the first attempt may have written the command, the value is unknown, for a read or a mutation. The read-only no now has one owner: the router seam src/daemon/request-dispatch-disclosure.ts, which keys it on the registry's recordingEffect: 'observes-app' (row daemon.read-only-command). The runner branch keyed on its own read-only trait was a second copy of that rule from a different source, so I removed it. The recycle-budget refusal had the same problem, so it now uses only firstAttemptUnwritten. The runner still resends a read after the restart. Only the disclosure changes.

• ios-runner.transport.read-only-written-then-lost is now unknown.
• New row ios-runner.status.read-only-completed-without-retained-reply is unknown. Its driver goes through the real connect loop and the recovery module, so the two paths are pinned to the same value.
• Mutations: putting the read-only no branch back in discloseRestartDispatch makes the restart row fail. Setting dispatched: 'no' on read_only_completed_without_retained_response makes the new status row fail.

2. Unconsumed second ok for the mutation (runner-recovery-wiring.test.ts ~L170): fixed in 4758d27. I dropped it.

3. Premise says "restarted", but the path is status recovery (~L164): fixed in 4758d27, with one pushback.

• I changed the comment on the existing test. It models status answering notAccepted, the way a runner whose journal did not survive a restart would. The path is status recovery.
• Harness gap: the fake server could only hang up on one request and stayed up, so it could not model a runner that dies. I added the smallest hook: an { kind: 'exit' } reply that hangs up and stops listening. A second fake server acts as the restarted runner.
• New test for press/fill (tap/type): the runner dies on the command. Across both servers the command is sent once, it fails with dispatched: unknown, the dead session is invalidated, and the next readText is served by the restarted runner. Mutation: declaring tap/type with READ_ONLY_TRAITS makes both rows fail.
• New test for get (readText): the runner dies mid-read. The daemon restarts it (runner_connect_failed_before_command_send), and the read is resent once and succeeds. Mutation: reducing canResendAfterRestart to firstAttemptUnwritten makes it fail.
• Pushback: with the real transport, a mutating command cannot reach restartSessionAndRunCommand with a possibly-written first attempt. Mutations are sent by sendRunnerCommandOnce (runner-exchange.ts, the non-read-only branch of sendRunnerCommandAfterPreflight). Only the connect loop waitForRunner stamps runner_connect_refused (runner-startup-transport.ts, runnerConnectFailureDetails call sites), and that loop sends only reads and the readiness preflight. The preflight restart always passes firstAttemptUnwritten: true. So the mutating arm of the new gate can only be driven through the mocked lifecycle driver (ios-runner.transport.written-then-lost). No fake-server test can reach it.
• Also, when a runner dies mid-mutation, the failure goes to status recovery, and the status probe fails there. That path rethrows the bare transport error (fetch failed, dispatched: unknown) with no runner_reply_lost reason. So the new test does not assert that reason. runner-command-recovery.test.ts ("a failing status probe … rethrows the transport error") pins this as the current contract. Adding the reason there is a separate change.

Checks run: pnpm typecheck; vitest on packages/platform-apple/src/runner (68 files, 768 tests) and on packages/contracts; pnpm check:layering; pnpm check:fallow; pnpm run format:check. All pass.

[thymikee]

[claude-fable-5-1] responding on behalf of @thymikee

Follow-up in 50fc6fc:

• Typed reason on the path that occurs: a runner dies mid-mutation and the status probe then fails. The error now has reason: runner_reply_lost (the name the restart arm uses), recovery: status_probe_failed and dispatched: unknown. It keeps the transport message and details, and the transport error as cause. The recovery unit test that pinned the bare fetch failed rethrow now asserts the reason. So do the real-transport press/fill tests. Mutation: dropping reason: RUNNER_REPLY_LOST_REASON from buildStatusProbeFailedError makes all three fail.
• Mutating arm of canResendAfterRestart: kept. The ADR 0011 gap list now says that ios-runner.transport.written-then-lost proves the rule, not a production route. Over the real transport that arm cannot be reached, because mutations go through sendRunnerCommandOnce and only the connect loop raises the restart trigger. Mutation (from c6188ef): making canResendAfterRestart return true fails the mocked row, because the tap is resent.

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[thymikee]

[claude-fable-5-1] responding on behalf of @thymikee

Hang-up count tied to the connect-loop cadence (runner-dispatch-disclosure.test.ts ~L81): fixed in f247110, with a complexity follow-up in the next commit. The fake runner server has a new hangUpAlways reply that is never consumed. The read-only driver uses it in place of 20 hang-ups, so the read is refused until the connect loop gives up, however often the loop retries. The 400 ms timeout now only bounds how long the loop runs. Mutation: setting RUNNER_CONNECT_ATTEMPT_INTERVAL_MS to 10 or 50 (with a 1 ms retry base delay) does not change the outcome, and the row still passes.

[thymikee]

The change looks correct in code, but the one reachable behavior it adds has no live proof yet. I reviewed 1edcb78. CI is green: 14 checks, none failing. No conflicts.

The reachable change is the typed reason runner_reply_lost on a mutation whose runner dies mid-command (runner-command-recovery.ts#L207). The route is: status probe fails, then retainInvalidation, then the reason with recovery status_probe_failed. The only live run was on 4708d4f, and it killed the runner before the press. That run hit the existing refused-connect restart-and-resend arm, not this route, and the PR's Risks line says so. So we have no proof that a real runner death mid-mutation gives this error and that the next command boots a new runner. Please run this on head on an iOS simulator with the Release test app: start a long mutation such as longpress @eN 5000 --debug (or a gesture or long swipe) and kill the XCTest runner while it is in flight. The request log must show exactly one ios_runner_command_send for it. The error must show details.reason=runner_reply_lost, recovery status_probe_failed (or lifecycle_state_not_recoverable) and dispatched=unknown. There must be no runnerRestarted resend, and an ios_runner_session invalidation with transport_error_after_command_send. Then snapshot -i must succeed on a new runner sessionId. A run that kills the runner before the send does not count.

Could the change be smaller? The connect loop in waitForRunner only carries read-only commands, so the new no-resend arm in restartSessionAndRunCommand sees a read, or a mutation with unwritten proof from the readiness preflight. Could the call site pass the resend permission (isRunnerPreSendRefusal || isReadOnlyRunnerCommand) as the entry condition, or drop the mutating arm and its error builder? Then the reachable delta is the runner_reply_lost reason on the two status-recovery errors, about 30 lines. The ADR 0011 sentence already records the rule, so nothing needs deciding first. Closing #3074 would need a note that its premise (restart resends a written mutation) has no production route.

Not blocking, take or leave: the no-resend arm at runner-lifecycle.ts#L437 is only driven by a mocked transport row, because mutations never enter the connect loop; the notAccepted and runner-dies-mid-command tests in runner-recovery-wiring.test.ts#L173 pass on the merge-base except for the runner_reply_lost assertion, so they could be retitled to that reason; buildStatusProbeFailedError spreads transportError.details and then overwrites reason and hint, so a transport reason would be lost (none of today's producers set one, but a separate key would keep it); and the PR body is stale, since it says reads disclose dispatched: "no" when the runner reports unknown and the router says no, it says 9 files when the diff has 12, it names 4708d4f instead of head, and it records check:affected exiting 1 with no green rerun.

I did not run the tests or the mutations. I judged "fails without the fix" from the merge-base code, and "next command gets a fresh runner" is only shown with a mocked ensureRunnerSession.

Before merge, we need the live run on 1edcb78 described above, and a refreshed PR body with the head sha, a green check:affected result and the router-owned "no".

[thymikee]

[claude-fable-5-1] responding on behalf of @thymikee

Head is now f52f120b1d.

Simplification (6739a58): I took it.

• The connect-failure call site in executeRunnerCommandAttempt now restarts only when isRunnerPreSendRefusal(appErr) || isReadOnlyRunnerCommand(command). Any other connect failure falls through to status recovery, as before.
• Deleted: the no-resend arm in restartSessionAndRunCommand, canResendAfterRestart, the firstAttemptError param, buildRunnerRestartedWithoutResendError, and the comment edits in runner-error-classification.ts (now identical to the base). I also reverted a reorder in discloseRestartDispatch that did not change behaviour.
• Production delta in this round: +26 / −72 lines. Against the merge-base, production is now +47 / −3 in runner-command-recovery.ts and runner-lifecycle.ts.
• The ADR 0011 rule sentence stays, as its own paragraph. I moved it out of the "Remaining gaps" paragraph that feat(errors): disclose whether a failed interaction reached the device #3071 just rewrote, so the PR merges cleanly with the new base.
• The row ios-runner.transport.written-then-lost no longer has a mocked lifecycle driver. It now runs tap over the real transport against the fake runner's { kind: 'exit' } hook. It asserts one tap send, reason: runner_reply_lost, recovery: status_probe_failed, no runnerRestarted, and invalidation with transport_error_after_command_send. Mutation: removing the call-site gate (always restart) fails 8 runner tests.

Reason key: buildStatusProbeFailedError keeps a transport details.reason as details.transportReason before it sets reason: runner_reply_lost. The probe-failed recovery test pins this.

Retitles (f52f120): a $acceptanceCommand whose status answers notAccepted fails as runner_reply_lost, sent once and a $acceptanceCommand whose runner dies mid-command fails as runner_reply_lost, not resent.

Live on f52f120: new iPhone 17 Pro sim, iOS 26.2, Release test app. I ran longpress @e3 5000 --debug --json and killed the sim's runner process during the press. The runner accepted the command at 23:32:47.630, the kill was at 23:32:48.922, and the send failed at 23:32:49.030. This was the first try.

47.612 ios_runner_session_reuse          sessionId …:61032:1790811100968
49.030 ios_runner_command_send  1402ms   {"command":"longPress","error":"fetch failed"}
52.035 ios_runner_command_send  3003ms   {"command":"status","error":"Runner did not accept connection"}
52.035 ios_runner_command_invalidation_decision {"decision":"retained","reason":"status_probe_failed","runnerReachable":false}
52.035 ios_runner_session_invalidated    {"reason":"transport_error_after_command_send"}

• Error: reason: runner_reply_lost, recovery: status_probe_failed, dispatched: unknown, with no runnerRestarted. The log has exactly one longPress send.
• snapshot -i --json then succeeded. On this sim it is served by the AX bridge and does not touch the runner. The next runner command (longpress @e3 100) started a new runner, session …:61516:1790811200162.

Gate: pnpm check:affected --run is green on f52f120. The first run had one 5 s timeout under load (fallow-fixture-policy.test.ts), which passes alone. The PR body is refreshed.

[thymikee]

Code-quality review. The shipped behavior is right: a mutation whose runner dies mid-command is sent once and fails with runner_reply_lost, through the status probe. The structure has three problems:

• The new restart gate at the call site never changes behavior on any input that can reach it. The defect is in the classifier that labels an exit-28 POST as runner_connect_refused.
• The written-then-lost proof is a boolean that later code converts back into 'no' | 'unknown', instead of the existing DispatchDisclosure type.
• runner_reply_lost is set on some lost-reply outcomes and not on others, by four hand-built copies of the same error.

Inline comments cover each point. No file crosses 1k lines.

[thymikee]

This conjunct guards a state that cannot happen. Mutations go through sendRunnerCommandOnce and never enter the connect loop (waitForRunner / postCommandViaSimulator), and that loop is the only producer of runner_connect_refused. The PR description says the same. For a mutation, the only restartBeforeSend error that can arrive is a marked readiness-preflight failure, and isRunnerPreSendRefusal is already true for that. For a read, the disjunct is true. So (firstAttemptUnwritten || isReadOnlyRunnerCommand(command)) is true for every input that can reach this line. No test exercises the side where it refuses either: the written-then-lost row moved to the status-probe path, and every remaining mutation driver uses unwrittenConnectRefusal().

The real defect is in the code that owns the classification. restartBeforeSend is documented as "connect-shaped failure before the command was sent". But postCommandViaSimulator (runner-startup-transport.ts ~L517) labels a curl exit-28 POST that has dispatched: 'unknown' as runner_connect_refused. Fix it there. Either stop labelling a request that was posted and then timed out as a connect refusal, or make shouldRestartRunnerBeforeCommandSend(error, command) in runner-error-classification.ts own the write-proof rule. Then delete this call-site guard. AGENTS.md says to repair at the owning type and not to add guards that rebuild another source of truth.

[thymikee]

firstAttemptUnwritten is a boolean derived from a typed fact that already exists: the error's details.dispatched, which is 'no' for curl exit 7 or ECONNREFUSED. Downstream code then turns it back into 'no' | 'unknown' with hand-written ternaries: once for the recycle-budget throw in restartSessionAndRunCommand, and twice in discloseRestartDispatch. A reader has to decode the boolean every time it is used.

Carry the first attempt's disclosure instead:

• Add firstAttemptDispatched: DispatchDisclosure, computed once by one classifier, for example resolveFirstAttemptDispatch(error) next to isRunnerCommandProvablyUnwritten.
• Replace the ternaries with discloseDispatch(err, params.firstAttemptDispatched).
• Have the readiness-preflight call site pass 'no' instead of true.

This models the proof as a value of the domain type and removes branches instead of adding them. Together with the L359 comment, the restart decision becomes one answer from one classifier.

[thymikee]

runner_reply_lost is documented as: the command was written, its reply was lost, there is no proof it did not run, and it is not resent. But only some outcomes that match this carry it: status_probe_failed and the unknown/missing-lifecycle case.

• completed_without_retained_response (handleCompletedRunnerStatus) and command_still_in_flight (runnerStatusInFlightError) are also written, reply lost, dispatched: 'unknown', and not resent. They do not set the reason.
• In the other direction, buildStatusProbeFailedError sets it on read-only commands too. That error keeps the code, message and connect details, so isRetryableRunnerError still holds, and the read-only resend loop in runAppleRunnerCommand resends the read up to TRANSPORT_RESEND_ATTEMPTS times. A read that runs out of attempts therefore ends with a reason that says "not resent".

A consumer that keys on details.reason gets a signal that is incomplete and sometimes false. The reason belongs to the recovery verdict, not to each error builder. Set it in one place, for example in applyRunnerTransportRecovery for every non-recovered mutation verdict with dispatched: 'unknown'. Add one table-driven test that every lost-reply row in dispatch-disclosure.json carries it.

[thymikee]

This is the fourth hand-built copy of the same lost-reply AppError: command, commandId, recovery, hint, logPath, the transportError message, and transportError as the cause. The other three are the inline unknown-lifecycle literal (~L289–305), handleCompletedRunnerStatus and runnerStatusInFlightError.

This copy also has a different shape. The other three drop the transport details. This one spreads ...transportError.details, overwrites reason, and moves the original reason into a new transportReason key that only this path has. To find the transport's reason, a consumer now has to know which path built the error.

Extract one buildLostReplyError(command, transportError, options, { recovery, lifecycleState?, message?, hint }). Make it own the detail shape, the reply-lost reason (see the L54 comment), and one rule for keeping the transport's own reason. Then rewrite this function and the inline literal as calls to it.

[thymikee]

This PR is ready. The earlier findings at 1edcb78 are fixed in f52f120, and I found nothing new to block on. Not blocking, and you can take or leave it: the guard (firstAttemptUnwritten || isReadOnlyRunnerCommand(command)) at https://github.com/callstack/agent-device/blob/f52f120/packages/platform-apple/src/runner/runner-lifecycle.ts#L359 looks true for every input that reaches it, and no test covers its refuse side, so you could let shouldRestartRunnerBeforeCommandSend own the write-proof rule, or stop labelling a posted-then-timed-out curl exit 28 as runner_connect_refused in runner-startup-transport.ts, and then drop the guard.

The code review is done. I read the quoted request-log lines from your live run, but I saw no raw artifact, so that evidence is author-reported. I did not run the runner vitest suite or your gate-removal mutation. From reading the code, the refuse side looks untested, which does not match the "8 tests fail" claim.

CI is still pending. Smoke Tests is in progress and has not failed, and the other 13 checks pass. If its iOS lane runs runner mutations, it exercises the changed route, which is the restart gating in executeRunnerCommandAttempt and the status-probe recovery. No conflicts. Smoke Tests must finish green before merge, and nothing in this delta stops that.

[thymikee]

[claude-fable-5-1] responding on behalf of @thymikee

Replayed onto #3071's d7b442d040. Conflicts: docs/adr/0011-interaction-guarantee-contract.md only, in two commits. I kept the base's runBatch paragraph and dropped this branch's older sentence that said a batch outside the daemon keeps the failing step's value, because the base now contradicts it. The written-then-lost row sentence stays only in its final form (the paragraph above "Remaining gaps").

Added test(apple-runner): the runner read-only set matches the registry's observes-app commands (src/__tests__/runner-read-only-registry-parity.test.ts). The runner has no mapping to registry commands, so the test declares one: each runner wire command is paired with the registry request that issues it, and readOnly must equal observes-app for it; alert actions are checked the same way. Runner-internal commands (status, uptime, appState, gestureViewport, sequence, shutdown, activate, terminate, targetReset) are listed with their expected value. recordStart and recordStop are the one divergence: record observes the app, but the runner must not resend them, so they are declared stricter than the registry. The test loads the package-private traits module by computed file URL, because the layering gate rejects a relative or type import across the package boundary and the module has no subpath.

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[thymikee]

[claude-fable-5-1] responding on behalf of @thymikee

Head is now 4e88908fc3, rebased on feat/dispatch-disclosure a5ac453380.

1. The call-site guard never changed behavior (runner-lifecycle.ts L359): fixed in 2ffd18a.
The write-proof rule moved into its owner. shouldRestartRunnerBeforeCommandSend(error, command) restarts only when the connect failure provably wrote nothing, or when the command is read-only. An exit-28 POST (runner_connect_refused with dispatched: unknown) on a mutation now gets false from the classifier.

• Deleted: the call-site conjunct (firstAttemptUnwritten || isReadOnlyRunnerCommand(command)) and its import (runner-lifecycle.ts +2/−8).
• Tests: a classifier test where the same exit-28 error gives false for tap and true for snapshot. A lifecycle test sends tap through the real connect loop with curl exit 28. It asserts no restart, one tap send, and dispatched: unknown.
• Mutation: making the classifier ignore the proof (return true) fails both tests.
• Parity test: kept. The runner's read-only list still makes decisions: the restart rule above, the read/mutation split in recovery (item 3), and the read-only resend loop in runAppleRunnerCommand.

2. A boolean instead of the domain type (runner-lifecycle.ts L369): fixed in 66ef675.
restartSessionAndRunCommand now takes firstAttemptDispatched: DispatchDisclosure. resolveFirstAttemptDispatch(error) computes it once, next to isRunnerCommandProvablyUnwritten, and the restart rule reads the same answer. The readiness-preflight call site passes 'no'.

• Deleted: the three ternaries. The recycle-budget throw and the no-restarted-session branch are now discloseDispatch(err, firstAttemptDispatched).
• Test: a read whose first POST may have been written and whose restart fails discloses unknown.
• Mutations: passing a constant 'no' at the connect call site fails that test. Passing 'unknown' at the readiness-preflight site fails the ios-runner.pre-send.readiness-preflight-after-restart row.

3. One lost-reply error, one reason (runner-command-recovery.ts L54, L489): fixed in 4e88908.
Each non-recovered verdict now carries one of two failures: runnerAnswer (the runner's own failure, read back from the journal) or lostReply facts (recovery, lifecycle state, message, hint). applyRunnerTransportRecovery resolves the failure in one place:

• A mutation gets buildLostReplyError. This one builder owns the detail shape, reason: runner_reply_lost, and one rule for the transport's reason, which is always kept as transportReason.
• A read gets its transport error, so the read-only resend loop resends it.
• The reason now covers completed_without_retained_response, command_still_in_flight, and status_recovery_unavailable as well.

What changed:

• Deleted: the inline unknown-lifecycle literal, the error built in handleCompletedRunnerStatus, runnerStatusInFlightError, buildStatusProbeFailedError, and the | undefined recovery result (runner-command-recovery.ts +133/−140).
• Not covered: runner_reported_failure. That is the runner's own answer and keeps its own reason, for example runner_main_thread_timeout.
• Behavior change for reads: a read whose status is unknown or notAccepted now rethrows its transport error and is resent, the same as every other lost read. Before, it failed with a non-retryable error.

Tests:

• In runner-dispatch-disclosure.test.ts, every row's test asserts that reason === runner_reply_lost is true exactly for the lost-reply rows (completed-without-retained-reply, accepted, started, notAccepted, probe-failed, unavailable). The row ios-runner.transport.written-then-lost already asserts it in its own driver.
• A test.each over four read outcomes (probe failed, notAccepted, started, completed without a reply) asserts no reason and a retryable error.

Mutations:

• Removing the reason from the builder fails all 6 lost-reply rows.
• Removing the read branch fails the read-only row and all 4 read cases.

ADR 0011 now names the ios-runner.status.* lost-reply rows.

Gate on 4e88908fc3: check:affected --run (fail-open full set) passed every runnable check. In vitest-related, 1333 of 1334 files passed. The one failure was a 5 s timeout under host load in an untouched file (screenshot-density.test.ts), which passes alone.

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[thymikee]

[claude-fable-5-1] responding on behalf of @thymikee

Addressed cubic's latest four findings:

• P2 runner-command-recovery.ts: a lost reply re-classified as retryable by its own text. 75a418f6b0. LostReply.message is now required, and status_probe_failed and status_recovery_unavailable get their own fixed message. The transport text stays in details.transportError and cause. RUNNER_REPLY_LOST_REASON moved into runner-error-classification.ts. A new first row in RUNNER_ERROR_RULES keys on details.reason === runner_reply_lost and sets retryable, drainResend, connectRetry, restartBeforeSend and restartAfterReadinessPreflight to false, so text a lost reply carries cannot resend it. New tests: (1) isRetryableRunnerError, shouldRetryRunnerConnectError and shouldRestartRunnerBeforeCommandSend are false for a lost reply that carries fetch failed, ECONNREFUSED or socket hang up text. (2) An end-to-end runAppleRunnerCommand tap whose send fails with fetch failed and whose status probe fails with ECONNREFUSED fails as runner_reply_lost, is not retryable, and sends the tap once. The runner-command-retry assertions that pinned the old message ('fetch failed') now assert the reason and details.transportError.
• P2 ADR 0011: ios-runner.status.* is not only the lost-reply rows. 72f27a68d1. The ADR now names the six lost-reply rows and ios-runner.transport.written-then-lost. It also says that the ios-runner.status.failed* rows carry the runner's own answer.
• P3 parity map: keyboardReturn. 28e492fa76. Changed to positionals: ['enter'] to match keyboardEnter in interactor.ts and the daemon's return → enter normalization.
• P3 connect-loop mutation test does not tell a lost reply from a plain transport failure. 25ce56e7d5. It now asserts reason: runner_reply_lost and recovery: status_probe_failed.

Checks: typecheck, lint, format:check, layering and fallow audit pass, and the apple-runner project passes 767/767. A 5 s timeout failed under load and passed when run alone. In unit-core, 2 timeouts fail when run alone, and neither relates to this change: screenshot-density fails the same way at the base, and scripts/fuzz/harness is outside this diff.

[cubic-dev-ai]

1 issue found across 10 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. 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. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/platform-apple/src/runner/runner-command-recovery.ts">

<violation number="1" location="packages/platform-apple/src/runner/runner-command-recovery.ts:506">
P3: `lostReplyWithoutStatusMessage` rebuilds the same sentence skeleton as the inline message in `handleRunnerCommandStatusRecovery` (`lifecycle_state_not_recoverable`): both are `Runner command "…" lost its transport response and … so agent-device invalidated the runner session instead of replaying the command.`. Three lost-reply messages now share the identical structure, so the shared "invalidated instead of replaying" clause can drift between the two paths. Feed the lifecycle branch through the same builder, e.g. `lostReplyWithoutStatusMessage(command.command, lifecycleState ? `lifecycle status was "${lifecycleState}"` : 'lifecycle status was missing')`.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P3: lostReplyWithoutStatusMessage rebuilds the same sentence skeleton as the inline message in handleRunnerCommandStatusRecovery (lifecycle_state_not_recoverable): both are Runner command "…" lost its transport response and … so agent-device invalidated the runner session instead of replaying the command.. Three lost-reply messages now share the identical structure, so the shared "invalidated instead of replaying" clause can drift between the two paths. Feed the lifecycle branch through the same builder, e.g. lostReplyWithoutStatusMessage(command.command, lifecycleState ? lifecycle status was "${lifecycleState}" : 'lifecycle status was missing').

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 packages/platform-apple/src/runner/runner-command-recovery.ts, line 506:

<comment>`lostReplyWithoutStatusMessage` rebuilds the same sentence skeleton as the inline message in `handleRunnerCommandStatusRecovery` (`lifecycle_state_not_recoverable`): both are `Runner command "…" lost its transport response and … so agent-device invalidated the runner session instead of replaying the command.`. Three lost-reply messages now share the identical structure, so the shared "invalidated instead of replaying" clause can drift between the two paths. Feed the lifecycle branch through the same builder, e.g. `lostReplyWithoutStatusMessage(command.command, lifecycleState ? `lifecycle status was "${lifecycleState}"` : 'lifecycle status was missing')`.</comment>

<file context>
@@ -504,6 +503,10 @@ function readReadinessPreflightRecoveryDetails(
   return details;
 }
 
+function lostReplyWithoutStatusMessage(command: string, statusOutcome: string): string {
+  return `Runner command "${command}" lost its transport response and ${statusOutcome}, so agent-device invalidated the runner session instead of replaying the command.`;
+}
</file context>

[thymikee]

Reviewed 25ce56e: no blocking issues. The new commits keep the restart-resend decision in one place, the connect-failure classifier. A lost reply now keys on its typed reason, not on transport text. A mutation whose request may have been written is never resent, and the first attempt's dispatched value survives the restart.

Not blocking, take or leave: the parity test in src/__tests__/runner-read-only-registry-parity.test.ts copies the readOnly values of nine runner-internal commands, so those rows compare the constant with itself; typing the counterpart rows as the registry's request type would also remove the as never cast. Also, buildLostReplyError replaces a boot-failure hint with the generic lost-reply hint for a mutation on a physical device; is that intended?

CI is still running (Smoke Tests, Repo Guards, Coverage), and iOS Smoke Tests run the runner route this changes. There are no conflicts. I read the code and did not run the tests; the lost-reply path is covered by the fake runner server only, with no live device run.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-01 09:06 UTC

[thymikee]

[claude-fable-5-1] responding on behalf of @thymikee

This PR merged into feat/dispatch-disclosure at 25ce56e7d5 before the three take-or-leave notes landed, so they are on #3071 instead (7f2d6d1c01, c679e60385, e6869a0827): the parity rows are typed from the registry's DispatchedCommand with both as never casts gone (the nine internal rows already asserted against a literal table); buildLostReplyError keeps the transport error's own hint and falls back to the lost-reply hint only when there is none (the replacement was not intended); the lost-reply sentence is built once from { command, cause }. Runner suite 823/823 on #3071's c6734bbf04.