docs(ios-runner): RUNNER_PROTOCOL.md points at the wrong file and omits recovery and busy codes

Open Beginner friendly

#2,797 opened on Sep 23, 2026 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty: 2/5
Estimated time: 1-3 hours
Newbie friendliness: 75/100

Issue type: Documentation
Clarity: Clearly specified
Activity status: Active
Tech stack: swift, typescript
Domain: documentation

Research direction

The file to update is apple/runner/RUNNER_PROTOCOL.md. First, verify the current command names location in packages/platform-apple/src/runner/runner-contract.ts:53-94. Then, examine the linked files for recovery and error codes: runner/runner-command-recovery.ts, AgentDeviceRunnerUITests/RunnerTests+Transport.swift, and RunnerTests+CommandJournal.swift. Update the document with correct references and brief explanations, ensuring all symbols exist via git grep. Finally, run pnpm check:agent-guidance to confirm the changes pass.

Written by the indexing model from the issue text.

Description

documentation good first issue ready-for-agent

Purpose

apple/runner/RUNNER_PROTOCOL.md:67 says the command names live in runner-client.ts. They are in packages/platform-apple/src/runner/runner-contract.ts:53-94. The doc also doesn't mention:

commandId and status recovery (the command journal)
runnerFatal and runnerMainThreadBusy
the error codes RUNNER_BUSY, RUNNER_WEDGED and MAIN_THREAD_TIMEOUT

Line references are at 01328de411.

Required behavior

Fix the pointer.
Add a short section for each missing concept: when it is produced, what it means, and what the daemon does with it. Link to the declaration sites (runner-contract.ts, runner/runner-command-recovery.ts, apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift, RunnerTests+CommandJournal.swift) and don't copy tables.

Completion conditions

Every symbol the doc names exists: check with git grep.
pnpm check:agent-guidance is green, if the doc is part of that check.

Dominant language: TypeScript
Stars: 4.7k
Forks: 304
Avg merge: 11h 29m
Merged PRs (30d): 514

Contributor guide

Open the contributing guide

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.

Similar issues

Ajv defaults: non-standard "format": "json" in third-party schemas (e.g. Notion) warns twice per property — register it like #2601 Open

Difficulty 2/5 1-3 hours Newbie friendliness 70/100

modelcontextprotocol/typescript-sdk#2854 · Opened Sep 24, 2026
[Bug]: ctx_search rejects singular 'query' param despite schema declaring it valid Open

Difficulty 2/5 1-3 hours Newbie friendliness 75/100

mksglu/context-mode#1200 · Opened Sep 24, 2026
[chore]: test(search): Migrate ResultItemTitle unit tests to TypeScript Open

Difficulty 2/5 1-3 hours Newbie friendliness 75/100

jaegertracing/jaeger-ui#4506 · Opened Sep 24, 2026
[BUG] "$250 credit for cloud sessions" gift icon is unclickable Open

area:desktop area:ui bug platform:macos

Difficulty 2/5 1-3 hours Newbie friendliness 75/100

anthropics/claude-code#96687 · Opened Sep 24, 2026
[GOOD FIRST ISSUE]: Clean Up Frontend Authentication Page & Context Open

good first issue

Difficulty 1/5 Under an hour Newbie friendliness 95/100

AOSSIE-Org/DebateAI#582 · 2 comments · Opened Sep 24, 2026

More TypeScript issues