feat(daemon): wire Session Manager + agent shim + RepoResolver + inbox messenger

[harshitsinghbhandari]

Summary

PR β in our SM-revival planning. PR #62 (merged 2026-06-01) deleted the Session Manager wiring from the daemon — every call to session.New() was removed; only the integration test still constructs one. This brings SM back end-to-end: calling sm.Spawn() now launches a real Claude Code agent in a real git worktree in a real zellij session, and lifecycle nudges actually reach the agent via an inbox file.

Branches from origin/staging (= main + #65) so @yyovil's claudecode adapter is available. PR base is staging.

What's new

Four new pieces:

• adapters/agent/portshim — bridges the richer adapters/agent.Agent interface (PR Add agent adapters and wire per-session agents into the session manager #65) onto the narrower ports.Agent the SM consumes. POSIX shell-quoting joins argv into the single string the zellij sh -lc wrapper expects.
• adapters/workspace/gitworktree/projectresolver — gitworktree.RepoResolver backed by project.Manager. Lives in its own subpackage so gitworktree stays free of the project import.
• adapters/messenger/inbox — ports.AgentMessenger writing each message as <session-workspace>/.ao/inbox/<nano>_<hash>.md. Symlink-safe via os.Lstat on the .ao / .ao/inbox segments.
• daemon/session_wiring.go — assembles claudecode → portshim, gitworktree over projectresolver, inbox messenger over the sqlite store, and the SM itself. Reuses the existing zellij runtime / project manager / lcm singletons.

Also promotes the duplicated "agentSessionId" metadata key in claudecode and codex to a single agent.MetadataKeyAgentSessionID constant so the portshim has a stable place to populate Session.Metadata for the underlying adapter.

Singleton sharing (the contract this PR enforces)

• One zellij.Runtime services both terminal mux and SM.Spawn (two adapters would race on the same socket).
• One *lifecycle.Manager services both the reaper and the SM (two LCMs would split agent-nudge state).
• One project.Manager services both httpd and the gitworktree RepoResolver.
• One ports.AgentMessenger services both the LCM (PR-driven reactions) and the SM (Send).

Out of scope (covered by follow-ups)

• HTTP routes for SM (POST /sessions, etc.) — γ
• ao session new CLI — γ
• SCM poller — δ (depends on aa-38)
• Codex agent wiring (claude-code only)
• Zellij send-keys pane-ping (agent reads inbox on demand)

References

• Re-introduces SM wiring deleted by refactor: simplify session lifecycle and zellij runtime #62.
• Wires the claudecode adapter added by Add agent adapters and wire per-session agents into the session manager #65 (@yyovil).

Test plan

• go test -race ./... — 323/324 pass (the 1 failure is TestSessionStreamsRealZellijPane, a pre-existing host-env issue: \$TMPDIR > 103 chars exceeds zellij's IPC socket limit; also fails on origin/staging without these changes)
• go vet ./... clean
• gofmt -l backend/ clean
• goimports -l clean
• portshim tests: 15 cases (shell quoting, env, restore propagation, error fall-through)
• projectresolver tests: 4 cases (happy / unknown / degraded / interface satisfaction)
• inbox tests: 9 cases (happy / dir-create / two-distinct / unknown session / empty workspace path / symlinked inbox refused / empty message / filename shape / interface satisfaction)
• daemon wiring test: SM stack constructed, shares singletons, messenger reaches store-known workspace end to end

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR re-wires the Session Manager end-to-end after it was removed in #62, adding four new components: a portshim bridging the richer agent.Agent interface to ports.Agent, a projectresolver subpackage connecting the gitworktree workspace to the project store, an inbox messenger writing lifecycle nudges as files under <workspace>/.ao/inbox/, and session_wiring.go assembling them all from shared daemon singletons.

• portshim translates argv slices to POSIX-quoted shell strings and adapts context-bearing agent calls to the context-free port interface; it silently returns \"\" on adapter errors since ports.Agent.GetLaunchCommand has no error return, and it zeros the Permissions field in both launch and restore configs because the port interface carries no permission mode.
• inbox messenger guards against symlinked .ao/.ao/inbox directories via os.Lstat and generates collision-resistant filenames from nanosecond timestamps plus SHA-256 prefixes.
• daemon.go correctly constructs singletons once and threads them through both startLifecycle and buildSessionStack; the SM stack is built but intentionally unused (_ = ss) pending HTTP route work in a follow-up PR.

Confidence Score: 3/5

The wiring is structurally sound and the singleton contract is correctly enforced, but the portshim silently returns an empty launch command on adapter error, which can cause the Session Manager to record a successful spawn while no agent process is actually running.

The portshim swallows GetLaunchCommand errors and returns an empty string. The SM passes that string directly to runtime.Create without checking it, so if the claude binary is missing the daemon creates a zellij session with sh -lc empty string, marks it spawned, and the caller gets back a valid domain.Session with no agent behind it. The reaper will eventually clean up the zombie, but no error is surfaced at spawn time. The permission-mode zeroing and context.Background() propagation are known port-interface limitations that do not introduce incorrect state.

backend/internal/adapters/agent/portshim/shim.go warrants the closest review — specifically how GetLaunchCommand and GetRestoreCommand handle errors and the absence of permission-mode propagation.

Important Files Changed

Filename	Overview
backend/internal/adapters/agent/portshim/shim.go	New bridge from richer agent.Agent to ports.Agent; correctly implements POSIX shell quoting but silently drops adapter errors in GetLaunchCommand (returns empty string) and zeros permission modes in both launch and restore paths.
backend/internal/adapters/messenger/inbox/inbox.go	New AgentMessenger writing timestamped+hashed .md files under workspace/.ao/inbox/; symlink safety via Lstat on .ao and .ao/inbox segments is sound; TOCTOU window between Lstat and MkdirAll is documented and acceptable given the workspace ownership model.
backend/internal/adapters/workspace/gitworktree/projectresolver/resolver.go	New subpackage bridging project.Manager to gitworktree.RepoResolver; cleanly prevents the import cycle; correctly surfaces degraded/unknown project as errors to avoid silent empty-path worktree creation.
backend/internal/daemon/session_wiring.go	New wiring file assembling the session stack; singleton contract is correctly enforced by threading shared instances; storeWorkspaceLookup correctly refuses empty workspace paths before inbox writes.
backend/internal/daemon/daemon.go	Singletons (runtimeAdapter, projects, messenger) are now constructed once and shared correctly; error-path cleanup for buildSessionStack failure is consistent with the pre-existing httpd error path.
backend/internal/daemon/lifecycle_wiring.go	LCM now receives the real messenger (was nil); lcm field exposed on lifecycleStack so the SM can share the same instance; straightforward change with no issues.
backend/internal/adapters/agent/agent.go	Promotes the duplicated agentSessionId string literal to MetadataKeyAgentSessionID constant; clean deduplication with no logic changes.
backend/internal/adapters/agent/claudecode/claudecode.go	Migrates claudeAgentSessionIDMetadataKey usages to agent.MetadataKeyAgentSessionID; no behavioral change.
backend/internal/adapters/agent/codex/codex.go	codexAgentSessionIDMetadataKey now aliases agent.MetadataKeyAgentSessionID instead of duplicating the string literal; const aliasing another const is valid Go and produces the same value.
backend/internal/daemon/wiring_test.go	New wiring test verifies singleton sharing via pointer identity and exercises the end-to-end Send path through the shared store; cleanup order (cancel then Stop) is correctly handled to avoid deadlock.

Sequence Diagram

sequenceDiagram
    participant D as daemon.Run
    participant LC as startLifecycle
    participant SS as buildSessionStack
    participant PM as portshim.Shim
    participant CC as claudecode.Plugin
    participant SM as session.Manager
    participant WS as gitworktree.Workspace
    participant RT as zellij.Runtime
    participant IB as inbox.Messenger
    participant ST as sqlite.Store

    D->>LC: startLifecycle(ctx, store, runtime, messenger)
    LC-->>D: "lifecycleStack{lcm, reaperDone}"

    D->>SS: buildSessionStack(cfg, store, runtime, projects, lcm, messenger)
    SS->>PM: portshim.New(claudecode.New())
    SS->>WS: gitworktree.New(projectresolver.New(projects))
    SS->>SM: "session.New(Deps{...})"
    SS-->>D: "sessionStack{sm, workspace, messenger}"

    Note over D: _ = ss (routes in follow-up PR)
    D->>RT: srv.Run(ctx)

    Note over SM,RT: On Spawn()
    SM->>PM: GetLaunchCommand(AgentConfig)
    PM->>CC: GetLaunchCommand(context.Background, LaunchConfig)
    CC-->>PM: argv or err
    PM-->>SM: shell-quoted string or empty string on err
    SM->>WS: Create(WorkspaceConfig)
    WS-->>SM: "WorkspaceInfo{Path, Branch}"
    SM->>RT: "Create(RuntimeConfig{LaunchCommand})"
    RT-->>SM: RuntimeHandle

    Note over SM,IB: On Send()
    SM->>IB: Send(ctx, sessionID, message)
    IB->>ST: WorkspacePath(ctx, id)
    ST-->>IB: workspace path
    IB->>IB: ensureRealDir(.ao, .ao/inbox)
    IB->>IB: WriteFile(nano_hash.md)

Loading

Comments Outside Diff (3)

1. backend/internal/adapters/agent/portshim/shim.go, line 134-140 (link)

   Adapter error silently becomes an empty launch command

   When s.agent.GetLaunchCommand returns an error (e.g., the claude binary is not on $PATH), the shim returns "". session.Manager.Spawn passes that empty string directly to runtime.Create without checking it, so a zellij session is created with sh -lc "". The pane exits immediately and the SM records a successful spawn. The caller gets a domain.Session object with a live ID, unaware that no agent is actually running. The error from the underlying adapter is entirely swallowed — there is no log line and no observable failure until the reaper cleans up the stale session.

2. backend/internal/adapters/agent/portshim/shim.go, line 169-175 (link)

   Permission mode is silently zeroed for both launch and restore

   launchConfigFor omits Permissions (leaving it at the zero value ""), and GetRestoreCommand likewise leaves RestoreConfig.Permissions unset. claudecode.appendPermissionFlags is called with an empty PermissionMode, so every session launched or restored via this shim gets whatever default Claude's TUI resolves from the user's ~/.claude/settings.json. A session originally spawned in bypassPermissions mode will silently revert to the configured default on restore, causing Claude to halt and prompt for approval instead of running autonomously. Neither the SM nor the caller is informed of this mode drop. The ports.AgentConfig and ports.Agent.GetRestoreCommand signatures do not carry a permissions field, so the shim cannot fix this without a port interface change — but the loss is currently invisible.

3. backend/internal/adapters/agent/portshim/shim.go, line 119-128 (link)

   context.Background() prevents cancellation propagation on all adapter calls

   The shim threads context.Background() into every call to the wrapped agent.Agent — including binary lookup in GetLaunchCommand, which may shell out to exec.LookPath. If the daemon is shutting down (context cancelled) or Spawn is cancelled mid-flight, those adapter calls continue running until they complete naturally. The comment acknowledges this as a known limitation ("context-free at its API surface"), but consider at minimum logging a warning when context.Background() is used during an already-cancelled parent call, to make debugging easier.

_{Reviews (1): Last reviewed commit: "feat(daemon): wire Session Manager + age..." | Re-trigger Greptile}