copilotkit 4.23.1 → 4.25.0

package/onboarding/prompts/research/gather.md

@@ -41,11 +41,10 @@ and continue when that thing arrives. A pause waits for one of two things:
    pick", gives no answer, and the default that the prompt states applies. Where the
    prompt states no default, ask once more.
 
-Before you end your turn to wait for the developer where the prompt states no default,
-report the pause:
+Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
 ```
 
 When the answer or the result arrives, continue from the step that paused. Do not read an
@@ -65,7 +64,7 @@ Both research subagents failing means this harness has no working subagent at al
 is worth recording once:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard checkpoint --phase delegation-unavailable
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase delegation-unavailable
 ```
 
 Then say once, in your own words, that this environment has no working subagents, so you
@@ -77,11 +76,22 @@ For the rest of this run, wherever a prompt tells you to spawn a subagent, read
 Before you ask the developer any setup question, finish every read-only investigation and
 preflight check in this section.
 
-Prepare two research assignments. Give each research subagent one assignment. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.23.1 onboard read subagent/inspect-repository` first and follow the
-prompt it returns. If that read fails because the subagent cannot use the shell, stop that
-subagent. Run the same command yourself, then spawn a fresh subagent with the returned prompt
-and the same handoff. Require only its assigned packet.
+Prepare two research assignments. Before you spawn either subagent, run these two
+read-only commands yourself, from the target project directory:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard read subagent/inspect-repository
+npx --prefer-offline --yes copilotkit@4.25.0 onboard inspect --json
+```
+
+Give each research subagent the prompt that the first command returns, the whole JSON that
+the second command returns, and one assignment. Tell it that its handoff already holds both,
+so it runs no onboarding command. A coding agent's permission layer can refuse a package
+that runs from the registry inside a subagent, even where it lets you run the same command.
+The run then waits for an approval that nobody sees. Require only its assigned packet.
+
+Give the same JSON to every later subagent that this research spawns, such as a retry, a
+focused directory check, or a conflict verifier.
 
 Start both research subagents in parallel:
 
@@ -92,8 +102,8 @@ Start both research subagents in parallel:
 The research is under way. Continue to the surface-control preflight while it runs:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard read research/preflight
+npx --prefer-offline --yes copilotkit@4.25.0 onboard read research/preflight
 ```
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.23.1 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/merge.md

@@ -48,8 +48,14 @@ app directory. Both results must start with `Status: passed`. Otherwise, use the
 Read the next step only after `login --json` has emitted `type: completed`. If sign-in still
 waits on the developer, end your turn and wait for it: that is a pause.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
 When both research results are merged and sign-in is done, run
-`npx --prefer-offline --yes copilotkit@4.23.1 onboard read research/route`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read research/route`.
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.23.1 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/preflight.md

@@ -27,8 +27,8 @@ Where the device probe found no booted device, that is the whole finding.
 Then merge the research:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard read research/merge
+npx --prefer-offline --yes copilotkit@4.25.0 onboard read research/merge
 ```
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.23.1 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/route.md

@@ -9,7 +9,7 @@ sends the run down one path.
 Before you route on, run this from the target app directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard protect
+npx --prefer-offline --yes copilotkit@4.25.0 onboard protect
 ```
 
 It reads the working tree itself, records every changed or untracked path with a digest,
@@ -44,7 +44,7 @@ On any one of them, run this before you read the three findings below, and witho
 the purpose question:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/channels/start
+npx --prefer-offline --yes copilotkit@4.25.0 onboard read feature/channels/start
 ```
 
 Name the provider to that node so it does not ask again. A `/slack` page names Slack. A
@@ -105,7 +105,7 @@ settle these three from your own reading of the project. Each one comes from the
 packets or it is not proved.
 
 If all three are proved, prove the live starting state before any project file changes. Run
-`npx --prefer-offline --yes copilotkit@4.23.1 onboard read proof/oss-baseline`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read proof/oss-baseline`.
 
 Route there before you ask the developer anything else. The questions after this prompt
 select a framework and a frontend that the findings already name, so a developer who
@@ -116,9 +116,16 @@ these three findings.
 For every other combination of the three, take one more step first. If neither the
 developer nor the repository findings prove what the project is for, ask one guided
 question about the user outcome. This asks what the developer wants to build before you
-select a framework. Give two or three short examples. Record the answer and give it to
-each later subagent. Then run
-`npx --prefer-offline --yes copilotkit@4.23.1 onboard read credentials/plan`.
+select a framework. Give two or three short examples.
+
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
+Record the answer and give it to each later subagent. Then run
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read credentials/plan`.
 
 Do not ask that question on the route above. A project carrying all three states its
 purpose in the application it already serves.
@@ -132,5 +139,5 @@ A purpose question here names a domain before that choice.
 Take the same read named above without asking.
 
 If authentication, inspection, or the baseline capture stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.23.1 onboard read stopped/run-failed`. None of them says anything
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read stopped/run-failed`. None of them says anything
 about whether this project's stack is supported, which is not yet known at this point.

package/onboarding/prompts/starter/clone.md

@@ -13,6 +13,12 @@ dependency manifest: those folders are the developer's projects. `init` refuses
 three. If the target is one of them, stop the shortcut and ask the developer which
 project to use, or to open the coding agent in a new empty folder.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
 Match the selected agent framework and frontend to this table:
 
 | Agent framework                  | Frontend | Framework ID                       | Model key                                 |
@@ -40,8 +46,14 @@ not include Intelligence.
 Get the target directory name from its path. The name can contain 1 to 100 letters,
 numbers, spaces, dots, underscores, or hyphens, in any case. It must not be `.` or `..`,
 start or end with a space, or end with a dot. `init` accepts the name of an existing empty
-directory as it is, so a name such as `MyApp` is valid. Do not rename the directory. If the
-selected pair is not in the table, or the directory name is not valid, stop the shortcut.
+directory as it is, so a name such as `MyApp` is valid. Do not rename the directory. Stop
+the shortcut in each of these cases:
+
+- The selected pair is not in the table.
+- The developer chose a model vendor whose key is not the Model key of the matched row.
+  Each starter runs on the vendor in that column only.
+- The directory name is not valid.
+
 Do not run `init`. No command ran, so this is not a failed shortcut. Go back to the
 `## Documentation` section of the frontend prompt you read before this one, and build the
 project from its pages.
@@ -55,12 +67,18 @@ the derived name.
 Only if the developer asks for an existing project, or asks to see the projects they have,
 read the choices:
 
-`npx --prefer-offline --yes copilotkit@4.23.1 project list --json`
+`npx --prefer-offline --yes copilotkit@4.25.0 project list --json`
 
 Then ask which one to use. Do not order the projects by creation time. If the developer
 already gave this answer, do not ask again. Do not read a secret value. Do not show or
 store a secret value.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
 ## Ask where the model credential lives
 
 The starter reads a model credential, and the `init` command below does not ask for one.
@@ -72,10 +90,37 @@ themselves after the clone. Asking where a credential lives is not requesting a
 value. Never ask for the value itself. If no answer comes, clone anyway. The step after
 the clone pauses for the key.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-model-credential
+```
+
 A path the developer names is theirs to give, including one outside the project. A path
 this run finds is not. Never read a key file the developer did not name. A key found that
 way bills a project nobody chose.
 
+## Record the selected path
+
+This route skips the plan step that records the path, so record it here, once, before
+the clone:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend> --model-vendor <model-vendor> --model-vendor-choice <model-vendor-choice>
+```
+
+- `<starting-state>`: the starting state the research recorded, usually `empty`.
+- `<agent-framework>`: the name of the framework prompt this run read, such as
+  `langgraph-typescript` for `framework/langgraph-typescript`. It is not the Framework ID
+  in the table.
+- `<frontend>`: the Frontend column of the matched row, `nextjs` or `angular`.
+- `<model-vendor>`: `openai`, `anthropic`, `google`, or `other`.
+- `<model-vendor-choice>`: if the developer chose the provider, `developer`. Otherwise,
+  `default`.
+
+If a value is refused, fix it from the choices the earlier prompts gave, and run the
+command again.
+
 ## Clone the starter
 
 Run the command in one step, from any directory. `--dir` names the target, so the app
@@ -84,7 +129,7 @@ Do not inspect another entry in the parent directory. Replace each placeholder w
 recorded value. Do not run a placeholder as a shell argument. If the path holds a space,
 put it in double quotes.
 
-`npx --prefer-offline --yes copilotkit@4.23.1 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
+`npx --prefer-offline --yes copilotkit@4.25.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
 
 `--dir` is always the absolute path of the target directory. `init` builds the app in that
 directory and gives the app the directory's name. Do not add `--name`: `init` refuses
@@ -102,9 +147,76 @@ variable name and never the value. Do not read or copy the key file yourself. If
 reports that it cannot read the model key file, it stopped before it cloned anything. Ask
 the developer for the right path, or run the command again without the flag.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-model-credential
+```
+
+If you cannot pass the key file to `init`, for example because a sandbox refuses the path,
+clone without `--model-key-file`. Then copy the key from `<target>` with one command:
+`cd <target> && npx --prefer-offline --yes copilotkit@4.25.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json`.
+`<env file>` is `.env`, or `agent/.env` for the Microsoft Agent Framework Python starter.
+The command writes the key into that file without printing it and protects the file. If the
+command is refused too, ask the developer to run it. Give them exactly this one line:
+`! cd <target> && npx --prefer-offline --yes copilotkit@4.25.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file>`.
+The command needs no input. Without `!`, they run the same command in a terminal.
+Do not write a `sed`, `grep`, or `cat` command to copy the key.
+
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-model-credential
+```
+
+### For a recorded local choice
+
+If the run recorded the local deployment choice in `deployment/choose-local`, use this
+command instead of the hosted command above. Do not ask the project questions above.
+Local evaluation creates its own empty project, and `init --local` refuses `--create` and
+`--project`.
+
+`npx --prefer-offline --yes copilotkit@4.25.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --local --defer-model --install`
+
+Use the model choice from `deployment/choose-local`. If the developer deferred it, keep
+`--defer-model`. If the developer gave model settings, replace `--defer-model` with
+`--model-config <private-file>`. Do not read or print that file. The CLI selects the latest
+stable release. If the developer gave a candidate manifest for release testing, add
+`--candidate <manifest.json>`. Otherwise, do not add it. The `--dir`, `--no-install` and `--model-key-file` rules
+above apply here too.
+
+If the developer chose guided model setup in `deployment/choose-local`, keep `--defer-model`.
+After `init` reports the stack ready:
+
+Ask the developer to run this command in their own terminal window, in `<target>`:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 local setup
+```
+
+Do not give it as a `!` line, and do not run it yourself. Its guided model prompt needs a
+terminal, and a coding agent's shell has none. Without a terminal, the command stops and
+changes nothing. The prompt asks for the model and its key, and it saves them privately.
+On a running stack, it restarts only Learning. Do not ask for a model file.
+
+Say that the run continues when they reply or resume this session. Report the pause with
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-model-credential`, end your
+turn, and wait. When the developer replies, run
+`npx --prefer-offline --yes copilotkit@4.25.0 local status --json` from `<target>` and read `learning.configuration`.
+
+The command installs the local stack, then connects the starter to it. It writes the
+gitignored `.copilotkit/local.json` stack reference and `.copilotkit/project.json` with the
+local project. It writes `INTELLIGENCE_API_URL`, `INTELLIGENCE_GATEWAY_WS_URL`,
+`CPK_INTELLIGENCE_API_KEY` and `SL_ENABLED` into `<target>/.env`. Later proof steps use
+this local project. Do not run `project select`, and do not provision another key. The
+output names the local dashboard URL. If you deferred the model, the output also says
+`Learning configuration incomplete`. Report both lines to the developer.
+
+### What the command does
+
 The command clones the starter into the empty target directory. It also connects the
-starter to the developer's Intelligence project. The earlier login phase supplies the
-account. The command does not need terminal input.
+starter to the developer's Intelligence project, or to the local stack for a local choice.
+The earlier login phase supplies the account. The command does not need terminal input.
 
 Do not rebuild the starter by hand. Then inspect only the generated
 paths inside the target directory. Record the files, install result, project connection,
@@ -144,7 +256,7 @@ When you ask, name each variable and the file it goes in, and say that the run c
 when they reply or resume this session. Then report the pause and end your turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 This is a pause, not a stop. Do not send a stop report, and do not take a stop route.
@@ -155,10 +267,40 @@ call.
 
 If no credential is missing, report no pause and continue.
 
-Then run `npx --prefer-offline --yes copilotkit@4.23.1 onboard read proof/round-trip`.
+Then run `npx --prefer-offline --yes copilotkit@4.25.0 onboard read proof/round-trip`.
+
+If the local command fails, `init` keeps the cloned starter in `<target>`. Do not run
+`init` again, because the target is no longer empty. Do not delete the starter or the stack.
+Report the exact error, and do not claim that the starter is ready. A failure that names
+Docker is an environment blocker, not a broken run. For example, Docker is stopped or
+missing, or `Docker available resources` is below 4 CPUs, 12 GiB RAM, or 40 GiB storage.
+Tell the developer what to change in Docker. Then report the pause and end your turn:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
+When the developer says that Docker is ready, resume from `<target>` with the same model
+choice. If the run used a `--candidate`, add the same one:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 local setup --defer-model --json
+```
+
+If the run used model settings, replace `--defer-model` with `--model-config <private-file>`.
+Read blockers and the recorded failed step. Do not delete or recreate a failed stack. After
+setup reports the stack ready, connect the starter from `<target>`:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 local connect --approve-connection --json
+```
+
+The connection writes `.copilotkit/local.json`, `.copilotkit/project.json`, and the local
+keys in `<target>/.env`. Then continue with the credential check above. If the resumed
+setup fails again with an error that does not name Docker, take the route below.
 
 If the command fails, report its exact error and do not claim that the starter is ready.
 Then run
-`npx --prefer-offline --yes copilotkit@4.23.1 onboard read stopped/run-failed`. The starter is one this
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read stopped/run-failed`. The starter is one this
 graph ships and the stack was chosen from its own supported list, so a command that
 returned an error is a run that broke, not a setup this release does not support.

package/onboarding/prompts/stopped/run-failed.md

@@ -38,10 +38,16 @@ Name the one fix you propose, and say which file or process it touches. Ask the
 developer whether they approve that one fix. If they decline, or the question cannot be
 put to them, stop here and send the report below.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
 If they approve it, make that one fix and nothing else. Then come back into this run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard resume --message "<approval>"
+npx --prefer-offline --yes copilotkit@4.25.0 onboard resume --message "<approval>"
 ```
 
 Put the developer's approval in `--message`, in one or two sentences: the fix they
@@ -64,7 +70,7 @@ Send one short report. The friction command follows the telemetry setting the de
 already chose, so it needs no separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.25.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped

package/onboarding/prompts/subagent/create-plan.md

@@ -94,7 +94,7 @@ against a dead host, and the failure arrives as an empty-body 404 with no cause
 Ask the CLI for the dependency upgrade, from the target directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard upgrade-plan --json
+npx --prefer-offline --yes copilotkit@4.25.0 onboard upgrade-plan --json
 ```
 
 It reads the installed tree and the registry. Read `status`:
@@ -176,7 +176,7 @@ here is work the developer did not ask for.
 Plan the threads drawer itself: add it from the selected drawer page, where this frontend
 does not already render one. Where this journey's frontend framework ships no threads
 drawer -- React Native --, plan that the thread is proved by
-`npx --prefer-offline --yes copilotkit@4.23.1 verify --round-trip`, which needs no browser. Do not plan a
+`npx --prefer-offline --yes copilotkit@4.25.0 verify --round-trip`, which needs no browser. Do not plan a
 step that opens the managed Intelligence dashboard.
 
 ## Name the files the run writes itself
@@ -218,6 +218,13 @@ step in the plan. Where a protected path you can justify is the only obstacle, t
 stays. Where the plan needs a protected path you cannot justify in that sentence, return
 `Status: blocked`.
 
+Installing or upgrading a package changes the manifest that lists it, such as `package.json`
+or `pyproject.toml`. When a step does that and the manifest is a protected path, list the
+manifest under `Authorization requested`, even if no step edits it by hand. Its consent
+also covers its lockfile, such as `package-lock.json` or `uv.lock`, beside it or at the
+workspace root, so do not list the lockfile on its own line. Install with the package manager's usual command, which
+rewrites the lockfile in place. Never delete a lockfile to regenerate it.
+
 Authorization covers changing a protected path, not removing it. Do not plan the deletion
 of a protected path, and do not plan a step that moves or renames one, which removes it
 under its captured name. If a step cannot be written any other way, return

package/onboarding/prompts/subagent/implement-and-validate.md

@@ -115,7 +115,7 @@ Intelligence: declare each exact version in its app's manifest, then install wit
 project's package manager. Then check the installed tree:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard upgrade-plan --check --json
+npx --prefer-offline --yes copilotkit@4.25.0 onboard upgrade-plan --check --json
 ```
 
 `single` means every direct dependency resolved to one version. `duplicates` names each
@@ -130,7 +130,7 @@ If the check finds duplicates or the baseline regresses, put the manifests and l
 back, leave Intelligence unwired, and report what failed:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard upgrade-plan --revert --json
+npx --prefer-offline --yes copilotkit@4.25.0 onboard upgrade-plan --revert --json
 ```
 
 Then end your turn. Never add an `overrides`, `resolutions`, or `pnpm.overrides` block to

package/onboarding/prompts/subagent/inspect-repository.md

@@ -4,13 +4,19 @@ Work only on the packet you were assigned. Inspect the repository without changi
 
 ## Start with what the CLI already knows
 
-Run this first, from the target project directory:
+Your handoff holds the JSON of this command, which the main coding agent ran from the
+target project directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard inspect --json
+npx --prefer-offline --yes copilotkit@4.25.0 onboard inspect --json
 ```
 
-It answers the deterministic half of both packets exactly, from the same code
+Read that JSON. Do not run the command again. If the handoff holds no inspection JSON, run
+the command yourself. If your harness refuses it, return at once with no packet. Say that
+the harness refused the command, name it, and do not wait for an approval. That is not
+`Status: blocked`: the main coding agent can run the command and do this work itself.
+
+The JSON answers the deterministic half of both packets exactly, from the same code
 `copilotkit verify` uses: the project record by presence, and, for each app or runtime
 directory on its own, the env files, which variable carries the Intelligence key and which
 file it came from, whether that directory's own process can load it, the package manager
@@ -111,6 +117,6 @@ Return one row for each assigned item with its status, evidence path, and a shor
 Use only `proved`, `absent`, or `unproved` for the status. State each absent or unproved item.
 Do not read, print, or return secret values. For `.env` and `.copilotkit/project.json`
 checks, return only paths, presence checks, missing field names, and the one `.env`
-modification time named above. Do not read a file
-outside the project directory. Do not run or return an onboarding command other than
-`onboard inspect`. End your turn after returning the findings to the main coding agent.
+modification time named above. Do not read a file outside the project directory. Do not
+run an onboarding command, except `onboard inspect` when the handoff holds no inspection
+JSON. End your turn after returning the findings to the main coding agent.

package/onboarding/prompts/subagent/prove-oss-baseline.md

@@ -32,7 +32,7 @@ Prove the live runtime in this order:
 4. Confirm from project files that the runtime constructor passes a `runner` option rather
    than an `intelligence` option. A package, import, project file, or key is not use proof.
 5. Run
-   `npx --prefer-offline --yes copilotkit@4.23.1 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
+   `npx --prefer-offline --yes copilotkit@4.25.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
    with the runtime URL or auth header options that this project needs. Require exit zero
    and the JSON `ok` field to be `true`.
 6. Drive one real request through the existing frontend, CopilotKit runtime, and expected
@@ -54,6 +54,11 @@ passed, failed, or skipped, and do not withhold `both-oss` for a skip. A failed
 on an available surface is a baseline failure and is not a skip. Return each predicate and
 its secret-safe evidence.
 
+For each failed predicate, say whether its cause is operational -- a project-owned process
+or port, a request option, or a sandbox block -- or the project itself. Name the check that
+failed, such as the `verify` check id. The main coding agent retries only an operational
+failure.
+
 The default in-memory OSS runner is ephemeral. SQLite, custom, or framework persistence
 can be durable. Report the persistence that project evidence proves, or `unproved`. Do not
 replace it and do not describe all OSS runs as ephemeral.

package/onboarding/prompts/subagent/prove-round-trip.md

@@ -78,7 +78,7 @@ about the failure it was spawned to clear.
 Run this from the target app directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.1 onboard proof-check --json
+npx --prefer-offline --yes copilotkit@4.25.0 onboard proof-check --json
 ```
 
 It starts each app's `dev` script unless a server from that app already listens, and
@@ -103,10 +103,15 @@ A pass on `runtime-process-in-project` proves only that the process runs inside
 project. Ask the running agent which graph or agent ID it serves, and compare that with the
 expected agent ID from Step 1. If they differ, an older build still answers on the port.
 Report it, and stop it only under the rule below. The servers keep running after
-the proof. Then go to Step 5a.
+the proof. Then go to Step 5a. On Windows, `runtime-process-in-project` is `undetermined` and
+marked `advisory`, because the CLI cannot read Windows processes. The checks still pass. Ask
+the agent ID question all the same.
 
 Otherwise sort `firstFailure`, and run the command again after each repair:
 
+- `model-key`: the credentials step found the model key missing, or the vendor refused it.
+  The agent cannot answer a chat without it, so the command started nothing. Do not change
+  code, and do not write a key. Return it with its detail, before the browser.
 - `runtime-answers`: nothing answered, or the project records no runtime URL. When the
   record holds no URL, the command records one itself if exactly one port in the project
   answers as a runtime. So this failure means it found none, or more than one. Read the
@@ -114,7 +119,7 @@ Otherwise sort `firstFailure`, and run the command again after each repair:
   asking. Read the port from the log, not from the plan, and record it:
 
   ```text
-  npx --prefer-offline --yes copilotkit@4.23.1 onboard runtime-url --url <runtime-url>
+  npx --prefer-offline --yes copilotkit@4.25.0 onboard runtime-url --url <runtime-url>
   ```
 
   `<runtime-url>` is the project's runtime URL, or the plan's, with its port replaced by the
@@ -129,8 +134,37 @@ Otherwise sort `firstFailure`, and run the command again after each repair:
 - `verify:intelligence_thread_routes`: usually a missing `identifyUser` where the runtime is
   constructed. Return it for implementation. Never remove a `mode: "single-route"` mount
   to satisfy it.
-- `round-trip:agent_answers` naming `user-not-identified`: this project's `identifyUser` reads a
-  session the CLI does not carry. Run again with `--header "Name: value"` for what it reads.
+- `round-trip:agent_answers` naming `user-not-identified`, or at `fail` because the runtime
+  refused the thread the check sent: the check starts its own run on a new thread, and this
+  app refuses that run. Its `identifyUser` reads a session the CLI does not carry, or it runs
+  only threads that it created. That is the app working. Do not change the app to accept the
+  run, and do not ask the developer for a session cookie. Prove the round trip on a thread
+  the app created:
+  1. Open the `frontendUrl` the checks resolved, under the Step 6a rules. The app needs a
+     signed-in user. Where the page asks for a sign-in, do not create an account and do not
+     enter credentials.
+  2. Send the Step 1 request once, on a new thread. On a second attempt, send it again: a
+     thread from before the repair does not prove the repaired app.
+  3. Read that request's `threadId` from the request body the page sent to the runtime
+     endpoint, in the network requests.
+  4. Run the checks again with `--thread <id>`. They read that thread from the platform with
+     the project key and start no run. The checks fail a thread that did not change during
+     this run, a thread whose newest message has no answer, and a thread of another agent.
+     Follow that detail once, with a new thread, before you report a failed proof.
+
+  Return `Status: blocked` with this check and its evidence when you cannot do these steps:
+  - a cloned-starter run, which opens no browser,
+  - no browser tool loaded,
+  - a sign-in you cannot complete,
+  - a browser tool that does not show request bodies.
+
+  Say that the developer can
+  send one message in the app and give you its thread id, which is all `--thread` needs.
+  The app is not at fault, so do not report `failed`. Pass `--header "Name: value"` instead
+  only when the developer offers what `identifyUser` reads.
+
+  Where the handoff carries a thread id from the developer, skip the numbered steps above
+  and do not open the app for them. Run the checks with `--thread <id>` at once.
 - `round-trip:page_context_reaches_agent` at `fail`: the agent answered the plain request
   and recorded nothing for the request that carried context. Return it with its evidence as
   a failed proof step. At `undetermined` and marked `advisory`, the agent answered without
@@ -140,6 +174,7 @@ Otherwise sort `firstFailure`, and run the command again after each repair:
   still does not complete, prove the path in Step 5a, and report the check with its detail.
 - `round-trip:learning_container_assigned` at `fail`: the thread carries no container or
   another one. A thread cannot move, so start a new thread rather than repairing that one.
+  With `--thread`, send the Step 1 request on a new thread in the app, and pass that id.
   `features.self_learning` and `/info` are not evidence of an assignment.
 - `env-files-current`: the process it names started before its env file was written, and
   has to start again before a 401 means anything. Report it. Do not restart or stop it.
@@ -160,6 +195,11 @@ with a prefix rule for `curl`, run it again, and do not record a failed predicat
 
 ### Step 5a -- Prove that the page's data reaches the model
 
+Where the proof checks needed `--thread`, the app refuses a run that Steps 5a and 5b send,
+for the same reason. Skip both steps and send no run. Record that they sent no run for that
+reason, and prove the page's data and the component in the browser instead, at Steps 6
+and 7.
+
 `verify --round-trip` asks a question that needs no context. Where the frontend's files
 call a context hook, it also sends one token as context and reports
 `page_context_reaches_agent`, whose `pass` proves that the agent's model sees context at
@@ -217,7 +257,8 @@ to read.
 Read the registrations this project's frontend declares, by name. Step 5a already sent the
 step 1 request with those declarations, so read the tool calls out of the events Step 5a
 captured for the run carrying the page's unchanged context. Do not send that request again.
-Where Step 5a sent no run, because this journey shares no page data, send the step 1 request
+Where Step 5a sent no run because the proof checks needed `--thread`, send no run here
+either. Where Step 5a sent no run, because this journey shares no page data, send the step 1 request
 to `<runtime>/agent/<agent id>/run`, carrying those declarations, and read the tool calls out
 of that run's own events. Where the Step 5a run carried none of those declarations, send
 that run once more with them, and read that run instead. Never report a wiring gap from a run
@@ -249,8 +290,10 @@ For a recorded `both-oss` starting state, this step has no component to render.
 same request the baseline recorded, require the same kind of user-visible result the
 baseline produced, and require that the thread for that request is listed in the drawer.
 Where this journey's frontend framework ships no threads drawer -- React Native --, prove
-that thread with `npx --prefer-offline --yes copilotkit@4.23.1 verify --round-trip`, which reads the
-answer back off the thread and needs no browser. Record which of the two you proved.
+that thread with `npx --prefer-offline --yes copilotkit@4.25.0 verify --round-trip`, which reads the
+answer back off the thread and needs no browser. Where the proof checks needed `--thread`,
+prove the thread for this request with `verify --thread <id>` instead. Record which of the
+two you proved.
 
 Use the surface control the main coding agent recorded for your environment. That finding
 is the answer, and there is nothing here for you to go looking for. Do not register a
@@ -277,7 +320,7 @@ limit can be ten minutes. You cannot interrupt a call while it runs, so the limi
 what you do after one. If a browser call took longer than 60 seconds to return, the browser
 control is unresponsive. Do not call the browser again in this attempt. A second call to a
 hung tool waits as long as the first one did. Run
-`npx --prefer-offline --yes copilotkit@4.23.1 verify --frontend-url <the frontendUrl the proof checks resolved> --json` once,
+`npx --prefer-offline --yes copilotkit@4.25.0 verify --frontend-url <the frontendUrl the proof checks resolved> --json` once,
 and record the `frontend_assets_served` result. Report the outcome `failed` with the cause
 `browser-control-unresponsive`. The application is not at fault on this evidence: every
 step before the browser proved the runtime without one, and no repair to the project can
@@ -287,7 +330,7 @@ reach the tool.
    the page to finish loading. Do not retype the host, and do not substitute a URL a tool
    offers you by default. Where the page loads but its styling is missing or the chat
    control is dead, run
-   `npx --prefer-offline --yes copilotkit@4.23.1 verify --frontend-url <the url you opened> --json`
+   `npx --prefer-offline --yes copilotkit@4.25.0 verify --frontend-url <the url you opened> --json`
    before you diagnose anything else. A dev server can serve its page and refuse every
    static chunk behind it, and on screen that is indistinguishable from a broken
    integration. The `frontend_assets_served` check tells the two apart.