PM Session Link

What it is

PM Session Link is bidirectional linking between a working session and a Mission Control board item -- the session shows which item it targets, and the board shows the agent's live progress on that item.

A session can be linked to a PM item at creation or afterwards. The link is atomic -- both sides are written in one SQLite transaction so they can never disagree about whether the link exists.

Where to find it

The link appears in two places. On the session side, the session header carries a chip naming the item the session targets. On the board side, the item shows the linked session's live agent state in real time.

Starting a brand-new linked session straight from an item is offered as a command-line route rather than a click.

How it behaves

Once linked:

• The session header shows a chip with the item's name.
• Status changes on the session are pushed to the board so it can show real-time agent state (idle, running, needs_you, finished, error).
• An agent can start a new linked session directly from an item.

Linking to an item that is already linked is a no-op (no write, no event). Unlinking removes both sides atomically.

There is no dedicated setting. The feature requires Mission Control to be enabled.

Not built yet: system comments back onto the item when a session's status changes -- there is no backend comment endpoint for it yet.

For agents

All channels are defined in src/shared/ipc-channels/pm.ts under the PM_SESSION_* prefix:

• PM_SESSION_SET_LINK -- link or unlink a session to/from an item
• PM_SESSION_LINKED_SESSIONS -- list sessions linked to an item
• PM_SESSION_GET_LINKED_ITEM -- get the linked item for a session
• PM_SESSION_LINK_CHANGED -- push-only event on link/unlink/status change

Push payloads are Zod-validated against PM_SESSION_PUSH_SCHEMAS and keyed-coalesced by sessionId in push-bus.ts.

The FK is sessions.pm_item_id (nullable), with a companion row in pm_item_links (entity_type = 'session'). Both are written in one SQLite transaction in pm-agent-link.ts. Status changes are mapped through toPmAgentState to a fixed vocabulary (idle, running, needs_you, finished, error). Positive and negative caches (max 1000 entries each, FIFO eviction) avoid repeated lookups. The header chip is PmItemChip, and the route that starts a linked session from an item is POST /pm/items/:id/start-session. Requires the missionControlEnabled setting; there is no dedicated setting of its own.

Related

The parent page for the boards this links to is mission-control.md, which covers the whole project management system this feature hangs off. If you are looking for the items that belong to you rather than the ones a session is working, pm-my-work.md is the one to read next, and pm-cross-entity-links.md covers the other kinds of links a board item can carry. The full behavioural contract is recorded in pm-session-link-contract.md, and every other page in this library is listed in INDEX.md.