feat(go): align CLI/SDK with TS guest auth and task start

Port lazy 401 login, guest task start, download-based results, and
non-retriable 4xx handling to Go. Tolerate empty JSON bodies from
PUT /start so guest convert no longer fails on 204 responses.

Author: zhaoxiongfei

apps/go-cli/main.go

@@ -566,14 +566,6 @@ func (c *appContext) apiBase() string {
 }
 
 func (c *appContext) getClient(ctx context.Context) (*deckops.Client, error) {
-	if c.config.Token == "" {
-		if _, err := c.ensureLoggedIn(ctx, defaultLoginPort, "explicit"); err != nil {
-			return nil, err
-		}
-	}
-	if c.config.Token == "" {
-		return nil, fmt.Errorf("Login did not provide a token. Please run `deckflow login` again.")
-	}
 	if c.client != nil {
 		return c.client, nil
 	}
@@ -582,7 +574,13 @@ func (c *appContext) getClient(ctx context.Context) (*deckops.Client, error) {
 		Token:   c.config.Token,
 		SpaceID: c.config.SpaceID,
 		OnUnauthorized: func(ctx context.Context) (deckops.AuthRefresh, error) {
-			token, err := c.ensureLoggedIn(ctx, defaultLoginPort, "unauthorized")
+			// First-time visit (no token yet) feels like an explicit login;
+			// an expired token reads as "auth expired".
+			reason := "unauthorized"
+			if c.config.Token == "" {
+				reason = "explicit"
+			}
+			token, err := c.ensureLoggedIn(ctx, defaultLoginPort, reason)
 			if err != nil {
 				return deckops.AuthRefresh{}, err
 			}
@@ -1045,6 +1043,10 @@ func (c *appContext) runTask(args []string) error {
 				return nil
 			}
 		}
+		task, err = c.attachDownloadResult(context.Background(), client, task)
+		if err != nil {
+			return err
+		}
 		c.output(task, func() string { return formatTaskDetails(task) })
 	case "delete":
 		if len(args) != 2 {
@@ -1428,6 +1430,17 @@ func (c *appContext) runFileTask(options fileTaskOptions) error {
 	if err != nil {
 		return err
 	}
+
+	// Guest mode (no token): the backend parks the task in a pending state
+	// and waits for an explicit start signal before executing.
+	// If Create triggered a 401 → login → retry, config.Token is now set
+	// and we skip the start call (authenticated tasks auto-start).
+	if c.config.Token == "" {
+		if _, err := client.Tasks.Start(context.Background(), task.ID); err != nil {
+			return err
+		}
+	}
+
 	c.info("Task created: " + task.ID)
 	if options.wait {
 		timeoutSec, err := positiveInt(options.timeout, "--timeout")
@@ -1458,14 +1471,12 @@ func (c *appContext) runFileTask(options fileTaskOptions) error {
 			return nil
 		}
 	}
-	if options.wait && task.Status == deckops.TaskStatusCompleted {
-		var downloadResult any
-		if err := client.Tasks.Down(context.Background(), task.ID, deckops.TaskDownloadOptions{}, &downloadResult); err != nil {
-			return err
-		}
-		printJSON(downloadResult)
-		return nil
+
+	task, err = c.attachDownloadResult(context.Background(), client, task)
+	if err != nil {
+		return err
 	}
+
 	c.output(task, func() string {
 		lines := []string{
 			options.title + ":",
@@ -1710,9 +1721,12 @@ func (c *appContext) tryWriteTaskOutput(ctx context.Context, client *deckops.Cli
 			return result, true
 		}
 		lastErr = err
-		if attempt < 3 {
+		// Only retry transient network/upstream failures — never 403/4xx business errors.
+		if attempt < 3 && deckops.IsRetriableError(err) {
 			time.Sleep(10 * time.Second)
+			continue
 		}
+		break
 	}
 	message := fmt.Sprintf("Task completed, but --out result could not be saved to %s after 3 attempts. The task result will be printed below; you can manually download the file from the target/result JSON.", outPath)
 	if c.json {
@@ -1725,6 +1739,20 @@ func (c *appContext) tryWriteTaskOutput(ctx context.Context, client *deckops.Cli
 	return outputWriteResult{}, false
 }
 
+// attachDownloadResult loads task result from GET /tools/tasks/:id/download.
+// Task detail/SSE only carries status/progress metadata now.
+func (c *appContext) attachDownloadResult(ctx context.Context, client *deckops.Client, task *deckops.Task) (*deckops.Task, error) {
+	if task.Status != deckops.TaskStatusCompleted {
+		return task, nil
+	}
+	var result any
+	if err := client.Tasks.Down(ctx, task.ID, deckops.TaskDownloadOptions{}, &result); err != nil {
+		return nil, err
+	}
+	task.Result = result
+	return task, nil
+}
+
 func (c *appContext) writeTaskOutput(ctx context.Context, client *deckops.Client, task *deckops.Task, outPath string) (outputWriteResult, error) {
 	var downloadResult any
 	if err := client.Tasks.Down(ctx, task.ID, deckops.TaskDownloadOptions{}, &downloadResult); err != nil {
@@ -1740,9 +1768,6 @@ func (c *appContext) writeTaskOutput(ctx context.Context, client *deckops.Client
 			return outputWriteResult{}, err
 		}
 		payload := downloadResult
-		if payload == nil {
-			payload = task.Result
-		}
 		if payload == nil {
 			payload = task
 		}

sdks/go/errors.go

@@ -43,6 +43,7 @@ func (e *APIError) Error() string {
 }
 
 func isRetriableStatus(status int) bool {
+	// Only transient upstream/gateway failures — never 4xx business errors (403, 404, …).
 	return status == StatusUpstreamUnavailable || status == http.StatusBadGateway
 }
 
@@ -57,6 +58,66 @@ func isRetriableTransportError(err error) bool {
 	return true
 }
 
+// IsRetriableError reports whether an error is worth retrying.
+//
+// Retries exist for transient network / upstream issues only.
+// Explicit application errors (403, 401, 404, 4xx in general) must fail immediately.
+func IsRetriableError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var apiErr *APIError
+	if errors.As(err, &apiErr) {
+		return isRetriableStatus(apiErr.StatusCode)
+	}
+
+	msg := err.Error()
+	if status, ok := parseHTTPStatusFromErrorMessage(msg); ok {
+		return isRetriableStatus(status)
+	}
+
+	lower := strings.ToLower(msg)
+	return strings.Contains(lower, "network") ||
+		strings.Contains(lower, "timeout") ||
+		strings.Contains(lower, "connection refused") ||
+		strings.Contains(lower, "connection reset") ||
+		strings.Contains(lower, "no such host") ||
+		strings.Contains(lower, "i/o timeout") ||
+		strings.Contains(lower, "temporary failure")
+}
+
+func parseHTTPStatusFromErrorMessage(message string) (int, bool) {
+	// Matches: "API Error (403): ..." or "Failed to download https://...: 403 Forbidden"
+	for _, prefix := range []string{"API Error (", "Failed to download "} {
+		idx := strings.Index(message, prefix)
+		if idx < 0 {
+			continue
+		}
+		rest := message[idx+len(prefix):]
+		if prefix == "Failed to download " {
+			colon := strings.LastIndex(rest, ": ")
+			if colon < 0 {
+				continue
+			}
+			rest = rest[colon+2:]
+		}
+		if len(rest) >= 3 {
+			status := 0
+			for i := 0; i < 3; i++ {
+				if rest[i] < '0' || rest[i] > '9' {
+					status = 0
+					break
+				}
+				status = status*10 + int(rest[i]-'0')
+			}
+			if status >= 100 && status <= 599 {
+				return status, true
+			}
+		}
+	}
+	return 0, false
+}
+
 func unauthorizedAPIKeyError(base *APIError) *APIError {
 	return &APIError{
 		StatusCode: http.StatusUnauthorized,

sdks/go/http_client.go

@@ -112,13 +112,8 @@ func (c *httpClient) ResolveSpaceID(ctx context.Context, spaceID string) (string
 	}
 	c.mu.RUnlock()
 
-	c.mu.RLock()
-	hasCredentials := c.token != "" || c.apiKey != ""
-	c.mu.RUnlock()
-	if !hasCredentials {
-		return "", fmt.Errorf("spaceId is required")
-	}
-
+	// Resolve from GET /user. The endpoint only requires X-Auth-UUID, so
+	// it works for both authenticated users and guests.
 	var user UserSelf
 	if _, err := c.getJSON(ctx, "/user", nil, nil, &user); err != nil {
 		return "", err
@@ -152,10 +147,8 @@ func (c *httpClient) getJSON(ctx context.Context, path string, query url.Values,
 	if err != nil {
 		return nil, err
 	}
-	if out != nil {
-		if err := json.Unmarshal(res.Body, out); err != nil {
-			return nil, err
-		}
+	if err := decodeJSONBody(res.Body, out); err != nil {
+		return nil, err
 	}
 	return res, nil
 }
@@ -173,14 +166,40 @@ func (c *httpClient) postJSON(ctx context.Context, path string, in any, out any)
 	if err != nil {
 		return nil, err
 	}
-	if out != nil {
-		if err := json.Unmarshal(res.Body, out); err != nil {
+	if err := decodeJSONBody(res.Body, out); err != nil {
+		return nil, err
+	}
+	return res, nil
+}
+
+func (c *httpClient) putJSON(ctx context.Context, path string, query url.Values, in any, out any) (*httpResponse, error) {
+	var body []byte
+	var err error
+	if in != nil {
+		body, err = json.Marshal(in)
+		if err != nil {
 			return nil, err
 		}
 	}
+	res, err := c.do(ctx, http.MethodPut, path, query, nil, body, false)
+	if err != nil {
+		return nil, err
+	}
+	if err := decodeJSONBody(res.Body, out); err != nil {
+		return nil, err
+	}
 	return res, nil
 }
 
+// decodeJSONBody unmarshals JSON into out. Empty bodies (common for 204 / start)
+// are treated as success and leave out unchanged.
+func decodeJSONBody(body []byte, out any) error {
+	if out == nil || len(bytes.TrimSpace(body)) == 0 {
+		return nil
+	}
+	return json.Unmarshal(body, out)
+}
+
 func (c *httpClient) delete(ctx context.Context, path string, query url.Values) error {
 	_, err := c.do(ctx, http.MethodDelete, path, query, nil, nil, false)
 	return err