Pin a session

What it is

Pinning marks one session as "keep this where I can see it". A pinned session moves out of the run of the list into its own Pinned section, drawn below Needs You and above the rest of the project's list, and it stays there until you unpin it.

• It is a flag, not a status. Pinning does not pause, stop, archive, save or restart anything — a running agent keeps running, an ended session stays ended. Unpinning hands the session straight back to whatever section its own status earns.
• It is its own section, not a sort weight. Pinned is a real sidebar section, drawn below Needs you and above the rest of the project's list. It is not "sort these rows first".
• Attention does not win. A pinned session that needs you stays in Pinned rather than appearing in Needs you as well. This is the one place where pin differs from Save, where a saved-but-needing-you session is shown in Needs you instead.
• Archived is excluded. An archived session never shows in Pinned — unarchive it first.
• It survives restarts. The pin is stored, not remembered by the window you happened to click in. Every open client follows: pin on the desktop and the phone's sidebar shows the same order.

Do not confuse it with three other things that also use the word "pin":

• Pin a project — pins a whole project above the scrollable project list (reorder-projects.md).
• Pin a command to the session bar — turns a session-header action into a one-tap button, set in Settings → Session bar (session-bar-commands.md).
• Pin a sheet, prompt or bookmark — unrelated lists that keep their own favourites.

Where to find it

• Right-click any session row — in the sidebar or in the Inbox. Pin is in the first block of the menu, alongside Snooze and Save.
• The ⋯ button on the row (it appears when you hover the row) opens the same menu, so you never have to know about right-click.
• The ⋯ button on a group's header — the same menu pointed at everything in that group, so you can pin a whole section at once (see session-section-actions.md).
• With several rows selected, Pin applies to every selected session that is not already pinned, and Unpin to every selected session that is. The selection is cleared afterwards.
• Once pinned, the same menu shows Unpin instead.

There is no keyboard shortcut for pinning and no setting that turns it on or off — it is always available. The menu labels read "Pin to the top of the sidebar for quick access." and "Remove from the pinned area at the top of the sidebar."

How it behaves

Where the session goes. A pinned session is drawn in the Pinned section, below Needs you and above the rest of the project's list. Inside Pinned, the order is your own drag order — pinned rows are never re-sorted by time, so a session you drag above another stays above it. Unpinning drops the session back into whichever section its status earns, at its normal sorted position.

What happens when you click. The row moves the instant you click; the save to Omniscio's own database happens after, behind the scenes. If that save fails, the row snaps back to where it was — there is no half-pinned state and nothing to clean up. The session menu arms no Undo and shows no toast for this (pin is not one of the undoable lifecycle actions, unlike archive, move or rename) — the row returning to its old place is the whole visible outcome.

A finished session leaves the hub count. Pinning an ended session moves it onto the Pinned shelf and out of its project's interrupted-session count; unpinning puts it back into that count. So pinning is also a way to say "stop counting this one at me".

Everything else about the session is untouched. Messages, tags, colour, project, and whether the agent is running are all unaffected — this is purely a placement decision.

For agents

Storage and writes

The pin is one column: sessions.is_pinned (0/1), written by pinSession(id, isPinned) in lifecycle.ts — UPDATE sessions SET is_pinned = ? WHERE id = ? AND is_deleted = 0. After the write it calls scheduleEndedCountRefreshIfShelfFlipped({ changed, status }), which refreshes the project's ended/interrupted count when the row moved between the Pinned shelf and that count.

The two IPC handlers SESSION_PIN / SESSION_UNPIN in lifecycle.ts call queries.pinSession(sessionId, true|false), then emitPush(IPC.SESSION_PINNED_CHANGED, { sessionId, isPinned }) — the push that re-renders every open client, desktop and phone alike — and trackEvent('session', 'pinned'|'unpinned', { sessionId }) for the audit log. Both directions are logged separately so dashboards can count each.

Renderer side, pinSession / unpinSession in session-metadata-slice.ts run the shared runOptimisticSessionMutation skeleton with a LIVE-ONLY patch and onFailure: 'plain-restore', and return a boolean so a caller can surface a silently-rolled-back pin. The menu caller, runBulkPinToggle in useSessionContextMenuActions.ts, loops the single-id action over the selection — pinning only the rows not already pinned, unpinning only the pinned ones — then clears the selection, and arms no undo and no toast.

Sidebar membership

pinnedSection() in sidebar-view-engine.ts is the membership rule: integration === 'session' && sourceRef.isPinned === true && status !== 'archived' && !isSilentlyHidden(sourceRef), and its sort is identity — the partition preserves store/drag order, deliberately never a timestamp sort. isNeedsYouMember in the same file excludes isPinned, which is why a pinned session that needs you shows in Pinned and not in Needs you; Pinned is registered after Needs you, and the exclusion is what makes first-match resolve correctly. Per-project ordering lives in session-nav-lists.ts, whose header states the drawn order — Needs You, then this project's OVERSEERS, then Pinned, then Regular Sessions — and builds the list in exactly that sequence; the numbered partition steps above it are construction order, NOT draw order. The render is SessionSectionList.tsx, Needs You first and Pinned after it.

CLI control

Two routes on 127.0.0.1:19519, registered in cli-server-session-mutation-routes.ts:

• POST /session/:id/pin — returns 200 { ok: true, data: { sessionId, isPinned: true } }.
• POST /session/:id/unpin — returns 200 { ok: true, data: { sessionId, isPinned: false } }.

Both are bearer-gated, charge the shared 10/min mutation budget (the pin routes do not use the per-source session-control bucket), apply immediately with no approval queue, and refuse a request body: only the id in the URL applies, so there is nothing else to send.

Related

• save-a-session.md — the neighbouring shelf: Save bookmarks without moving the row; a saved session that needs you surfaces in Needs you instead
• snooze-a-session.md — Snooze hides a session until a time; pin keeps it visible at the top
• archive-a-session.md — archiving removes a session from Pinned; unarchive it first
• session-section-actions.md — the group-header ⋯ menu that pins a whole section at once
• bulk-select-sidebar.md — Pin and Unpin applied across a multi-selection
• move-a-session.md — moving a session between projects, together with its place in the list
• session-bar-commands.md — the other kind of session pin: a command promoted to the session header