Codeman/docs/session-lineage-lines-plan.md

Session lineage lines (spawn lines between tabs)

Goal: when a session spawns another session (the codeman agent skill starting a worker, or anything else that says who it is), draw the same kind of glowing connection line the subagent windows already use, but tab → tab, so a glance at the strip shows which tab spawned which.

Status: PLAN. Nothing implemented yet.

---

1. The blocking fact: no parent relationship exists today

There is no spawn-parent link between sessions anywhere in the codebase:

• SessionState (src/types/session.ts:388) has no parentSessionId / spawnedBy / createdBy.
• POST /api/quick-start and POST /api/sessions record only owner = ownerFor(req), which is the multi-user human, not the calling session.
• The only parent links that do exist are TeamConfig.leadSessionId (agent teams) and subagent-parents.json (a frontend window-layout store for subagent windows). Neither says "session A spawned session B".
• Nothing in the HTTP request identifies the caller: an agent's spawn call is plain curl from inside a tmux pane, so there is no socket-level identity to recover (SO_PEERCRED needs a unix socket; the API is TCP).

So the caller has to tell us. It already knows its own id: every managed pane gets CODEMAN_SESSION_ID exported by session-cli-builder.ts (and the skill's §0 preamble already binds it to $SELF).

2. Wire format

Two ways in, because they serve different callers. Body wins when both are present.

Where	Shape	Who uses it
body field	"parentSessionId": "<uuid>"	anything hand-writing one create call
request header	X-Codeman-Parent-Session: <uuid>	the skill: added once to the CURL array in the §0 preamble, so every present and future create call carries it with no per-recipe edit

Rules, all of them deliberate:

• Advisory decoration only. It never grants access, never scopes anything, never affects lifecycle. A child is not killed when its parent dies; the line just stops being drawn once the parent tab is gone.
• Never fails a spawn. An unknown / stale / foreign parent id is silently dropped (field ends up undefined), not a 400. A cosmetic field must not be able to break worker creation.
• Resolved, not trusted. The id must match a live session the caller can already see (canAccessOwned), and the resolved parent's owner must equal the new session's owner. Otherwise a user could staple their session under another user's tab in multi-user mode.
• Exact id match first; a >= 8-char unique prefix match as a fallback (ids appear truncated in mux names and UI surfaces; ambiguous prefixes resolve to nothing).

3. Server changes

File	Change
src/types/session.ts	SessionState.parentSessionId?: string with a doc comment saying it is UI decoration and never a permission signal
src/session.ts	constructor option parentSessionId → _parentSessionId, public getter, emitted from toState() (~line 1170)
src/web/schemas.ts	parentSessionId: z.string().max(100).optional() on CreateSessionSchema (272) and QuickStartSchema (680). Neither is .strict(), so this is additive
src/web/route-helpers.ts	new resolveParentSessionId(ctx, req, bodyValue, owner) implementing §2's rules; returns string | undefined, never throws
src/web/routes/session-routes.ts	pass it into the three new Session({...}) sites: POST /api/sessions (846), POST /api/run (2522), POST /api/quick-start (2896)
src/web/server.ts	recovery path (~2617): parentSessionId: savedState?.parentSessionId so the link survives a restart

No new SSE event. session_created / session_updated broadcast getSessionStateWithRespawn(session), which is toState()-derived, so the field rides along to the browser for free — and the frontend already does this.sessions.set(data.id, data), so session.parentSessionId is simply there.

Optional follow-up: surface it on /api/sessions/unified rows so the Session Manager and the home rails can show "spawned by w3-claudeman".

4. Frontend rendering

4.1 Where the code goes

_updateConnectionLinesImmediate() (subagent-windows.js:242) is a strict batched read → batched write pass, and it already has an extension point: ultracode appends its own layer via _appendUltracodeConnectionLines(svg, rects) at the end, sharing the rects cache so no layer forces a second reflow.

Lineage lines follow that exactly: a new module src/web/public/session-lineage.js (load order 15.6, after ultracode-windows.js) exporting _appendLineageConnectionLines(svg, rects) onto CodemanApp.prototype, called from the same tail. The core function keeps ownership of the read/write split; the new layer only reads through the shared rects map and only appends paths.

The path math itself lives in constants.js as a pure computeLineagePath(parentRect, childRect, stripRect, depth) — same treatment as computeTabScrollLeft, so the geometry is unit-testable without a browser.

4.2 Geometry

Both endpoints are tabs in one horizontal strip, so the subagent shape (tab-bottom → window-top) does not apply. Two cases:

• Same row (the normal case): a shallow U-bridge hanging below the strip. y0 = max(parent.bottom, child.bottom), dip d = clamp(14 + |x2 - x1| * 0.06, 16, 44) + depth * 6, path M x1 y0 C x1 y0+d, x2 y0+d, x2 y0. depth is the child's index among its siblings, so several children of one parent nest instead of overprinting.
• Different rows (tabs-two-rows / tabs-auto-wrap on desktop): the existing vertical bezier from parent-bottom-center to child-top-center.

A small <circle r="3"> at the child end marks direction (an SVG marker would need a <defs> block and fights stroke-dasharray).

Each path gets class="connection-line lineage-line", data-parent-tab, data-child-tab, and data-agent-id="lineage:<childId>" — that last one is what makes the existing entrance machinery (markConnectionLineEntering / _applyLineEntrances, keyed on data-agent-id) work on these lines with zero new animation code, including the negative-animation-delay resume across the svg.innerHTML = '' rebuild.

4.3 Clipping

.session-tabs is overflow-x: auto, so a tab scrolled out of the strip still has a rect — one that lies outside the strip box and would draw an arc across the logo or the header buttons. Skip any edge whose parent or child center falls outside stripRect (4px tolerance). Skipping is honest; clamping would draw a line to a tab that is not there.

4.4 Redraw triggers

updateConnectionLines() already coalesces through scheduleBackground, so extra callers are cheap. Needed:

• _fullRenderSessionTabs() — already calls it (app.js:3912). Free.
• _renderSessionTabsImmediate() — does not. A badge appearing widens a tab and moves every tab after it, which slides the arcs off their anchors. Add the call, guarded on this._lineageEdgeCount > 0 so nobody pays for it without the feature.
• strip scroll (passive listener on #sessionTabs) — the arcs must track the scroller. This is new; no existing line layer needed it.
• window resize — piggyback the throttled handler in terminal-ui.js:930.
• _onSessionCreated — markConnectionLineEntering('lineage:' + data.id) so a new child draws in if the user has a line-entrance theme on (all entrance styles are legacy/off by default, so this is a no-op for an untouched install).

4.5 Styling

.connection-line.lineage-line: violet stroke from a --lineage-line token, stroke-width: 2, dasharray 4 4, opacity: .55, softer glow than the subagent lines so the two layers read as different things. Trap to respect: the skin block nests under html:not([data-skin="og"]), so a bare .lineage-line rule inside it would outrank the base rule at higher specificity. Define the color as a token per skin, keep exactly one .lineage-line rule. Light skins get a darker stroke.

Optional signal worth having: .lineage-line--working (a slow stroke-dashoffset march) only while the child session is working, wrapped in prefers-reduced-motion: no-preference. Static otherwise — a permanently marching line per tab pair is noise and battery.

4.6 Desktop only, and why

The SVG overlay is z-index: 999. On desktop the header is z-index: 100, so arcs paint over the header and can touch tab bottoms. Under 1024px mobile.css makes the header position: fixed; z-index: 1200, which would bury the arcs — and the phone strip is a scroller where both endpoints are rarely on screen together anyway. So the layer returns early unless MobileDetection.getDeviceType() === 'desktop'.

Raising the SVG to ~1250 (above the fixed header, below modals at 1300) is a possible phase 2, but it needs a real check against the mobile overview and the drawer.

4.7 Setting

sessionLineageLines, per-device — so it goes in the displayKeys set in settings-ui.js and must not be added to SettingsUpdateSchema (.strict(); sending an undeclared key fails the whole PUT). Rendered as a switch in App Settings → Appearance, beside the entrance-animation pickers.

Default: ON for desktop (phones never render it). This is the one deliberate departure from the "new visual surfaces ship OFF" convention — the feature is the request, and a user with 12 unrelated tabs has a one-click off switch. Flag for the owner if the convention should win instead.

5. Optional extras (call them separately, none are required)

1. Order children after their parent in sessionOrder on create, so arcs stay short and the strip reads as a tree. Real cost: it renumbers the Alt+N badges and moves tabs under the user's cursor, so it should be its own toggle, default OFF.
2. Lineage hover focus: hovering a tab dims unrelated arcs and brightens its own subtree.
3. "Spawned by" in the Session Manager / home rails, once parentSessionId is on the unified rows.
4. Inherited tab tint: children pick up a faded version of the parent's tab color.

6. Tests

• test/session-lineage.test.ts (route-level, app.inject): round-trips through POST /api/sessions + POST /api/quick-start, header path, body-wins-over-header, unknown id dropped without failing the spawn, cross-owner parent dropped in multi-user, field present in GET /api/sessions and persisted state.
• test/session-lineage-lines.test.ts (jsdom, pure): computeLineagePath — same-row U, wrapped-row bezier, sibling nesting depth, off-strip skip, degenerate zero-width rects.
• Browser check (not in test:ci): spawn two workers with a parent, assert two path.lineage-line elements anchored to the right tabs, then scroll the strip and assert they moved.
• Existing guards that must stay green: test/mobile-header-buttons-policy.test.ts (nothing new on phones), test/app-settings-structure.test.ts (the new switch pairs with its rail section).

7. Skill side (owned by the release session, not this plan)

One line in the codeman skill's §0 preamble covers every spawn recipe:

CURL=(curl -sk "${AUTH[@]}" -H "X-Codeman-Parent-Session: $SELF")

plus a CODEMAN_PREAMBLE version bump so stale cached preambles fail loudly instead of silently spawning unparented workers. Recipes that build a create payload by hand can alternatively send "parentSessionId":"'"$SELF"'".

8. Docs to update when it lands

CLAUDE.md (a Key Patterns bullet), docs/architecture-invariants.md (new anchor: the resolve-don't-trust rule, the desktop-only z-index reason, the shared rects pass), docs/api-reference.md (the new field + header on the create endpoints).