Fix SAM CLI contract drift

[simple-agent-manager]

Summary

• Aligns SAM CLI command response structs and renderers with current API contracts for status, chat, library, context, notifications, triggers, profiles, activity, and nodes.
• Fixes sam chat <sessionId> to use the session detail route, adds explicit library root-only/recursive behavior, sanitizes table cells, and improves invalid JSON errors with safe route/status/decode context.
• Updates CLI help text for sam library --recursive.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test
• pnpm build
• go test ./... in packages/cli
• go test -race -coverprofile=coverage.out -covermode=atomic ./... in packages/cli
• go tool cover -func=coverage.out inspected: total 80.9%, internal/cli 81.1%

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging workflow run 26765014939 passed for this branch at commit fadbad32
• Live app verified via Playwright — N/A: CLI-only package change; no app UI surface changed
• Existing workflows confirmed working — staging smoke tests passed in run 26765014939
• New feature/fix verified on staging — staging built and uploaded CLI binaries successfully; behavior covered by CLI command-boundary tests against current API shapes
• Infrastructure verification completed — N/A: no infrastructure paths changed
• Mobile and desktop verification notes added for UI changes — N/A: no UI changes

Staging Verification Evidence

Deploy Staging run 26765014939 completed successfully for sam/title-fix-sam-cli-01kt1v. The run included successful Build CLI, Upload CLI Binaries, Health Check, and smoke-test jobs.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified — N/A: no UI changes
• Accessibility checks completed — N/A: no UI changes
• Shared UI components used or exception documented — N/A: no UI changes
• Playwright visual audit run locally — N/A: no UI changes

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code

Data Flow Trace

• CLI entry routing: packages/cli/internal/cli/run.go
• Command behavior and text rendering: packages/cli/internal/cli/commands.go
• API calls and safe decode errors: packages/cli/internal/cli/client.go
• Current response contracts: packages/cli/internal/cli/types.go
• Table sanitization and timestamp formatting: packages/cli/internal/cli/table.go
• Command-boundary tests: packages/cli/internal/cli/commands_test.go, client_test.go, run_test.go, table_test.go

Untested Gaps

No live authenticated CLI smoke was run against staging because the staging workflow does not expose an authenticated CLI session for this task. Changed behavior is covered by command-boundary tests using current API response shapes and by staging CLI binary build/upload.

Post-Mortem (Required for bug fix PRs)

What broke

The CLI had drifted from current API response shapes, causing several commands to fail with INVALID_JSON or produce incomplete/misleading table output.

Root cause

CLI response structs and command renderers remained coupled to older API shapes while the API routes and shared types evolved.

Class of bug

Client/server contract drift with insufficient command-boundary coverage for current response shapes.

Why it wasn't caught

Existing CLI tests covered many command boundaries but used stale fake response shapes for several commands.

Process fix included in this PR

Added/updated CLI command-boundary tests for the affected text and JSON outputs, plus decode redaction and table-rendering tests.

Specialist Review Evidence (Required for agent-authored PRs)

• All dispatched reviewers completed and findings addressed before merge

Reviewer	Status	Outcome
go-specialist	PASS	No blocking Go CLI issues found
test-engineer	PASS	CLI command-boundary, JSON, table, and race/coverage checks passed
security-auditor	PASS	Invalid JSON context redacts cookies/tokens; no credential leakage found
task-completion-validator	PASS	Task findings, checklist, and acceptance criteria map to diff and tests

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: Internal contract alignment between CLI and API. Current contracts verified against local API routes and shared type definitions in packages/shared/.

Codebase Impact Analysis

Affected components: packages/cli/internal/cli (commands, client, types, table, run). No API, web UI, or infrastructure runtime code changed. CLI binary build verified on staging.

Documentation & Specs

CLI help text updated for sam library --recursive. No other documentation changes needed as the CLI docs were consolidated into the public docs site.

Constitution & Risk Check

Checked Principle XI: no new hardcoded URLs, secrets, timeouts, or environment identifiers introduced. Error output redaction verified to not expose credentials.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[simple-agent-manager]

Review Fixes Applied

Addressed findings from go-specialist code review:

[HIGH] Test assertion bug fixed — TestStatusJSONOutputUsesCurrentContracts was asserting that value["sessions"] is a map[string]any (always true for the wrapped SessionListResponse), but didn't verify the inner sessions array was non-empty. Fixed to use assertArrayField on the nested sessions object, matching the pattern used by all other JSON contract tests.

[MEDIUM] Query param construction — ListLibraryFiles used raw string concatenation (path += "?recursive=true"). Changed to idiomatic url.Values.Encode() to prevent the pattern from spreading to user-controlled inputs.

[MEDIUM] Dead code removed — FormatAnyTimestamp had int, int64, and json.Number type switch branches that are unreachable via standard encoding/json unmarshalling into any (which always produces float64). Removed with a clarifying comment.

Commit: be10f66a