fix(cli): creds-recovery verb, webhook URL print, env-token 401 advice, full token in list (#33)

Four agent-DX follow-ups found in a live cohort dogfood (round 2, building on #32):

F1 (P0): add `instant resource creds <token>` (alias `credentials`) — GETs
  /api/v1/resources/:id/credentials and prints the connection_url (webhook
  receive_url fallback; --json for the full response). Closes the broken
  first-provision recovery loop: `db new` frequently hits the 60s client
  timeout and the URL — printed only by `new` — was otherwise lost forever.
  Path fragment is the named const resourceCredsSuffix.

F2 (P1): `webhook new` printed a blank `url` line — the human path read
  creds.ConnectionURL only, but /webhook/new returns receive_url. Fall back
  to ReceiveURL like the local token-store code already does. (--json already
  emits receive_url via emitProvisionJSON; verified.)

F3 (P1): a 401 with INSTANT_TOKEN set advised `instant login`, which is
  useless — the env var SHADOWS any saved login. errSessionExpired() +
  classifyError() now branch on token SOURCE (new authFromEnvToken helper):
  an env-sourced reject tells the user to fix/unset INSTANT_TOKEN. This also
  fixes the dead session_expired JSON code (a 401 was mis-coded auth_required
  because errSessionExpired carries ExitAuthRequired).

F4 (P2): `instant resources` truncated the token (`d3cef90f-a75…`) — the
  exact value every other command needs as an argument, so it was
  un-copyable. Print the FULL token; truncate the NAME column instead
  (new truncateName + nameDisplayMaxLen). --json unchanged.

Tests: cmd/agent_dx_followups_test.go covers all four (creds happy/alias/json/
webhook-fallback/unauth/missing-token/empty/parse/server-error + token
fallback; webhook receive_url human+json; env-vs-saved 401 advice + json
action + flag-over-env; full-token + name-truncation + truncateName unit).
100%-patch on the diff; make ci green (build+vet+race+lint).

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: mastermanas805

cmd/agent_dx_followups_test.go

@@ -149,10 +149,10 @@ func TestClassifyError_GenericURLError(t *testing.T) {
 }
 
 func TestClassifyError_SessionExpired(t *testing.T) {
-	// errSessionExpired returns an *ExitCodeError with ExitAuthRequired,
-	// so classifyError catches it in the auth_required branch first. To
-	// reach the lowercase-contains("session expired") branch we need a
-	// plain error whose message contains the phrase.
+	// A plain (non-ExitCodeError) error carrying the phrase reaches the
+	// default-arm "session expired" classifier. (errSessionExpired's
+	// ExitCodeError variant is now handled inside the ExitAuthRequired arm
+	// after F3 — see TestClassifyError_AllBranches.)
 	err := errors.New("oops: session expired token")
 	c, _, _ := classifyError(err)
 	if c != "session_expired" {

cmd/coverage_push95_test.go

@@ -178,13 +178,14 @@ func TestClassifyError_AllBranches(t *testing.T) {
 	if c, _, _ := classifyError(errResourceFailed(errors.New("x"))); c != "resource_failed" {
 		t.Errorf("resource -> %q", c)
 	}
-	// errSessionExpired is an *ExitCodeError with Code==ExitAuthRequired, so it
-	// classifies as auth_required (the switch matches the code before the
-	// message phrase). The dedicated "session_expired" branch is only reached
-	// for a *plain* error whose message contains the phrase.
-	if c, _, _ := classifyError(errSessionExpired()); c != "auth_required" {
+	// errSessionExpired is an *ExitCodeError with Code==ExitAuthRequired, but
+	// F3 now distinguishes a rejected-token "session expired" from a genuine
+	// "never authenticated" inside the ExitAuthRequired arm — so it classifies
+	// as session_expired (accurate code) rather than the old auth_required wart.
+	if c, _, _ := classifyError(errSessionExpired()); c != "session_expired" {
 		t.Errorf("session-as-exitcode -> %q", c)
 	}
+	// A plain error carrying the phrase still reaches the default-arm branch.
 	if c, _, _ := classifyError(errors.New("the session expired, sorry")); c != "session_expired" {
 		t.Errorf("session phrase -> %q", c)
 	}

cmd/coverage_units_test.go

@@ -172,19 +172,17 @@ func runResources(cmd *cobra.Command) error {
 		return nil
 	}
 
+	// F4: print the FULL token — it is the exact argument every other command
+	// (`instant resource <token>`, `… creds`, `… delete`, …) needs, so a
+	// truncated `d3cef90f-a75…` made the default list view un-copyable. The
+	// NAME column is truncated instead when it's long, since a name is
+	// human-facing and rarely the value being copied verbatim.
 	w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
 	_, _ = fmt.Fprintln(w, "TOKEN\tTYPE\tNAME\tTIER\tSTATUS")
 	for _, r := range result.Items {
-		shortToken := r.Token
-		if len(shortToken) > 12 {
-			shortToken = shortToken[:12] + "…"
-		}
-		name := r.Name
-		if name == "" {
-			name = "-"
-		}
+		name := truncateName(r.Name)
 		_, _ = fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n",
-			shortToken, r.ResourceType, name, r.Tier, r.Status)
+			r.Token, r.ResourceType, name, r.Tier, r.Status)
 	}
 	_ = w.Flush()
 	return nil
@@ -247,6 +245,27 @@ func matchResourceFilters(filters map[string]string, rType, env, status, tier, n
 	return true
 }
 
+// nameDisplayMaxLen caps the NAME column in the `instant resources` table.
+// F4: the token now prints in full (it is the copy-paste argument every other
+// command needs); the human-facing NAME is the column we truncate when width
+// is tight. A trailing ellipsis signals truncation. "" renders as "-".
+const nameDisplayMaxLen = 24
+
+// truncateName renders a resource name for the table: "-" when empty, the
+// name unchanged when within nameDisplayMaxLen, else a one-ellipsis truncation.
+func truncateName(name string) string {
+	if name == "" {
+		return "-"
+	}
+	// Count runes (not bytes) so a multibyte name truncates on a character
+	// boundary and the column width math stays correct.
+	runes := []rune(name)
+	if len(runes) <= nameDisplayMaxLen {
+		return name
+	}
+	return string(runes[:nameDisplayMaxLen]) + "…"
+}
+
 // lower / eqFold — tiny strings helpers kept local so this file does not
 // re-import strings (the runResources path already does, but the filter
 // helpers stay testable in isolation).

cmd/discover.go

@@ -99,12 +99,26 @@ func errAuthRequired(detail string) error {
 // a bearer token. Tests assert on this exact wording so the contract is
 // stable for downstream agents.
 //
+// F3: the advice branches on token SOURCE. When the active token came from
+// INSTANT_TOKEN (env), `instant login` is useless guidance — the env var
+// SHADOWS any saved login, so re-logging-in changes nothing until
+// INSTANT_TOKEN is fixed or unset. In that case we tell the user to fix/unset
+// the env var instead. A flag/saved-login token keeps the original `instant
+// login` guidance.
+//
 // IMPORTANT: keep the literal phrase "session expired" in the message — the
-// hermetic suite (and the project's "shipped ≠ verified" rules) grep for it.
+// hermetic suite, json_error.go's session_expired classifier, and the
+// project's "shipped ≠ verified" rules all grep for it. Both branches retain
+// it; only the trailing actionable clause differs.
 func errSessionExpired() error {
+	msg := "session expired — run `instant login` to re-authenticate"
+	if authFromEnvToken() {
+		msg = "session expired — INSTANT_TOKEN is set but the server rejected it; " +
+			"fix or unset INSTANT_TOKEN (it shadows any saved `instant login`)"
+	}
 	return &ExitCodeError{
 		Code: ExitSessionExpired,
-		Err:  errors.New("session expired — run `instant login` to re-authenticate"),
+		Err:  errors.New(msg),
 	}
 }
 

cmd/errors.go

@@ -71,6 +71,10 @@ var resourceCmd = &cobra.Command{
 	Long: `Show, delete, or operate on a single resource by token.
 
   instant resource <token>             Print the resource's metadata + connection URL
+  instant resource creds <token>       Re-fetch the connection URL alone
+                                       (alias: credentials; GET …/credentials).
+                                       Recovers the URL after a provision that
+                                       timed out client-side before printing it.
   instant resource delete <token>      Tear down the resource. Requires --yes
                                        (or an interactive 'y' confirmation) to
                                        actually delete — printing nothing
@@ -96,6 +100,16 @@ listed in 'instant resources'.`,
 				return wrapJSONErr(cmd, fmt.Errorf("instant resource delete: token argument is required"))
 			}
 			return wrapJSONErr(cmd, runResourceDelete(cmd, args[1]))
+		case "creds", "credentials":
+			// F1 — re-fetch a resource's connection URL (GET …/credentials).
+			// Closes the broken first-provision recovery loop: `db new`
+			// frequently hits the 60s client timeout and the connection URL
+			// is otherwise lost forever (it's only printed by `new`). Handler
+			// lives in operate.go alongside the other GET-by-token verbs.
+			if len(args) < 2 {
+				return wrapJSONErr(cmd, fmt.Errorf("instant resource %s: token argument is required", verb))
+			}
+			return wrapJSONErr(cmd, runResourceCredentials(args[1]))
 		case "pause", "resume", "rotate", "backup", "backups":
 			// Wave-2 A4 operate verbs — handlers live in operate.go.
 			if len(args) < 2 {

cmd/extras.go

@@ -98,6 +98,14 @@ func classifyError(err error) (code, message, agentAction string) {
 	if errors.As(err, &ec) {
 		switch ec.Code {
 		case ExitAuthRequired:
+			// F3: errSessionExpired() carries ExitSessionExpired (== ExitAuthRequired),
+			// so a 401 lands here. Distinguish a rejected-token "session expired" from
+			// a genuine "never authenticated" so the code + agent_action are accurate,
+			// and branch the advice on token SOURCE (an INSTANT_TOKEN-sourced reject is
+			// not fixed by `instant login` — the env var shadows it).
+			if strings.Contains(strings.ToLower(msg), "session expired") {
+				return "session_expired", msg, sessionExpiredAction()
+			}
 			return "auth_required", msg,
 				"run `instant login`, or set INSTANT_TOKEN to a Personal Access Token"
 		case ExitResourceFailed:
@@ -131,13 +139,26 @@ func classifyError(err error) (code, message, agentAction string) {
 	}
 
 	// Default: surface the raw message; agents read .error code regardless.
+	// (Reached for the plain-error errSessionExpiredSentinel path — the
+	// ExitCodeError variant is handled in the switch above.)
 	if strings.Contains(strings.ToLower(msg), "session expired") {
-		return "session_expired", msg,
-			"run `instant login` to re-authenticate"
+		return "session_expired", msg, sessionExpiredAction()
 	}
 	return "cli_error", msg, ""
 }
 
+// sessionExpiredAction returns the agent_action for a rejected-token (401)
+// error, branched on token SOURCE (F3). An INSTANT_TOKEN-sourced reject is not
+// fixed by `instant login` — the env var shadows any saved login — so advise
+// fixing/unsetting it instead. Mirrors errSessionExpired()'s human-message
+// branch so the JSON envelope and the text path stay consistent.
+func sessionExpiredAction() string {
+	if authFromEnvToken() {
+		return "fix or unset INSTANT_TOKEN — it shadows any saved `instant login`"
+	}
+	return "run `instant login` to re-authenticate"
+}
+
 // wrapJSONErr emits a JSON error envelope on stdout when --json is on, and
 // returns the same error to the caller so cobra's exit-code path still fires
 // (with usage printing silenced). When --json is OFF, returns err unchanged

cmd/json_error.go

@@ -216,7 +216,16 @@ func makeProvisionCmd(endpoint, resourceType string) func(*cobra.Command, []stri
 		}
 
 		fmt.Printf("ok    %-8s  %s\n", resourceType, creds.Token)
-		fmt.Printf("url   %s\n", creds.ConnectionURL)
+		// F2: /webhook/new returns receive_url (NOT connection_url), so a
+		// bare creds.ConnectionURL printed `url   ` (blank). Fall back to
+		// ReceiveURL like the local token-store code above already does, so
+		// webhook provisions show their real receiver URL. (--json already
+		// emits both fields via emitProvisionJSON.)
+		provisionURL := creds.ConnectionURL
+		if provisionURL == "" {
+			provisionURL = creds.ReceiveURL
+		}
+		fmt.Printf("url   %s\n", provisionURL)
 		if creds.Tier != "" {
 			fmt.Printf("tier  %s\n", creds.Tier)
 		}

cmd/monitor.go

@@ -67,6 +67,7 @@ const (
 	resourceRotateSuffix = "/rotate-credentials"  // POST rotate password
 	resourceBackupSuffix = "/backup"              // POST ad-hoc backup (tier-gated)
 	resourceBackupsList  = "/backups"             // GET list backups
+	resourceCredsSuffix  = "/credentials"         // GET re-fetch connection URL (no rotation)
 )
 
 // operateJSON is the shared --json toggle for every operate-verb command.
@@ -587,6 +588,68 @@ func runResourceOperate(verb, token string) error {
 	return nil
 }
 
+// ── resource creds (re-fetch the connection URL) ─────────────────────────────
+
+// resourceCredentialsResult mirrors GET /api/v1/resources/:id/credentials
+// (api/internal/handlers/resource.go GetCredentials). The real endpoint
+// returns connection_url plus the resource identity; ReceiveURL is decoded
+// too so a webhook-shaped response (receiver URL) still renders.
+type resourceCredentialsResult struct {
+	OK            bool   `json:"ok"`
+	ID            string `json:"id"`
+	Token         string `json:"token"`
+	ResourceType  string `json:"resource_type"`
+	Env           string `json:"env"`
+	ConnectionURL string `json:"connection_url"`
+	ReceiveURL    string `json:"receive_url"`
+}
+
+// runResourceCredentials re-fetches a resource's connection URL by token —
+// the recovery path for a provision whose `new` call hit the 60s client
+// timeout before printing the URL (the URL is otherwise unrecoverable). GETs
+// /api/v1/resources/:token/credentials and prints the connection_url (or the
+// webhook receive_url fallback); --json emits the full structured response.
+func runResourceCredentials(token string) error {
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return fmt.Errorf("token is required")
+	}
+	url := fmt.Sprintf("%s%s/%s%s", APIBaseURL, resourcesBasePath,
+		neturl.PathEscape(token), resourceCredsSuffix)
+	raw, err := doOperate(http.MethodGet, url, nil, true)
+	if err != nil {
+		return err
+	}
+	var res resourceCredentialsResult
+	if err := json.Unmarshal(raw, &res); err != nil {
+		return fmt.Errorf("parsing response: %w", err)
+	}
+	if resourceDetailJSON || operateJSON {
+		return emitJSON(res)
+	}
+	// Webhooks have no connection_url — fall back to receive_url so the
+	// receiver URL still surfaces (mirrors the provision + detail paths).
+	connURL := res.ConnectionURL
+	if connURL == "" {
+		connURL = res.ReceiveURL
+	}
+	tok := res.Token
+	if tok == "" {
+		tok = token
+	}
+	fmt.Printf("ok    creds  %s\n", tok)
+	if connURL != "" {
+		fmt.Printf("url   %s\n", connURL)
+	}
+	if res.ResourceType != "" {
+		fmt.Printf("type  %s\n", res.ResourceType)
+	}
+	if res.Env != "" {
+		fmt.Printf("env   %s\n", res.Env)
+	}
+	return nil
+}
+
 // backupRow is one row from GET /api/v1/resources/:token/backups.
 type backupRow struct {
 	BackupID     string `json:"backup_id"`

cmd/operate.go

@@ -115,6 +115,7 @@ Examples:
   instant vector new --name app-vec   Provision a Postgres+pgvector resource
   instant resources                   List your provisioned resources (requires login)
   instant resource <token>            Show detail for a single resource by token
+  instant resource creds <token>      Re-fetch a resource's connection URL by token
   instant resource delete <token>     Delete a resource (use --yes to skip confirm)
   instant resource pause <token>      Suspend a resource without deleting it (Pro+)
   instant resource resume <token>     Un-pause a suspended resource (Pro+)