fix(pinned): treat pinned roles as interactive interfaces, not loops

Pinned roles (kind: pinned) were modeled as looping oneshots (Option D):
a status:active pinned role with no live session was eligible every poll
tick and re-dispatched — wake, survey, find nothing, exit, repeat. A
pinned status hub (shapepipe) was observed redispatching ~10x in 90min,
burning tokens. The inverse failure: a worker on a pinned role auto-exited
(park + kill $PPID) when idle, going dark while the human wanted to keep
talking — forcing a manual resume of the closed chat.

Root cause: status:active conflates "a session is attached" with "should
be dispatched/looping" — correct for oneshots, wrong for an interactive
interface a human drives.

Fix, two halves:
- Poller: exclude pinned roles from the autonomous tick in filter_eligible/2
  (NOT eligible?, so explicit force/plain dispatch still launches them). A
  pinned active+sessionless role now sits idle until the human resumes.
- Dispatcher: kind-aware exit contract. A pinned worker is told to STAY
  ALIVE at a clean checkpoint and never kill $PPID; the session ends only
  when the human parks the role (active -> open). kind threaded through
  the prompt opts via fiber_kind/1.

Regressions: poller_test (no auto-dispatch of active pinned; no re-dispatch
after exit; force-dispatch still launches) and dispatcher_test (pinned exit
contract inverted vs oneshot). Full suite 459/0.

Finding: ai-futures/shuttle/findings/finding-pinned-roles-are-interfaces-not-loops

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016RVNkdUCoxqgGVVhUoApVp

Author: cailmdaley

lib/shuttle/dispatcher.ex

@@ -97,7 +97,8 @@ defmodule Shuttle.Dispatcher do
           resume_intent ->
             create_tmux_session(fiber_id, agent, work_dir, runner, prompt_context, resume_intent,
               felt_store: felt_store,
-              uid: uid
+              uid: uid,
+              kind: fiber_kind(fiber)
             )
         end
       end
@@ -658,7 +659,7 @@ defmodule Shuttle.Dispatcher do
     # fresh directive.
     [
       header,
-      render_exit_contract(),
+      render_exit_contract(Keyword.get(opts, :kind, "oneshot")),
       render_headless_notice(Keyword.get(opts, :headless, false)),
       render_user_message_block(fiber_id, felt_opts)
     ]
@@ -683,7 +684,23 @@ defmodule Shuttle.Dispatcher do
 
   defp render_headless_notice(_), do: ""
 
-  defp render_exit_contract do
+  # Pinned roles invert the default exit contract. A pinned role is an
+  # INTERACTIVE INTERFACE — a status hub, a debug intake — that a human drives;
+  # the session IS the interface, so a worker that runs out of immediate work
+  # must STAY ALIVE and wait, not `kill $PPID`. The poll loop never re-spawns a
+  # pinned role (see Poller.filter_eligible/2), so a worker that exits leaves the
+  # interface dark until the human manually resumes it — exactly the dead-chat
+  # gap that made this fix necessary. The session ends when the human ends it
+  # (parking the role: `active → open`), never autonomously.
+  defp render_exit_contract("pinned") do
+    render_block(
+      "Exit Contract",
+      nil,
+      "This is a pinned interactive role — a standing interface a human drives, not a one-shot task. Keep the fiber current as you work (outcome, history, findings, commits at clean checkpoints), but when you run out of immediate work DO NOT `kill $PPID`: stay alive and wait for the next message. The session is the interface; it ends only when the human parks the role (`active → open`), not when you finish the task at hand. The poll loop will not re-spawn this role, so exiting goes dark on the human until they manually resume — don't. Reply normally and wait when there's nothing left to drive."
+    )
+  end
+
+  defp render_exit_contract(_kind) do
     render_block(
       "Exit Contract",
       nil,
@@ -849,7 +866,7 @@ defmodule Shuttle.Dispatcher do
 
     [
       String.trim(header),
-      render_exit_contract(),
+      render_exit_contract("oneshot"),
       render_block("From User", nil, String.trim(yap))
     ]
     |> Enum.join("\n\n")
@@ -1080,6 +1097,19 @@ defmodule Shuttle.Dispatcher do
     end
   end
 
+  # The shuttle block's `kind` (new-format) / `mode` (old-format), defaulting to
+  # "oneshot". Threaded into the prompt so the exit contract can diverge for
+  # pinned interactive roles (stay alive) vs oneshot/standing work (exit).
+  defp fiber_kind(fiber) do
+    case Map.get(fiber, "shuttle") do
+      shuttle when is_map(shuttle) ->
+        Map.get(shuttle, "kind", Map.get(shuttle, "mode", "oneshot"))
+
+      _ ->
+        "oneshot"
+    end
+  end
+
   # Dispatch: fresh worker (new session) or resume previous.
   # `resume_intent` is `:fresh | {:previous, session_id}` from check_resume_intent/3.
   defp create_tmux_session(fiber_id, agent, work_dir, runner, prompt_context, resume_intent, opts) do

lib/shuttle/poller.ex

@@ -1668,8 +1668,33 @@ defmodule Shuttle.Poller do
     end
   end
 
+  # The autonomous-tick eligibility filter. Beyond the shared `eligible?`
+  # predicate, the tick excludes pinned roles: a pinned role is an INTERACTIVE
+  # INTERFACE (a status hub, a debug intake), not autonomous work. The human
+  # starts it (drag-to-in-flight / New session / Resume — all force-dispatch),
+  # the worker stays attached as the interface, and the session ends when the
+  # human ends it. The poll loop must never re-spawn it: a pinned `active` role
+  # whose session has ended (human closed the chat, worker crashed) would
+  # otherwise re-dispatch every tick — surveying, finding nothing, exiting —
+  # burning tokens on an idle interface (the shapepipe redispatch loop). Pinned
+  # roles remain explicitly dispatchable: force-dispatch bypasses this entirely,
+  # and a plain `shuttle-ctl dispatch <id>` still routes through `eligible?`
+  # (which has no pinned gate), so only the *autonomous* path is severed.
+  # See [[ai-futures/shuttle/findings/finding-pinned-roles-are-interfaces-not-loops]].
   defp filter_eligible(candidates, state) do
-    Enum.filter(candidates, fn fiber -> eligible?(fiber, state) end)
+    Enum.filter(candidates, fn fiber ->
+      eligible?(fiber, state) and not pinned_role?(fiber)
+    end)
+  end
+
+  defp pinned_role?(fiber) do
+    case Map.get(fiber, "shuttle") do
+      shuttle when is_map(shuttle) ->
+        Map.get(shuttle, "kind", Map.get(shuttle, "mode", "oneshot")) == "pinned"
+
+      _ ->
+        false
+    end
   end
 
   defp eligible?(fiber, state) do
@@ -1718,14 +1743,15 @@ defmodule Shuttle.Poller do
         MapSet.member?(state.claimed, fiber_id) ->
           false
 
-        # A pinned role dispatches exactly like a oneshot: an `active` pinned
-        # fiber is LOOPING — eligible → dispatch → worker exits active →
-        # re-dispatch next poll, until a worker sets `status: closed` or a human
-        # parks it (`active → open`, the `pause` verb). `open` is the parked rest
-        # state, already excluded by the `status != "active"` gate above. So
-        # pinned needs no bespoke branch here; it falls through to the oneshot
-        # dependency check below. (Option D: parked=open, looping=active — the
-        # never-auto-dispatch special case was deleted.)
+        # Pinned roles need no bespoke branch HERE: this predicate also serves
+        # the explicit-dispatch path (`shuttle-ctl dispatch`, plain POST
+        # /dispatch), where a pinned role IS eligible — it's a human asking for
+        # it. The autonomous tick is what must never loop a pinned interface;
+        # that exclusion lives in `filter_eligible/2` (the tick's only caller),
+        # not here. A pinned `active` role with no live session therefore sits
+        # idle until the human re-attaches, instead of re-dispatching every
+        # poll. (Supersedes Option D's "active pinned = looping" model, which
+        # burned tokens re-surveying idle interfaces.)
 
         # Standing roles have additional preconditions; oneshots go to dep check.
         # Support both new-format (kind:) and old-format (mode:) shuttle blocks.

test/shuttle/dispatcher_test.exs

@@ -183,6 +183,24 @@ defmodule Shuttle.DispatcherTest do
     refute prompt =~ "Exit before context is half-full"
   end
 
+  test "render_prompt for a pinned role inverts the exit contract to stay-alive" do
+    # A pinned role is an interactive interface — the worker must NOT kill $PPID
+    # when it runs out of immediate work; it stays attached and waits. The
+    # default (oneshot) contract is the opposite, so the two must not collide.
+    pinned = Dispatcher.render_prompt("tests/haiku", kind: "pinned")
+    assert pinned =~ "Exit Contract"
+    assert pinned =~ "pinned interactive role"
+    assert pinned =~ "DO NOT `kill $PPID`"
+    assert pinned =~ "stay alive and wait"
+    # The autonomous kill-on-exit instruction must be absent for pinned.
+    refute pinned =~ "your final action must be `kill $PPID`"
+
+    # Oneshot (the default) keeps the kill-on-exit contract.
+    oneshot = Dispatcher.render_prompt("tests/haiku")
+    assert oneshot =~ "your final action must be `kill $PPID`"
+    refute oneshot =~ "pinned interactive role"
+  end
+
   test "render_prompt carries the headless notice only when headless: true" do
     # Headless (-p) workers run unattended — the prompt must tell them the
     # human-gate exception can't apply, or they may park at a checkpoint that

test/shuttle/poller_test.exs

@@ -1008,32 +1008,45 @@ defmodule Shuttle.PollerTest do
            end)
   end
 
-  test "poller auto-dispatches a LOOPING (status:active) pinned role, like a oneshot" do
-    # Option D: a pinned role at status:active is LOOPING — eligible and
-    # dispatched on the poll, exactly like an active oneshot. (Old model: the
-    # poller hard-skipped every pinned role; the never-auto-dispatch branch is
-    # gone.) The parked rest state is status:open, covered by the sibling test.
-    fiber = make_fiber("tests/pinned-looping", %{"status" => "active"})
-    MockRunner.set_fiber("tests/pinned-looping", fiber)
-    MockRunner.set_shuttle("tests/pinned-looping", "kind: pinned\n", "active")
+  test "poller does NOT auto-dispatch a status:active pinned role (it's an interface, not a loop)" do
+    # A pinned role is an INTERACTIVE INTERFACE: the human starts it, the worker
+    # stays attached, the session ends when the human ends it. The autonomous
+    # poll loop must never re-spawn it — a status:active pinned role whose session
+    # ended (human closed the chat, worker crashed) would otherwise re-dispatch
+    # every tick, surveying-and-exiting, burning tokens (the shapepipe loop).
+    # The exclusion lives in filter_eligible/2 (the tick), NOT in eligible? — so
+    # force-dispatch still launches it (covered below).
+    fiber = make_fiber("tests/pinned-active", %{"status" => "active"})
+    MockRunner.set_fiber("tests/pinned-active", fiber)
+    MockRunner.set_shuttle("tests/pinned-active", "kind: pinned\nagent: claude-opus\n", "active")
 
     {:ok, poller} =
       start_poller!(
-        name: :test_poller_pinned_looping,
+        name: :test_poller_pinned_active,
         runner: MockRunner,
         poll_interval_ms: 60_000,
         felt_stores: ["/tmp"]
       )
 
     send(poller, :run_poll_cycle)
+    # Flush the poll cycle through the GenServer mailbox.
+    _ = Poller.snapshot(poller)
+
+    refute Enum.any?(MockRunner.commands(), fn {cmd, args} ->
+             cmd == "tmux" and hd(args) == "new-session"
+           end),
+           "the autonomous tick must not spawn a worker for a pinned role"
+
+    # But an explicit force-dispatch (the strip's "start"/"Resume" gesture) DOES
+    # launch it — pinned roles are human-dispatch-only, not never-dispatch.
+    assert {:ok, _session} =
+             Poller.dispatch_fiber(poller, "tests/pinned-active", force: true, ad_hoc: true)
 
     assert wait_until(fn ->
              Enum.any?(MockRunner.commands(), fn {cmd, args} ->
                cmd == "tmux" and hd(args) == "new-session"
              end)
            end)
-
-    assert Enum.any?(Poller.snapshot(poller).eligible, &(&1.fiber_id == "tests/pinned-looping"))
   end
 
   test "poller does NOT auto-dispatch a PARKED (status:open) pinned role" do
@@ -1063,11 +1076,12 @@ defmodule Shuttle.PollerTest do
     refute Enum.any?(Poller.snapshot(poller).eligible, &(&1.fiber_id == "tests/pinned-parked"))
   end
 
-  test "a LOOPING pinned worker exit leaves the role active and re-dispatches next poll" do
-    # Option D: a pinned role at status:active is looping. On worker-exit-while-
-    # active it must stay status:active (NOT marked awaiting like a standing role)
-    # so the next poll re-dispatches it — that's the loop. Only STANDING/cron
-    # roles mark awaiting; a pinned worker that's genuinely done self-closes.
+  test "a pinned worker exit leaves the role active but the next poll does NOT re-dispatch" do
+    # A pinned worker exit must leave the document status:active (NOT marked
+    # awaiting/closed like a standing role) — the interface stays "open" for the
+    # human to resume. But the autonomous poll must NOT re-spawn it: that
+    # combination (active + sessionless + no re-dispatch) is the whole fix.
+    # Reverting filter_eligible's pinned guard re-arms the shapepipe token loop.
     #
     # The exit handler routes through felt (LifecycleStore → FeltStores.resolve_
     # fiber), so the mock fiber must be felt-resolvable: point LOOM_HOMES at the
@@ -1115,10 +1129,12 @@ defmodule Shuttle.PollerTest do
     refute doc =~ ~r/status:\s*closed/
     refute doc =~ "closed-at"
 
-    # The loop: the next poll re-dispatches the still-active, no-longer-running
-    # role (a SECOND new-session for the same session name).
+    # No loop: the next poll does NOT re-dispatch the still-active, no-longer-
+    # running pinned role. The session count stays at 1 — the human must resume
+    # it explicitly. (Reverting the pinned guard flips this to a second launch.)
     send(poller, :run_poll_cycle)
-    assert wait_until(fn -> new_sessions.() == 2 end)
+    _ = Poller.snapshot(poller)
+    assert new_sessions.() == 1
   end
 
   test "a standing worker exit DOES close the role to awaiting-review (status:closed)" do