feat(config): persist per-project agent config and resolve it at spawn

[neversettle17-101]

Summary

Each project should be able to carry its own agent configuration (model, flags, permission mode, agent-specific keys), but today there is no durable per-project agent config. The legacy TS version resolved this from agent-orchestrator.yaml ("global vs project config resolution"); the Go rewrite split global settings into env vars and project identity into the projects table, but the per-project agent config half was never wired to storage.

The type-level scaffolding already exists — it just has no data source.

Current state

Wired today (per-session, at spawn):

• ports.SpawnConfig carries Harness, Prompt, AgentRules (backend/internal/ports/session.go:7).
• Empty Harness falls back to the daemon-global AO_AGENT default (backend/internal/daemon/lifecycle_wiring.go:142).

Designed but NOT wired:

• ports.AgentConfig (map[string]any) — "values loaded from the selected agent's config section" (backend/internal/ports/agent.go:54).
• ports.ConfigSpec / ConfigField — typed, adapter-declared config keys (backend/internal/ports/agent.go:57).
• LaunchConfig.Config — the carrier into the launch command (backend/internal/ports/agent.go:85).

The gaps:

• projects table has no agent-config columns — only id, path, repo_origin_url, display_name, registered_at, archived_at (backend/internal/storage/sqlite/migrations/0001_init.sql:8).
• At spawn, LaunchConfig is built with Config left empty (backend/internal/session_manager/manager.go:139).
• claudecode.GetConfigSpec returns an empty spec ("no agent-specific config keys yet", backend/internal/adapters/agent/claudecode/claudecode.go:85).

Proposed slice

Following the rewrite's patterns (env for global, DB rows for per-project, validation owned by adapters):

1. Storage — persist per-project agent config keyed by project_id (e.g. a projects.agent_config JSON column, or a project_agent_config table keyed by project_id + harness). Add sqlc queries + migration.
2. Resolution — in startSession / session_manager, load the project's config and populate LaunchConfig.Config before GetLaunchCommand.
3. Validation — each adapter validates its own keys against its ConfigSpec ("Agent adapters own validation for their custom keys").
4. CLI/API surface — set/get per-project agent config (e.g. extend ao project + a projects controller route).

Out of scope

• Pinning a default harness per project (separate concern; can be a follow-up using the same storage).
• Notifier/tracker/SCM per-project config (this issue is scoped to agent config).

Acceptance criteria

• A project can store agent config that survives daemon restart.
• A spawn for that project receives the resolved AgentConfig in LaunchConfig.Config.
• Invalid keys/values are rejected by the owning adapter with a clear error.
• Works OS-agnostically (macOS/Linux/Windows); no new env-only config for per-project state.

🤖 Generated with Claude Code

[neversettle17-101]

Context: how project config reaches SQLite today

Tracing PR #37 (feat(backend): SQLite storage layer + CDC pipeline) clarifies the boundary of this gap:

• PR feat(backend): SQLite storage layer + CDC pipeline #37 created the projects table as "the SQLite twin of the old YAML config (global config.yaml plus per-repo agent-orchestrator.yaml)" — but shipped it dormant (no write handler).
• The write path now exists via the ao project CLI (thin client → daemon HTTP → UpsertProject → SQLite). Users never edit files or touch the DB.

What ao project add configures today: --path, --id, --name only (internal/cli/project.go:151).

The gap: the per-repo agent-orchestrator.yaml half carried agent config (model, flags, permissions). The projects table has no agent-config columns and ao project add has no agent-config flags — so the user-facing config surface for agents is missing, even though the SQLite write path pattern is already proven by ao project add.

Implication for this issue: the CLI/API surface item (step 4) should extend the existing ao project command + projects route, reusing the established thin-client → daemon → SQLite path rather than introducing a new mechanism.

[neversettle17-101]

Solution design

Porting from legacy: packages/core/src/config.ts → AgentSpecificConfigSchema + ProjectConfig.agentConfig.
Owns: ConfigService (sync) + SessionService (resolution at spawn).
Invariants preserved: per-project config is YAML-authoritative; DB is a write-through cache that is always brought in sync on daemon start. LaunchConfig.Config is populated before GetLaunchCommand — nothing else changes.

---

1. What the legacy carries (the spec)

AgentSpecificConfig in packages/core/src/types.ts has these fields (.passthrough() means arbitrary extra keys are valid too):

{
  permissions?: "permissionless" | "default" | "auto-edit" | "suggest"
  model?: string
  orchestratorModel?: string
  [key: string]: unknown   // adapter-specific extras
}

ProjectConfig.agentConfig defaults to {} and is per-project in the YAML. The same shape is also present on worker.agentConfig and orchestrator.agentConfig (role-level overrides), but this issue is scoped to the top-level project config.

---

2. Storage — migration 0004

Add a single nullable JSON column to projects. A separate table would be over-engineered for what is one blob per project.

-- backend/internal/storage/sqlite/migrations/0004_add_project_agent_config.sql
-- +goose Up
-- +goose StatementBegin
ALTER TABLE projects ADD COLUMN agent_config TEXT;   -- NULL = not set; non-NULL = JSON object
-- +goose StatementEnd

-- +goose Down
-- +goose StatementBegin
-- SQLite does not support DROP COLUMN before 3.35; leave as no-op or recreate.
-- +goose StatementEnd

---

3. Domain

// backend/internal/domain/project.go
type ProjectRecord struct {
    ID            string
    Path          string
    RepoOriginURL string
    DisplayName   string
    RegisteredAt  time.Time
    ArchivedAt    time.Time
    AgentConfig   map[string]any  // nil = not set
}

map[string]any matches AgentConfig in ports/agent.go exactly — no translation layer needed.

---

4. SQL queries

-- backend/internal/storage/sqlite/queries/projects.sql

-- name: UpsertProject :exec
INSERT INTO projects (id, path, repo_origin_url, display_name, registered_at, archived_at, agent_config)
VALUES (?, ?, ?, ?, ?, ?, ?)
ON CONFLICT (id) DO UPDATE SET
    path         = excluded.path,
    repo_origin_url = excluded.repo_origin_url,
    display_name = excluded.display_name,
    archived_at  = excluded.archived_at,
    agent_config = excluded.agent_config;

-- GetProject / ListProjects / FindProjectByPath: add agent_config to SELECT

JSON round-trip in the store layer:

// store/project_store.go — marshal on write, unmarshal on read
func marshalAgentConfig(cfg map[string]any) (sql.NullString, error) { ... }
func unmarshalAgentConfig(s sql.NullString) (map[string]any, error) { ... }

---

5. Sync: YAML → DB (add + remove)

The project service's Add already calls UpsertProject. Extend it to accept AgentConfig:

// service/project/service.go — Add()
row := domain.ProjectRecord{
    ...
    AgentConfig: in.AgentConfig,   // populated from parsed YAML
}

On daemon start, the config loader iterates YAML projects and calls Add/UpsertProject for each. Delete (archive) is already handled by ArchiveProject — when a project disappears from the YAML, the sync loop calls it, which sets archived_at. The agent config goes away with the row implicitly.

The sync loop is the only caller that needs changing — AddInput gains an optional AgentConfig map[string]any field.

---

6. Resolution at spawn

// session_manager/manager.go — startSession / SpawnSession
proj, ok, err := m.projectStore.GetProject(ctx, string(cfg.ProjectID))
// ...
argv, err := agent.GetLaunchCommand(ctx, ports.LaunchConfig{
    SessionID:     string(id),
    WorkspacePath: ws.Path,
    Prompt:        prompt,
    IssueID:       string(cfg.IssueID),
    Config:        ports.AgentConfig(proj.AgentConfig),  // ← wire this in
})

ports.AgentConfig is already map[string]any — no cast needed beyond the type alias.

---

7. Adapter validation

claudecode.GetConfigSpec currently returns an empty spec. Extend it with the keys the adapter understands:

func (p *Plugin) GetConfigSpec(_ context.Context) (ports.ConfigSpec, error) {
    return ports.ConfigSpec{
        Fields: []ports.ConfigField{
            {Key: "model",       Type: ports.ConfigFieldString, Description: "Model override (e.g. claude-opus-4-5)"},
            {Key: "permissions", Type: ports.ConfigFieldEnum,   Enum: []string{"default","accept-edits","auto","bypass-permissions"}},
        },
    }, nil
}

Validation runs in GetLaunchCommand — reject unknown keys against the spec, return a typed error.

---

8. What does NOT change

• ArchiveProject — already handles delete; no new code needed.
• Session lifecycle, state machine, reconciliation invariants — untouched.
• worker.agentConfig / orchestrator.agentConfig role overrides — out of scope for this issue.
• Notifier/tracker/SCM config — separate concern.

---

File checklist

File	Change
backend/internal/storage/sqlite/migrations/0004_add_project_agent_config.sql	New — ALTER TABLE
backend/internal/storage/sqlite/queries/projects.sql	Add agent_config to all SELECT/INSERT
backend/internal/storage/sqlite/gen/	Re-run sqlc generate
backend/internal/storage/sqlite/store/project_store.go	JSON marshal/unmarshal for agent_config
backend/internal/domain/project.go	Add AgentConfig map[string]any
backend/internal/service/project/service.go	Pass AgentConfig through Add → UpsertProject
backend/internal/service/project/store.go	No interface change (Store already takes domain.ProjectRecord)
backend/internal/session_manager/manager.go	Load project, populate LaunchConfig.Config
backend/internal/adapters/agent/claudecode/claudecode.go	Fill GetConfigSpec, validate in GetLaunchCommand

🤖 Generated with Claude Code