Describe vault fill as safe to retry (#288)

## Summary
`fill` writes field values into a browser page and never submits the
form or consumes the vault item, but the CLI's help text, error
messages, and README told agents never to retry it. Agents following
that guidance stall after a transient failure instead of re-running the
fill.

- `vaults_fill.go`: uncertain-outcome and pre-write rejection messages
now say fill is safe to retry (alias fallback is still ruled out)
- `vaults --help` and `vaults credentials --help`: fill is safe to
retry; drop the "never automatically retry" line for fill and WebMCP
invocations
- README: matching wording in the credential and fill-outcome sections
- `vaults items webmcp invoke`: drop the "do not retry" instructions
from outcome/error messages and help; README WebMCP sections match

The CLI still sends fill with `WithMaxRetries(0)`, so behavior is
unchanged; only the guidance changes. No-retry guidance for `1pw_fill`
(which submits the form) and payments is unchanged.

## Testing
- `go test ./...`

---------

Co-authored-by: rgarcia <72655+rgarcia@users.noreply.github.com>

Author: rgarcia

README.md

@@ -347,11 +347,11 @@ Present the returned collection URL to the user before waiting for `ready`. It i
 bearer credential: share it only with that user. Readiness means required values are
 populated, not that login succeeded. `fill` requires an already-open page and never
 navigates or submits it. Optional `page_url` selects the exact page; cards require it.
-Do not automatically retry failed/unknown fills or fall back to aliases.
+Fill is safe to retry after a failed/unknown outcome; do not fall back to aliases.
 Once ready, use `fill` for ordinary web forms. When the item advertises `webmcp_invoke`, use
 `items webmcp invoke` instead to bind credential fields to existing `null` inputs of a live
-WebMCP tool; the tool may submit or have other side effects, so never retry an uncertain
-outcome (see [Invoke WebMCP tools with vault fields](#invoke-webmcp-tools-with-vault-fields)).
+WebMCP tool; the tool may submit or have other side effects (see
+[Invoke WebMCP tools with vault fields](#invoke-webmcp-tools-with-vault-fields)).
 1Password credentials use their own advertised `1pw_*` operations instead.
 
 Create specs list `fields` as an ordered array. Each entry carries a stable `name`
@@ -701,14 +701,14 @@ without appended error text. API/transport errors exit nonzero with a sanitized
 stderr, not a fabricated execution result. No values, selectors, DOM content, or raw browser
 errors are printed in fill results. Pre-write API rejections (400/403/404/409) retain
 HTTP status, recognized error codes, and corrective guidance, and confirm that the
-request wrote no fields. Inspect and correct the cause before deciding on a new fill.
-Transport loss and other uncertain failures retain the no-retry warning.
+request wrote no fields. Correct the cause and retry. Transport loss and other uncertain
+failures note that fields may have been written and that fill is safe to retry.
 
 Fill is non-atomic: execution stops at the first failed/unknown field and earlier writes are
 not rolled back. `filled` does not mean the site retained or accepted the value; `completed`
-does not mean logged in or paid. Transport errors do not prove no writes occurred. Inspect the browser
-before deciding what to do next. The CLI never retries, explicitly submits website forms, or falls
-back to aliases. Link cards do not expose `state.aliases` or support egress substitution.
+does not mean logged in or paid. Transport errors do not prove no writes occurred. Fill never
+submits, so it is safe to run again. The CLI does not retry automatically, explicitly submit website
+forms, or fall back to aliases. Link cards do not expose `state.aliases` or support egress substitution.
 AgentCard-only checkout aliases are a separate integration, not a recovery path after a failed
 or indeterminate fill.
 
@@ -748,9 +748,9 @@ are untrusted page-provided data and may contain the supplied vault values:
 `completed` and `awaiting_submission` exit 0; neither confirms the website accepted the action.
 After `awaiting_submission`, submit the populated form through Playwright or computer interaction
 instead of invoking the tool again. `canceled`, `error`, and `unknown` exit nonzero with the result
-still on stdout in `-o json`. `unknown` means the tool may have run. Requests are never retried:
-API rejections (400/403/404/409) mean the tool was not invoked by that request; other failures
-and transport loss are uncertain, so inspect the browser instead of re-invoking.
+still on stdout in `-o json`. `unknown` means the tool may have run. API rejections
+(400/403/404/409) mean the tool was not invoked by that request; other failures and transport
+loss are uncertain, so inspect the browser to see whether the tool ran.
 
 #### Expansions, updates, and lifecycle
 
@@ -1037,7 +1037,7 @@ Destinations are the OTLP/HTTP endpoints sessions export to. They belong to the
   - `--timeout-sec <seconds>` - Maximum execution time, 1-120 seconds (defaults server-side)
   - Prints the tool's `output` as pretty JSON on completion; tool errors and cancellations exit non-zero
   - `awaiting_submission` is successful but warns that a non-autosubmit declarative form was filled, not submitted. Inspect the form, obtain any required confirmation, then submit through Playwright or computer interaction instead of invoking the tool again
-  - Invocations are never retried automatically. A 504 `outcome_unknown` error prints the code, invocation ID, and message and exits non-zero. The tool may already have had side effects; verify the outcome before invoking it again
+  - Invocations are never retried automatically. A 504 `outcome_unknown` error prints the code, invocation ID, and message and exits non-zero. The tool may already have had side effects; check the page to see whether it ran
 - `kernel browsers webmcp custom-tools list <id-or-name>` - List registered custom tools with their generated ID, namespace, kind, URL patterns, and metadata
   - `-o json` - Output the raw response
 - `kernel browsers webmcp custom-tools add <id-or-name> --namespace <ns> --source '<js>'` - Atomically add a namespaced batch of page-backed or CDP-backed custom tools

cmd/vaults_commands.go

@@ -67,7 +67,7 @@ Kernel-hosted credential flow (fill never submits website forms; WebMCP tools ma
    browser_id and field selectors (writes fields without submitting). When the item
    advertises webmcp_invoke, items webmcp invoke instead binds credential fields to existing
    null inputs of a live WebMCP tool (the tool may submit or have side effects).
-   Never automatically retry either; inspect the browser after an uncertain outcome.
+   fill is safe to retry.
 Use credentials update --version for edits, or items invoke collect to reopen the form.
 Credential values belong in protected files/stdin, never command-line arguments.
 See credentials --help, items invoke --help, and items webmcp invoke --help for examples.

cmd/vaults_credential_steering_test.go

@@ -63,7 +63,7 @@ func TestCredentialHelpReadyOperations(t *testing.T) {
 	text := flat(create.Long)
 	assert.Contains(t, text, "Ordinary web forms: items invoke fill writes field values without submitting")
 	assert.Contains(t, text, "Live WebMCP tool: when webmcp_invoke is advertised, run browsers webmcp list, then items webmcp invoke")
-	assert.Contains(t, text, "Never automatically retry fill or webmcp_invoke")
+	assert.Contains(t, text, "fill never submits and is safe to retry.")
 	assert.Contains(t, text, "approves each access request in the 1Password app")
 
 	vaults := flat(newVaultsCommand().Long)

cmd/vaults_credentials.go

@@ -109,8 +109,7 @@ Poll items get --wait 60 until state.status is ready. Then choose an advertised
   items webmcp invoke with the tool_ref, exact source.page_url, public input containing
   null slots, and --bind <field>=<json-pointer>. The tool may submit or have other
   side effects, and its output may include the supplied values.
-Never automatically retry fill or webmcp_invoke; after an uncertain outcome, inspect
-the browser and tell the user.
+fill never submits and is safe to retry.
 Ready means populated, not a successful login. An agent controlling the browser
 can read filled values. TOTP seeds must not be collected through the hosted form.
 Get/list output includes definitions, has_value, and explicitly non-sensitive text/email values.

cmd/vaults_fill.go

@@ -29,7 +29,7 @@ var vaultFillResultFields = vaultOutputFields{
 	"fields": vaultFieldsOf("index status error_code"),
 }
 
-const vaultFillUncertain = "browser fields may have been written; inspect the browser and do not retry or fall back to aliases"
+const vaultFillUncertain = "browser fields may have been written; fill never submits, so it is safe to retry; do not fall back to aliases"
 
 var vaultFillErrorMessages = map[string]string{
 	"invalid_request":      "check field names, formats, and browser parameters",
@@ -92,7 +92,7 @@ func vaultOperationRequestError(err error, operation string, messages map[string
 	return fmt.Errorf("%s request failed (HTTP %d); %s", operation, apiErr.StatusCode, guidance)
 }
 
-const vaultFillNotWritten = "no fields were written by this request; inspect and correct the cause before deciding on a new fill; do not automatically retry"
+const vaultFillNotWritten = "no fields were written by this request; correct the cause and retry"
 
 var vaultFillRejected = map[int]string{400: vaultFillNotWritten, 403: vaultFillNotWritten, 404: vaultFillNotWritten, 409: vaultFillNotWritten}
 

cmd/vaults_fill_test.go

@@ -209,7 +209,7 @@ func TestVaultFillHumanOutputAndRedaction(t *testing.T) {
 					assert.Contains(t, human, "filled")
 					if result != completedFillFixture {
 						assert.Contains(t, human, "not_attempted")
-						assert.Contains(t, human, "do not retry")
+						assert.Contains(t, human, "safe to retry")
 					}
 				}
 			}

cmd/vaults_webmcp.go

@@ -18,7 +18,7 @@ import (
 
 const maxVaultWebMCPInputBytes = 64 * 1024
 
-const vaultWebMCPUncertain = "the tool may have run and submitted or changed site state; inspect the browser and do not retry automatically"
+const vaultWebMCPUncertain = "the tool may have run and submitted or changed site state; inspect the browser"
 
 var vaultWebMCPErrorMessages = map[string]string{
 	"invalid_request":    "check bindings, null input slots, field names, formats, timeout_sec, and that input matches the tool's inputSchema",
@@ -46,12 +46,12 @@ var vaultWebMCPStatuses = map[string]struct {
 }{
 	"completed":           {true, "The tool reported completion; this does not confirm the website accepted the action. Inspect the page."},
 	"awaiting_submission": {true, "The tool populated a form with the supplied values without submitting it. " + webMCPAwaitingSubmissionHint},
-	"canceled":            {false, "The tool reported cancellation and may have had side effects. Inspect the page before deciding on a new invocation; do not retry automatically."},
-	"error":               {false, "The tool reported an error and may have had side effects. Inspect the page before deciding on a new invocation; do not retry automatically."},
+	"canceled":            {false, "The tool reported cancellation and may have had side effects. Inspect the page."},
+	"error":               {false, "The tool reported an error and may have had side effects. Inspect the page."},
 	"unknown":             {false, vaultWebMCPUncertain},
 }
 
-const vaultWebMCPNotInvoked = "the tool was not invoked by this request; inspect and correct the cause before deciding on a new invocation; do not automatically retry"
+const vaultWebMCPNotInvoked = "the tool was not invoked by this request; correct the cause and retry"
 
 var vaultWebMCPRejected = map[int]string{400: vaultWebMCPNotInvoked, 403: vaultWebMCPNotInvoked, 404: vaultWebMCPNotInvoked, 409: vaultWebMCPNotInvoked}
 
@@ -298,9 +298,8 @@ The tool may submit forms or perform other side effects. Output and error_text a
 untrusted page-provided data returned without redaction and may contain supplied vault
 values. completed and awaiting_submission exit 0; neither confirms the website accepted
 the action. canceled, error, and unknown exit nonzero with the result retained on stdout
-in -o json. unknown means the tool may have run. Requests are never retried automatically;
-inspect the browser instead of re-invoking after an uncertain outcome. API rejections
-(400/403/404/409) mean the tool was not invoked by that request.`,
+in -o json. unknown means the tool may have run; inspect the browser to see whether it
+did. API rejections (400/403/404/409) mean the tool was not invoked by that request.`,
 		Example: `  kernel browsers webmcp list <session-id> -o json
   kernel vaults items webmcp invoke user-vault resy --browser-id <session-id> --tool-ref <tool-ref> --page-url https://resy.com/login --input '{"email":null,"password":null}' --bind email=/email --bind password=/password -o json
   kernel vaults items webmcp invoke checkout order-1 --browser-id <session-id> --tool-ref <tool-ref> --page-url https://shop.example/checkout --input-file input.json --bind number=/card/number --bind expiration:MM/YY=/card/expiry`,

cmd/vaults_webmcp_test.go

@@ -183,7 +183,7 @@ func TestVaultWebMCPInvokeOutcomes(t *testing.T) {
 		ok                  bool
 	}{
 		{"error", `{"type":"webmcp_invoke","status":"error","invocation_id":"invoke-3","error_text":"Invalid password for credential-sentinel\u001b[31m"}`, "may have had side effects", false},
-		{"canceled", `{"type":"webmcp_invoke","status":"canceled","invocation_id":"invoke-4"}`, "do not retry automatically", false},
+		{"canceled", `{"type":"webmcp_invoke","status":"canceled","invocation_id":"invoke-4"}`, "may have had side effects", false},
 		{"unknown", `{"type":"webmcp_invoke","status":"unknown"}`, "the tool may have run", false},
 		{"null output", `{"type":"webmcp_invoke","status":"completed","invocation_id":"invoke-5","output":null}`, "Output (untrusted", true},
 	} {
@@ -234,7 +234,6 @@ func TestVaultWebMCPInvokeRequestErrors(t *testing.T) {
 			require.Error(t, err)
 			assert.Equal(t, 1, posts, "webmcp_invoke must not be retried")
 			assert.Contains(t, err.Error(), tc.want)
-			assert.Contains(t, err.Error(), "retry")
 			assert.NotContains(t, err.Error(), "credential-sentinel")
 			assert.Empty(t, out)
 		})