feat(agents): add server-side projects with working directory support

[KyleAMathews]

Agents now have projects (named directories) that set the agent's working directory and group sessions in the sidebar. Also adds a 404 page, UI polish, and AGENTS.md context loading. Previously, all sessions shared the server's startup cwd and appeared in a flat timeline.

Approach

Projects — three layers, bottom-up

1. Server-side project store (project-store.ts)
Projects persist to ~/Library/Application Support/electric-agents/projects.json (or OS equivalent) via env-paths. Plain JSON read/write — no database needed for a handful of user-defined entries. Path validation expands ~ and resolves symlinks so stored paths are always canonical absolute paths.

2. REST API (project-routes.ts)
ProjectRoutes class following the existing ElectricAgentsRoutes pattern:

• GET/POST /_electric/projects — list and create
• PATCH/DELETE /_electric/projects/:id — update and delete
• POST /_electric/validate-path — pre-submit validation for immediate UI feedback

Wired into server.ts before entity-type routes so the path prefix doesn't collide.

3. UI + agent wiring

• useProjects hook rewritten from localStorage to server API
• NewSessionPage redesigned with a hero heading (rotating verbs: "Let's ship", "Let's build", etc.) and a popover project picker with inline create form
• On spawn, the active project's path is passed as workingDirectory in spawn args and the session is tagged with the project ID for sidebar grouping
• Horton's creationSchema accepts an optional workingDirectory; the handler computes effectiveCwd (prefer spawn arg, fall back to server default) and validates the directory exists before running — writes a clear error to the stream if invalid

404 page

EntityPage now detects missing entities: if 2 seconds pass with the entities collection loaded and no match, it shows a "Not found" page instead of spinning "Loading entity..." forever. Unknown routes are caught by notFoundComponent on the root route. Removed the silent redirect-on-error from GenericEntityBody — errors now surface in the timeline instead of silently navigating home.

AGENTS.md context

Horton now reads AGENTS.md from the working directory (if it exists) and includes it as a stable context source, wrapped in XML tags. This gives agents project-specific instructions without manual prompting.

UI polish

Warmer light theme, tool trace refinements, focus fixes, wider chat column, font switch from Inter to Figtree.

Key invariants

• Stored project paths are always resolved absolute paths (validated + expanded at creation time)
• activeProjectId in localStorage is reconciled against the server list on load — stale references to deleted projects are cleared
• Horton validates effectiveCwd exists before tool setup; invalid directories produce a user-visible error instead of mysterious tool failures
• workingDirectory is filtered from the composer's inline pill controls so it doesn't leak as a user-facing schema field
• Entity 404 only triggers after 2s with the collection loaded — avoids false positives during initial sync

Non-goals

• No file-level locking on the project store. Concurrent writes from multiple tabs could race, but for a single-user dev tool this is acceptable.
• No shared Project type. The interface is duplicated between server and client. Will be unified when the projects data model is redesigned.
• Error handling on fetch/delete/rename is minimal. These hooks will be rewritten when projects move to a different storage layer.

Verification

pnpm vitest run packages/agents/test/

Manual:

• Create a project via the popover (try ~/some/path and absolute paths)
• Verify project persists across page refresh
• Start a session with a project selected — check horton operates in that directory
• Start a session without a project — verify default cwd behavior
• Delete a project's directory on disk, start a session — verify clear error message
• Navigate to a nonexistent entity URL — verify 404 page appears
• Navigate to a garbage URL — verify catch-all 404

Files changed

File	What
agents-server/src/project-store.ts	New — JSON file store with env-paths, ~ expansion
agents-server/src/project-routes.ts	New — REST CRUD + path validation
agents-server/src/server.ts	Wire project routes before entity-type routes
agents/src/agents/horton.ts	workingDirectory spawn arg, effectiveCwd validation, AGENTS.md context
agents-server-ui/src/router.tsx	404 page for missing entities and unknown routes
agents-server-ui/src/hooks/useProjects.tsx	Rewrite from localStorage to server API, stale ID reconciliation
agents-server-ui/src/components/NewSessionPage.tsx	Hero layout, rotating verbs, popover project picker
agents-server-ui/src/components/NewSessionPage.module.css	Styles for hero + project picker
agents-server-ui/src/ui/tokens.css	Switch body font to Figtree, bump --ds-text-sm, warmer palette
agents-server-ui/src/components/toolBlock.module.css	Tool trace polish
agents-server-ui/src/components/EntityTimeline.module.css	Timeline style tweaks
agents-server-ui/src/router.module.css	Wider chat column

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 21.38365% with 375 lines in your changes missing coverage. Please review.
✅ Project coverage is 62.50%. Comparing base (a3cee92) to head (a078c5f).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...agents-server-ui/src/components/NewSessionPage.tsx	0.00%	85 Missing ⚠️
packages/agents-server/src/project-routes.ts	0.00%	67 Missing ⚠️
...ackages/agents-server-ui/src/hooks/useProjects.tsx	0.00%	60 Missing ⚠️
packages/agents-server/src/project-store.ts	4.34%	44 Missing ⚠️
...ages/agents-server-ui/src/lib/entity-connection.ts	0.00%	27 Missing ⚠️
...es/agents-server-ui/src/hooks/useEntityTimeline.ts	0.00%	23 Missing ⚠️
packages/agents-server-ui/src/router.tsx	0.00%	21 Missing ⚠️
packages/agents/src/agents/horton.ts	36.66%	18 Missing and 1 partial ⚠️
packages/agents-runtime/src/pi-adapter.ts	77.27%	10 Missing ⚠️
...nts-server-ui/src/components/MarkdownCodeBlock.tsx	0.00%	9 Missing ⚠️
... and 6 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4273      +/-   ##
==========================================
- Coverage   63.06%   62.50%   -0.57%     
==========================================
  Files         184      186       +2     
  Lines       19932    20274     +342     
  Branches     4962     5052      +90     
==========================================
+ Hits        12571    12673     +102     
- Misses       7358     7597     +239     
- Partials        3        4       +1     

Flag	Coverage Δ
packages/agents	60.62% <35.48%> (-0.58%)	⬇️
packages/agents-runtime	79.64% <86.17%> (+0.40%)	⬆️
packages/agents-server	64.18% <8.13%> (-1.86%)	⬇️
packages/agents-server-ui	1.58% <0.00%> (-0.07%)	⬇️
packages/electric-ax	38.59% <ø> (ø)
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (ø)
packages/start	82.83% <ø> (ø)
packages/typescript-client	94.27% <ø> (ø)
packages/y-electric	56.05% <ø> (ø)
typescript	62.50% <21.38%> (-0.57%)	⬇️
unit-tests	62.50% <21.38%> (-0.57%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.