---
title: PM Session Link
---

# 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](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](pm-my-work.md) is the
one to read next, and [pm-cross-entity-links.md](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](../../.claude/memory/contracts/pm-session-link-contract.md), and
every other page in this library is listed in [INDEX.md](INDEX.md).