Skip to content

feat(remote): surface a script delivery failure on every caller surface - #4582

Merged
thymikee merged 9 commits into
mainfrom
feat/script-delivery-surfaces
Nov 16, 2026
Merged

thymikee merged 9 commits into
mainfrom
feat/script-delivery-surfaces

Conversation

@thymikee

@thymikee thymikee commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Part of #4564; batch step delivery moves to #4595.

An action that records a remote script version keeps its success when that version cannot reach the caller file. The wire already answered scriptDeliveryFailure; nothing above it passed the field on, so a caller read a stale file as current.

readScriptDeliveryFailure in the kernel reads the field from a response, and readScriptDeliveryDisclosure pairs it with the warning written beside it. Every result that can carry a script version now spreads both: the SDK open, sessions.close, apps.close, snapshot and screenshot results, the CLI human output and --json payload, and the MCP tool text and structured content. The SDK close also keeps the response's warnings, which the CLI human output prints.

remote_script_batch_close_unsupported stands unchanged: a batch delivers no script versions from its steps, so closing an armed remote recording inside one stays refused until #4595 gives the daemon one receipt to deliver from.

Tests: a table covers each serializer, including that plain input yields neither field, and the provider scenario discloses a failed final download on the SDK result, the CLI --json and MCP. Production code is 9 files, +131/-7.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.32 MB 6.32 MB +2.8 kB
Package (unpacked) 6.32 MB 6.32 MB +2.8 kB
Package (download) 1.92 MB 1.92 MB +432 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 37.0 ms 27.7 ms -9.3 ms
CLI --help 65.5 ms 56.4 ms -9.2 ms

@thymikee
thymikee force-pushed the feat/script-delivery-surfaces branch from d03f541 to 4556e33 Compare November 16, 2026 11:24
@thymikee

thymikee commented Nov 16, 2026 •

Copy link
Copy Markdown
Member Author

Thanks for this. I reviewed 4556e33 and found two things to fix before merge. CI is green (21 checks, none failing), and there are no conflicts.

A script delivery failure that the daemon reports on a batch step never reaches the batch result. disclosedDelivery lifts the typed scriptDeliveryFailure only from this client's own payload, and from the finished steps it lifts only warnings (remote-batch-script-delivery.ts#L283). Example: batch [wait, close], where remoteCloseScript cannot write the final script. The client delivers the older wait version and sets savedScript. It then lifts only the warning text, and the session is already closed, so nothing else adds the field. The caller file lacks the terminal close, and the CLI --json, SDK and MCP batch results show savedScript with no top-level scriptDeliveryFailure. An agent that reads the typed field will treat the stale file as current, and remote-proxy.md:129 and ADR 0016 promise the field reaches the batch result. The rule the code must satisfy: the batch payload carries scriptDeliveryFailure whenever this client's delivery, or any finished step, reports one for the open publication and no newer delivered version supersedes it. This client's own failure wins. Otherwise read each step through readScriptDeliveryFailure in plan order, keep the last one for the publication, and lift only its paired warning. Please add a provider or unit case where a step answers a daemon-side scriptDeliveryFailure.

normalizeStepCommand is a verbatim copy of normalizeBatchCommandName (remote-batch-script-delivery.ts#L323, original in batch-policy.ts#L74). The batch-policy doc says every caller that decides something about a step must resolve the name through that function. Here the copy decides plan authorization and the close and retire decision. If the daemon's normalization changes, for example with alias resolution, a finished close stops matching, the final script is not delivered and the record is not retired. Please import normalizeBatchCommandName from @agent-device/command-registry/batch-policy and add the workspace dependency to packages/remote/package.json. Remote is rank 4 and command-registry rank 1, so the layering allows it.

Not blocking, and you can take or leave these: isUsableVersion (L265) restates the guard in publishScriptVersion, so one exported isPublishableScriptVersion in session-script-destination.ts could serve both; no test covers the open, apps.close, snapshot and screenshot disclosure spreads or their serializers (index.ts#L614), so deleting any one leaves CI green, and one table-driven normalizer test would pin them; disclosedDelivery lifts every finished step's warnings onto the batch, so unrelated capture warnings and warnings from a superseded write also appear, and lifting only the warning paired with the typed failure fixes that (L294); deliverBatchScript fakes command: 'close' so the retirement rule applies (L173), and an explicit closedPublicationId input on sessionScriptDelivery would be clearer; the bare catch { return undefined; } in materializeRemoteBatchPartialArtifacts emits no diagnostic (daemon-artifacts.ts#L531), where the owner emits a session_script_delivery_failed warn; the batch path returns top-level artifacts exactly as the daemon answered, while the single path drops failed script artifacts and sets localPath (L30); readScriptDeliveryFailure is a kernel and wire-surface export with one reader, so the doc's claim that every surface uses it does not yet hold (contracts.ts#L230), and the fix above would make remote a second reader; the snapshot spread sets warnings again from the same data.warnings already read two lines above, so adding only scriptDeliveryFailure, as screenshot does, is enough.

Could the batch side be much smaller? Keep the five SDK spreads and the serializer helper. Give sessionScriptDelivery an explicit retire input and export one publishable-version predicate. Then replace the 333-line module with about 60 lines in daemon-artifacts.ts. Read the plan through normalizeBatchCommandName, take the finished prefix (with the step === executed + 1 check on the error path), collect script artifacts from the top level and finished steps, and pick the highest revision. Run the single-response owner on that artifact, with retire set when a finished plan step is close. Lift disclosure with readScriptDeliveryFailure: this client's failure, else the last finished step's failure for that publication, plus only its paired warning. That would remove DeliveryContext, isUsableVersion, normalizeStepCommand and the withBatchDisclosure/disclosedDelivery pair, and fix both findings above. It needs a small API change in session-script-destination.ts and a workspace dependency from remote on command-registry. Do you see a reason to keep the larger module?

The CodeQL thread on the polynomial regex in session-script-destination.ts no longer applies: the flagged hunk is gone at 4556e33, and withoutTrailingSlashes now uses a loop, so it can be resolved (thread).

The first finding comes from reading the path from remoteCloseScript write failure through step data to disclosedDelivery, and no run has reproduced it. Only the open, close, snapshot and screenshot CLI --json formatters were traced for scriptDeliveryFailure, and the MCP error result of a failed batch was not traced. A device run is not needed for this change. After the two fixes, the merge needs a green CI run on the new head.

@thymikee
thymikee force-pushed the feat/script-delivery-surfaces branch from a385901 to f09f36f Compare November 16, 2026 13:22
@thymikee

Copy link
Copy Markdown
Member Author

Yes — it could, and it now is. f09f36fcb7 adopts that design; I see no reason to keep the larger module. It is rebased on current main, so the tree is conflict-free again.

Line counts

Before After
Batch owner remote-batch-script-delivery.ts, 333 lines (218 code) inline in daemon-artifacts.ts, 159 lines (120 code)
Batch answer readers (plan, finished prefix, disclosure) inside that module remote-batch-answer.ts, 127 lines (86 code)
Production delta of this round −81 lines (307 added, 388 deleted)

The batch side is 286 lines in two places instead of 333 in one. The second file exists so those readers stay off the client's eager import path: daemon-artifacts.ts sits in packages/daemon-client/src/index.ts's closure, and the eager-closure gate fails a static edge from it to command-registry/batch-policy, so the readers load on demand with the script owner. Production code for this round is net smaller; tests are larger. remote-batch-script-delivery.ts is deleted, and DeliveryContext, isUsableVersion, normalizeStepCommand and the withBatchDisclosure/disclosedDelivery pair are gone. sessionScriptDelivery takes closedPublicationId instead of a faked command: 'close', isPublishableScriptVersion is one exported predicate used by publishScriptVersion and the batch scan, and the plan resolves through normalizeBatchCommandName (workspace dependency and tsconfig reference added).

Finding 1 — a step's daemon-side failure now reaches the batch payload

The disclosure takes this client's own failure first, else the last finished step's failure whose publicationId matches, and lifts only the warning written beside that one failure. A version saved from a later step supersedes it. Covered by a finished step that reports a write failure is disclosed when an older version is delivered (your [wait, close] case: savedScript and the typed failure on one payload) and a close step that names the publication retires the record with no artifact to deliver (no version to deliver), plus a step failure superseded by a newer delivered version is not disclosed and a batch step that cannot save its version discloses it on the batch payload. Dropping the step branch turns the first two red, and both are red at 4556e33.

Finding 2 — one normalizer

Imported from @agent-device/command-registry/batch-policy; a batch step named with other case or spaces still authorizes its delivery and retirement pins that the plan check and the daemon's step naming agree.

Cross-check items

  • The finished-prefix reader requires step === executed + 1, step <= plan.length, and that the normalized failing command is the plan's entry at that position. a failed remote batch whose step report disagrees with its entries delivers nothing and a failed remote batch whose report does not describe the submitted plan delivers nothing cover these, and the RPC fixture no longer submits step: 3 against a two-step plan. Dropping the command check turns the second one red.
  • The cap tests now pin which candidate survives: a batch reads at most its bound of step artifacts and keeps the newest version of the payload, a batch that names three hundred script versions keeps the bounded candidate and costs one download, a batch that names one hundred script versions in one step stops at the per-payload bound. Raising either bound to unbounded turns all three red, and each says which artifact then leaks in.
  • The failed-batch catch emits the session_script_delivery_failed warn diagnostic: a failed batch whose step entries cannot be read reports the delivery failure.
  • The batch path rewrites the answer's own artifacts the way the single path does: a script entry that did not arrive is dropped, the delivered one carries localPath.

Non-blocking notes, taken

  • One table-driven test per owner pins the spreads and the serializers: packages/client/src/__tests__/index-script-delivery-disclosure.test.ts (sessions.close, apps.close, apps.open, capture.snapshot, capture.screenshot, each also with a malformed failure object) and packages/command-output/src/output/result-serialization-script-delivery.test.ts (open, session close, snapshot); screenshot --json is pinned in src/cli/commands/__tests__/screenshot.test.ts. Removing one spread, or the serializer helper's typed field, turns one of them red.
  • The snapshot spread sets only scriptDeliveryFailure, since the annotations reader two lines above already read warnings from the same payload.
  • readScriptDeliveryFailure now has remote as a second reader, so the doc claim holds.

remote-proxy.md and ADR 0016 state the disclosure rule now (own failure, else the last finished step's unless superseded; only the paired warning) instead of the earlier wording. The CodeQL thread was already resolved; the flagged hunk is gone.

@thymikee

Copy link
Copy Markdown
Member Author

The PR is ready at f09f36f: the earlier findings from the review of 4556e33 (#4582 (comment)) are fixed and I found no new problems.

Not blocking, take or leave: readBatchDisclosure picks warnings by matching their text against the failure message and hint, and the merge in daemon-artifacts.ts replaces the batch payload's own warnings. An empty failure message matches every warning of that step, and the daemon's own write warning is dropped when the client download also fails. Setting warnings to [...readResponseWarnings(data), ${failure.message} ${failure.hint}] would remove the text match and keep both.

The [wait, close] failed-final-write path is traced statically; the unit case at daemon-artifacts-batch-script.test.ts:340 covers it with a hand-built step answer.

The code-scanning thread on the polynomial regex no longer applies, since withoutTrailingSlashes is now a loop, so it can be resolved: #4582 (comment)

CI is green with 24 checks and none failing, and there are no conflicts. The PR is still a draft, so it needs to be marked ready for review before merge.

@thymikee

Copy link
Copy Markdown
Member Author

All four are in at d14e68a. The root cause was the same in the three blockers: retirement and disclosure read the plan or the counts beside the answer's proof instead of using it. readBatchAnswer now returns one validated prefix — the steps the answer proves ran, of the recording this client armed — and the publication, the newest version, the close decision and the disclosure are all derived from it.

  1. Disclosure on a failed batch. A validated step keeps its scriptDeliveryFailure whether or not the batch delivers, so a failed batch whose steps carry only failures still answers with the failure and its warning. daemon-artifacts-batch-script.test.ts — "a failed batch whose finished step reports a write failure still discloses it".
  2. Foreign revision. Version candidates must name a recording this client armed before revisions are compared, so a foreign revision 999 no longer masks this recording's revision 2. daemon-artifacts-batch-script.test.ts — "a step script of another recording never outranks the newest version this client is owed".
  3. Retirement. closed is true only when the plan's close position is a validated step the answer reports as succeeded, so the [wait, close, snapshot] report whose entry 2 names wait retires nothing. daemon-artifacts-batch-script-disclosure.test.ts — "a finished count that passes the plan close entry names no close and retires nothing".

On the non-blocking note: agreed, and it went further than the dropped warning. warnings is now [...readResponseWarnings(data), ${failure.message} ${failure.hint}] — the text match is gone, which the repository's writing rules ask for anyway, and a daemon-side write failure plus a client-side download failure now report both lines. Covered by "a batch whose daemon write and client download both failed reports both warnings", which is red at f09f36f with one warning instead of two.

Hardening: the serializer table now calls each serializer with plain input and asserts both fields are absent, so a serializer that invents a disclosure fails; and a screenshot-typed entry that borrows the savedScript field at revision 900 is no longer a candidate ahead of a valid script ("a step entry that borrows the script field under another artifact type is not a candidate" — red when the candidate guard is loosened to the field-OR-type test).

Production code is +47 lines over f09f36f: remote-batch-answer.ts carries the validation it used to lack, daemon-artifacts.ts gives up 41. Each blocker's test was checked red at f09f36f. Format, lint, typecheck, build, fallow, layering, wire-compat, the affected unit lanes and the remote-script publication scenario are green locally, and pnpm check:affected --run --head HEAD passes on d14e68a with exactCommit=true. Leaving this as a draft for the cross-check.

thymikee and others added 7 commits November 16, 2026 16:03
An action that records a remote script version keeps its success when that
version cannot reach the caller file, so the caller needs one field that says
the file is stale. `readScriptDeliveryFailure` reads it from a response, and
every result that can carry a script version now spreads it beside the
warning: the SDK open, close, snapshot and screenshot results, the CLI human
output and `--json`, and the MCP tool text and structured content.

A batch delivers the script versions its own steps record. Each step is
published through the session-script owner under its own command name, in step
order, so a step that closes the recording retires the caller record the way a
standalone close does, and a step that only records a version leaves the record
open for the next one. The destination still comes only from the record this
client's own `open --save-script` wrote, so a response never chooses a path, and
a step script of another publication still writes nothing. That retires the
`remote_script_batch_close_unsupported` refusal, which existed only because a
batch delivered nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tted

A batch answer carries one entry per step, and the client delivered whatever
the answer named. That made the response the authority over a caller-owned
record: an entry planted in place of a `wait` step could name this client's
publication and retire it, and its artifact list was unbounded, so one answer
asking for a thousand duplicate versions spent a thousand downloads. Delivery
now runs on the plan THIS client submitted: an entry must be the plan's own
command at the plan's own position and a step that finished, and anything else
is reported exactly as the daemon answered it, with no download, no destination
and no retirement. Of the versions one payload names, only the newest is taken,
and a duplicate or a version no newer than one already accepted is dropped
before any request, which caps one answer at one download per submitted step.

A `close` step that names this client's publication now reaches the owner even
when it carries no artifact, so a recording the daemon could not finish is
still forgotten instead of staying active beside a file that never gained its
final version.

A failed batch reports the steps it finished in the error's `partialResults`,
which never reached the code that materializes a successful response. Those
steps are delivered before the error is rehydrated, under the same plan bound,
so `[wait, close, snapshot]` that fails on `snapshot` still writes the final
script and still ends the recording; the batch error itself stands.

A batch's own output reads the batch payload, so a step's warning and typed
`scriptDeliveryFailure` are lifted onto it: the CLI `Warning:` line, the MCP
tool text and `--json` and structured content now say the caller file is stale,
instead of printing only "OK Closed: journey".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A batch answer is untrusted input, and the per-step delivery path read it
step by step. A failing step's report could carry successful entries for
steps that never ran, so a forged partial result retired a close the caller
never ran. A malformed publication ID threw while it was interpolated, which
turned a successful batch into a client failure. Filtering revisions
re-scanned every earlier version, so a large answer blocked the caller. And a
successful batch whose steps carried no script stopped before its own payload,
leaving the caller's file stale behind a newer version the daemon had stamped.

Deliver at most ONE version per batch. Every version is the whole recording,
so only the newest of the open publication matters: one linear, bounded scan
reads the plan's finished steps and the batch payload and keeps that one, and
one delivery goes through the session-script owner.

Derive the completed prefix from the submitted plan and cross-check it against
the step and executed count the error names, so entries at or after the failure
authorize no download and no retirement. Retire only when that prefix contains
the close step, with or without an artifact. Validate each candidate with the
publisher's own guards, so no response value reaches a record lookup, a path,
or a download request.

Reports #4564 review findings 1 to 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ints

ADR 0016 said every recorded action costs one download without naming the
batch case, and the ledger rationale still described the per-step path this
module no longer takes.

Reports #4564 review finding 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ler path

The batch script owner is replaced by one delivery path: read the plan the caller
submitted, take its finished prefix, pick the newest publishable version the answer
names, and run the single-response owner on that one artifact. `sessionScriptDelivery`
takes an explicit `closedPublicationId` instead of a faked `command: 'close'`, and
`isPublishableScriptVersion` is one predicate used by the publisher and the batch scan.
Step names resolve through `normalizeBatchCommandName`, so the plan check and the
daemon's own step naming cannot drift apart.

A finished step's `scriptDeliveryFailure` now reaches the batch payload: this client's
own failure wins, otherwise the last finished step's failure for that publication,
unless the saved version came from a later step. Only the warning written beside that
failure rides up. A step entry outside the finished prefix, or one whose report does not
describe the submitted plan, authorizes nothing. The failed-batch catch emits the
`session_script_delivery_failed` diagnostic, and the batch path rewrites the answer's own
artifact list the way a single response does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d prefix

A batch answer proves which of the caller's steps ran. Retirement, disclosure
and the newest version each read the plan or the counts beside that proof, so
three findings followed: a failed batch that carried only step failures lost its
disclosure, a foreign revision masked the version this client was owed, and a
finished count that passed the plan's `close` entry retired a recording whose
close nobody ran.

`readBatchAnswer` now returns ONE validated prefix — the steps the answer proves
ran, of the recording this client armed — and the publication, the newest
version, the close decision and the disclosure all come from it. Candidates for
the newest version must name a recording this client armed, so another client's
revision cannot outrank the caller's own file. Retirement needs the plan's
`close` position to be a validated step the answer reports as succeeded.
Disclosure runs whatever a download did, and answers with the payload's own
warnings plus this failure's line, so a daemon-side write failure and a
client-side download failure are both reported and no warning text is matched.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…h closes

Batch step delivery moves to #4595, where it waits on a daemon-side delivery
receipt. This carries the caller-facing half only: every result that recorded a
remote script version discloses a version that did not arrive, so no caller
reads a stale file as current.

`readScriptDeliveryFailure` reads the response field the daemon already answers,
and `readScriptDeliveryDisclosure` pairs it with its warning. The SDK `open`,
close, snapshot and screenshot results, the CLI human output and `--json`, and
the MCP tool result each carry both, and the SDK close keeps the response's
warnings the CLI prints.

`remote_script_batch_close_unsupported` stands as it was: a batch delivers no
step versions, so closing an armed remote recording inside one stays refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee
thymikee force-pushed the feat/script-delivery-surfaces branch from d14e68a to 0ebfbfb Compare November 16, 2026 15:16
@thymikee

Copy link
Copy Markdown
Member Author

Split per your call: this PR now carries the caller-facing half only. Batch step delivery moves to #4595, which is the shape that needs a daemon-side receipt.

Removed: remote-batch-answer.ts, the batch routing in daemon-artifacts.ts and the failed-batch hook in daemon-client-rpc.ts, the batch fixtures, batch unit tests and the three batch provider scenarios. hasScriptRecord, the isPublishableScriptVersion export, the closedPublicationId input and the @agent-device/command-registry dependency went with them — nothing else used them. remote_script_batch_close_unsupported and its tests are back exactly as on main, and the branch is rebased onto current main.

Kept: scriptDeliveryFailure on the SDK, CLI (--json and human) and MCP results; the SDK close keeps the response warnings and the CLI human output prints them; the table-driven serializer tests, including the plain-input cases that assert neither field appears; and the provider scenario that discloses a failed final download on all three surfaces.

Docs: ADR 0016 keeps the batch limitation, now pointing at #4595; remote-proxy.md and replay-e2e.md describe the result fields and the refusal. The wire ledger is main's again, plus one additive digest for the new readScriptDeliveryFailure reader.

Five findings from the d14e68a cross-check are not fixed here — they belong to the batch reader, so they move with it to #4595. Net against main: 9 production files, +131/-7. Still a draft.

@apex-sentinel-staging

apex-sentinel-staging Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 0 no longer raised

No open findings.

Reviewed with this repository's own Sentinel configuration (cfe08502f0f6).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

Earlier reviews

Review of 8f0ecc63 · 16.11.2026 15:40 UTC

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 0 no longer raised

No open findings.

Reviewed with this repository's own Sentinel configuration (cfe08502f0f6).

Review of 0ebfbfb6 · 16.11.2026 15:26 UTC

Apex Sentinel · ✅ Approve

No open findings.

2 findings below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (cfe08502f0f6).

…file

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee
thymikee marked this pull request as ready for review November 16, 2026 15:39

@cubic-dev-ai cubic-dev-ai Bot left a comment

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.

4 issues found across 18 files

You’re at about 96% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

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="src/cli/commands/__tests__/screenshot.test.ts">

<violation number="1" location="src/cli/commands/__tests__/screenshot.test.ts:95">
P3: The fixture's `warnings` should be the wire string the daemon writes, `${failure.message} ${failure.hint}`, not `failure.message` alone. Otherwise the assertion only checks the fixture against itself. Update both the fixture and the `warnings` assertion.</violation>
</file>

<file name="test/integration/provider-scenarios/remote-script-publication.test.ts">

<violation number="1" location="test/integration/provider-scenarios/remote-script-publication.test.ts:616">
P3: `createArtifactGate` repeats the inline artifact-refusing gate already written in the refresh test. Have that test call `createArtifactGate(proxy.baseUrl, () => refuseArtifacts)` so the forwarding logic lives in one place.</violation>
</file>

<file name="packages/client/src/index.ts">

<violation number="1" location="packages/client/src/index.ts:609">
P3: The leveled snapshot branch returns the raw payload, so a malformed `scriptDeliveryFailure` reaches the caller unchecked. Pass that field through `readScriptDeliveryFailure` on the leveled path too, as `presentedSurface` already is.</violation>

<violation number="2" location="packages/client/src/index.ts:621">
P3: Add `'scriptDeliveryFailure'` to the `Pick<CaptureSnapshotResult, ...>` union in `optionalSnapshotResponseFields`. The union is the documented list of fields this helper can return, and the new field is missing from it.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

path: '/tmp/shot.png',
width: 40,
height: 20,
warnings: [failure.message],

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 fixture's warnings should be the wire string the daemon writes, ${failure.message} ${failure.hint}, not failure.message alone. Otherwise the assertion only checks the fixture against itself. Update both the fixture and the warnings assertion.

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/cli/commands/__tests__/screenshot.test.ts, line 95:

<comment>The fixture's `warnings` should be the wire string the daemon writes, `${failure.message} ${failure.hint}`, not `failure.message` alone. Otherwise the assertion only checks the fixture against itself. Update both the fixture and the `warnings` assertion.</comment>

<file context>
@@ -77,6 +77,37 @@ test('screenshot --json carries response-level warnings in the data', async () =
+    path: '/tmp/shot.png',
+    width: 40,
+    height: 20,
+    warnings: [failure.message],
+    scriptDeliveryFailure: failure,
+  });
</file context>

* A gate in front of the daemon proxy that answers the artifact downloads of a refused moment with
* 503, which is how these scenarios make one delivery fail.
*/
async function createArtifactGate(

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: createArtifactGate repeats the inline artifact-refusing gate already written in the refresh test. Have that test call createArtifactGate(proxy.baseUrl, () => refuseArtifacts) so the forwarding logic lives in one place.

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 test/integration/provider-scenarios/remote-script-publication.test.ts, line 616:

<comment>`createArtifactGate` repeats the inline artifact-refusing gate already written in the refresh test. Have that test call `createArtifactGate(proxy.baseUrl, () => refuseArtifacts)` so the forwarding logic lives in one place.</comment>

<file context>
@@ -438,3 +450,197 @@ test('close delivers the final script after it stops an app log', async () => {
+ * A gate in front of the daemon proxy that answers the artifact downloads of a refused moment with
+ * 503, which is how these scenarios make one delivery fail.
+ */
+async function createArtifactGate(
+  upstreamUrl: string,
+  refused: () => boolean,
</file context>

...(snapshotDiagnostics ? { snapshotDiagnostics } : {}),
// `readSerializedSnapshotCaptureAnnotations` above already reads this response's `warnings`, so
// only the typed field needs adding here.
...(scriptDeliveryFailure === undefined ? {} : { scriptDeliveryFailure }),

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: Add 'scriptDeliveryFailure' to the Pick<CaptureSnapshotResult, ...> union in optionalSnapshotResponseFields. The union is the documented list of fields this helper can return, and the new field is missing from 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/client/src/index.ts, line 621:

<comment>Add `'scriptDeliveryFailure'` to the `Pick<CaptureSnapshotResult, ...>` union in `optionalSnapshotResponseFields`. The union is the documented list of fields this helper can return, and the new field is missing from it.</comment>

<file context>
@@ -614,6 +616,9 @@ function optionalSnapshotResponseFields(
     ...(snapshotDiagnostics ? { snapshotDiagnostics } : {}),
+    // `readSerializedSnapshotCaptureAnnotations` above already reads this response's `warnings`, so
+    // only the typed field needs adding here.
+    ...(scriptDeliveryFailure === undefined ? {} : { scriptDeliveryFailure }),
     ...(typeof data.fallbackScreenshotPath === 'string'
       ? { fallbackScreenshotPath: data.fallbackScreenshotPath }
</file context>

const snapshotDiagnostics = readSnapshotDiagnosticsSummary(data.snapshotDiagnostics);
const presentedSurface = readPresentedSurfaceFact(data);
const postGestureOutcome = readPostGestureOutcome(data.postGestureOutcome);
const { scriptDeliveryFailure } = readScriptDeliveryDisclosure(data);

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 leveled snapshot branch returns the raw payload, so a malformed scriptDeliveryFailure reaches the caller unchecked. Pass that field through readScriptDeliveryFailure on the leveled path too, as presentedSurface already is.

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/client/src/index.ts, line 609:

<comment>The leveled snapshot branch returns the raw payload, so a malformed `scriptDeliveryFailure` reaches the caller unchecked. Pass that field through `readScriptDeliveryFailure` on the leveled path too, as `presentedSurface` already is.</comment>

<file context>
@@ -605,6 +606,7 @@ function optionalSnapshotResponseFields(
   const snapshotDiagnostics = readSnapshotDiagnosticsSummary(data.snapshotDiagnostics);
   const presentedSurface = readPresentedSurfaceFact(data);
   const postGestureOutcome = readPostGestureOutcome(data.postGestureOutcome);
+  const { scriptDeliveryFailure } = readScriptDeliveryDisclosure(data);
   return {
     ...(keyboard ? { keyboard } : {}),
</file context>

@thymikee

Copy link
Copy Markdown
Member Author

The earlier note on f09f36f found no problems. The code-scanning thread is now fixed, and one docs problem remains at 8f0ecc6.

The new sentence in remote-proxy.md says every result that records a version prints a Warning: line. That does not hold for a remote screenshot whose script download or save fails. session-script-destination.ts:118-119 adds the message and hint to warnings without a prefix. The dedicated screenshot handler at screenshot.ts:44-49 joins them as plain text, and the router returns after that handler, so the generic warning-line formatter never adds the prefix. A user or agent who looks for Warning: will miss a failed script delivery there. Please reword the sentence to say the CLI prints a warning, without promising a Warning: prefix on every surface.

The code-scanning thread no longer applies, because this PR does not change session-script-destination.ts and the helper at head is main's loop, not the flagged regex. Please resolve it: #4582 (comment)

There are no conflicts. Integration, unit and wire-compat checks pass on this head. The smoke tests and the review-bot checks are still running, and none has failed. Before merge, the docs sentence needs the fix above and those checks need to finish green.

…urface

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

5de4c76: remote-proxy.md now says the CLI prints a warning, without promising a Warning: prefix, since a remote screenshot prints the message and hint as plain text. Docs only.

@thymikee

Copy link
Copy Markdown
Member Author

The earlier finding from 8f0ecc6 (#4582 (comment)) is fixed, and there are no new problems in 5de4c76. The only change is one docs line in remote-proxy.md, which now describes the CLI warning accurately. CI is still running with no failures, and there are no conflicts.

Not blocking: four lower-priority review threads are still open and this docs change does not touch them: #4582 (comment), #4582 (comment), #4582 (comment) and #4582 (comment).

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 16, 2026
@thymikee
thymikee merged commit 244d1ff into main Nov 16, 2026
21 checks passed
@thymikee
thymikee deleted the feat/script-delivery-surfaces branch November 16, 2026 16:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants