[likun666661]

Summary

This is PR 1 of the implementation sequence proposed in #1366, rebased onto the SQLite session metadata control plane completed by #1370.

• add a typed, durable subagentParent relation to child session headers and summaries
• preserve branch/revision lineage as separate concepts and reject mixed lineage
• keep the relation child-owned and immutable; parents do not persist reciprocal child ID arrays
• persist full relation provenance in the canonical SQLite metadata payload
• add an indexed subagent_parent_session_id projection for reverse lookup
• expose SessionManager.listChildSessions(parentSessionId) without changing agent_spawn or agent_swarm execution
• accept legacy JSONL session headers where the relation is absent

Relation contract

interface SubagentSessionParent {
  kind: 'subagent';
  parentSessionId: string;
  spawnedBy: {
    parentRunId: string;
    parentTurnId: string;
    toolCallId: string;
  };
  swarm?: {
    swarmId: string;
    itemId: string;
  };
  lifecycle: 'foreground';
}

The child session remains the sole source of truth. Reverse lookup is derived from the canonical child metadata instead of persisting a reciprocal child ID array on the parent.

SQLite storage model

• schema v3 adds session_metadata.subagent_parent_session_id
• the migration backfills the indexed column from existing v2 payload_json
• create/import/update paths keep the indexed column consistent with the canonical payload
• SessionListFilter.subagentParentSessionId becomes a keyed SQLite query
• the legacy file store fails closed for relation queries; there is no JSONL full-scan fallback

Non-goals

• no child-session creation primitive yet
• no spawn/swarm migration
• no graph scheduler concepts
• no historical AgentRun rewrite

Validation

• npm run typecheck --workspace @maka/core --workspace @maka/storage --workspace @maka/runtime
• npm --workspace @maka/core test (all passed)
• npm --workspace @maka/storage test (446 passed, 1 platform skip)
• npm --workspace @maka/runtime run build
• node --test packages/runtime/dist/__tests__/session-manager.test.js (202 passed)
• Biome check on all changed files

Part of #1366. Builds on #1370.

[likun666661]

One storage/read-model question before this direction gets locked in:

Maka already has a SQLite runtime store with schema migrations and indexed queries, but listChildSessions(parentSessionId) is currently implemented through FileSessionStore.list(), which scans every session directory, reads each header, and filters on subagentParent.parentSessionId.

I understand the current boundary: runtime.sqlite owns RuntimeEvents/tool-journal state, while Session headers remain file-backed, and SQLite canonical mode is still optional. Still, linked child sessions are expected to become a Host/Desktop-facing tree projection and may be queried frequently. Is this full scan intended only as a compatibility fallback, or is it the intended long-term read model?

It may be worth explicitly documenting the storage direction here. Two possible paths would be:

• keep the child header as the source of truth, but maintain a rebuildable SQLite session_relations projection/index; or
• plan a SQLite-backed SessionStore and query the relation directly there.

Otherwise the API looks like a keyed lookup while its cost is O(all sessions), and future lineage/status/descendant/usage queries may continue accumulating as filesystem scans. I do not think PR 1 necessarily needs to perform the whole SessionStore migration, but the intended ownership and scalability boundary seems important to settle before the Host projection work lands.