Summary

• Problem: GET /api/workflows/:name returns 404 for any workflow at ~/.archon/workflows/. The Web UI then renders an empty workflow object, surfacing misleading Zod errors ("workflow name is required", "workflow description is required", "at least one node is required") even though the same workflow loads and runs correctly via the CLI.
• Why it matters: Home-scoped workflows are the documented user-level storage path (per CLAUDE.md "Home-scoped workflows"). They appear in archon workflow list with source: 'global', validate cleanly, and execute end-to-end — but cannot be opened in the workflow builder UI.
• What changed: Added a home-scoped lookup tier to the GET route between the existing project-scoped and bundled-defaults tiers. Mirrors the PUT route, which already defaults saves to getArchonHome() when no cwd matches.
• What did NOT change: The route's project > global > bundled priority (matches discoverWorkflows() in packages/workflows/src/workflow-discovery.ts). No subfolder lookup added — that would be a separate change touching PUT too.

UX Journey

Before

User opens workflow builder ──▶ UI calls GET /api/workflows/<name>
                                 │
                                 └─▶ Server checks cwd/.archon/workflows/  ❌
                                     Server checks bundled defaults        ❌
                                     (skips ~/.archon/workflows/)
                                 │
                                 ◀── 404
UI renders empty {} ──────────▶ Zod errors:
                                 "workflow name is required"
                                 "workflow description is required"
                                 "at least one node is required"

After

User opens workflow builder ──▶ UI calls GET /api/workflows/<name>
                                 │
                                 └─▶ Server checks cwd/.archon/workflows/  ❌
                                     [+ Server checks ~/.archon/workflows/ ✅]
                                 │
                                 ◀── 200 { workflow, source: 'global' }
UI renders editor ────────────▶ Workflow loads correctly

Architecture Diagram

Before

GET /api/workflows/:name   ───┐
                              ├─▶ project (cwd/.archon/workflows/)
                              └─▶ bundled (BUNDLED_WORKFLOWS map / dev fs)

PUT /api/workflows/:name   ───┐
                              ├─▶ project (if cwd)
                              ├─▶ codebase[0].default_cwd
                              └─▶ getArchonHome() ✅
(asymmetric — GET missing the home-scoped tier)

After

GET /api/workflows/:name   ───┐
                              ├─▶ project (cwd/.archon/workflows/)
                              ├─▶ [+] global (getHomeWorkflowsPath())
                              └─▶ bundled

PUT /api/workflows/:name   (unchanged)
(symmetric — both routes now reach home-scoped storage)

Connection inventory:

Label Snapshot

• Risk: risk: low
• Size: size: XS
• Scope: server
• Module: server:routes-api-workflows

Change Metadata

• Change type: bug
• Primary scope: server

Linked Issue

• Closes #
• Related #
• Depends on #
• Supersedes #

(No issue filed — discovered during dogfooding by a user authoring a home-scoped workflow per the documented ~/.archon/workflows/ flow.)

Validation Evidence (required)

bun run type-check    # all 10 packages exit 0
bun run lint          # clean
bun run format:check  # clean
bun --filter '@archon/server' test  # 4 files / 118 tests pass, 0 fail

Full bun run validate was run; 4 pre-existing failures in @archon/workflows (DAG Loader -- cycle detection > accepts valid DAG … ×3 and one script-node test) are present on origin/dev without this patch and are unrelated to this change (verified by stashing the patch and re-running). This PR touches only packages/server/src/routes/api.ts.

Manual verification:

$ curl -s http://localhost:3090/api/workflows/<home-scoped-workflow-name>
{ "workflow": {...full definition...}, "filename": "...", "source": "global" }
HTTP 200  (was 404 before)

Web UI workflow builder now opens the workflow without Zod errors.

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No — only reads from getHomeWorkflowsPath() which is already read by discoverWorkflows(). Filename is derived from a route param that already passes isValidCommandName(), so no new path-traversal surface is introduced.

Compatibility / Migration

• Backward compatible? Yes — strictly additive. Existing project and bundled lookups are untouched. Routes that previously returned 404 for home-scoped names now succeed; nothing that previously succeeded changes.
• Config/env changes? No
• Database migration needed? No

Human Verification (required)

What was personally validated beyond CI:

• Verified scenarios:
  • Home-scoped workflow → GET returns 200 with source: 'global'
  • Project-scoped workflow → still returns 200 with source: 'project'
  • Bundled workflow → still returns 200 with source: 'bundled'
  • Nonexistent name → still returns 404
• Edge cases checked: ENOENT on home dir is swallowed and falls through to bundled (matches existing project-tier behavior); other read errors log and 500 (also matches existing project-tier behavior).
• What was not verified: Subfolder discovery (e.g. ~/.archon/workflows/personal/foo.yaml) — discovery surfaces these but GET still 404s. PUT also writes only to top level. Out of scope for this PR; would need a paired GET+PUT change.

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: Only GET /api/workflows/:name. The Web UI workflow builder benefits; the CLI was already correct.
• Potential unintended effects: A home-scoped file with the same name as a bundled default will now win over the bundled version on GET — matching the priority documented in workflow-discovery.ts. This was already the case in archon workflow list and execution; the GET route was the outlier.
• Guardrails/monitoring: Existing Pino logging (workflow.fetch_home_failed) added for non-ENOENT read errors.

Rollback Plan (required)

• Fast rollback: git revert <this commit>. Single-file, additive change with no migrations.
• Feature flags or config toggles: None.
• Observable failure symptoms: 500s on GET /api/workflows/:name for any user with a home-scoped workflow → check workflow.fetch_home_failed log entries.

Risks and Mitigations

• Risk: Home-scoped file shadows a same-named bundled default after this patch (where it didn't shadow on GET before).
  • Mitigation: This matches existing discovery / list / execute behavior, so the fix removes inconsistency rather than introducing it. The GET route was the only path that didn't honor the documented priority.

Summary by CodeRabbit

Release Notes

• New Features
  • Workflows can now be stored and accessed from a global home location. The system automatically checks your home directory for workflows and falls back to project-specific or bundled versions as needed.