{/* Error banner — kept from the previous shell */}
{error && (
diff --git a/src/types/index.ts b/src/types/index.ts
index ce18189..2874e84 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -104,6 +104,13 @@ export interface ProjectEntry {
* the backend `skip_serializing_if`s it when false.
*/
autonomous?: boolean;
+ /**
+ * Pinned to the rail (`prd-rail-corridor-shell` Phase 1): past 5 registered
+ * projects, only pinned projects (plus a fixed overflow door) show in the
+ * 72px rail. Per-machine, not synced. Optional on the wire because the
+ * backend `skip_serializing_if`s it when false.
+ */
+ pinned?: boolean;
/**
* Total `## Next Steps` checklist items parsed from `.loopdeck/loops.md`,
* refreshed on every `list_projects` call. Ephemeral — not persisted when
diff --git a/tests/frontend/rail.test.mjs b/tests/frontend/rail.test.mjs
new file mode 100644
index 0000000..724b9ba
--- /dev/null
+++ b/tests/frontend/rail.test.mjs
@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+ doorInitials,
+ sortByLastActive,
+ selectRailDoors,
+ hasActiveOrQueuedRun,
+ RAIL_DOOR_LIMIT,
+} from "../../src/lib/rail.ts";
+
+function project(overrides = {}) {
+ return {
+ path: "/tmp/x",
+ name: "x",
+ description: "",
+ status: "active",
+ last_opened: null,
+ created_at: "2026-01-01T00:00:00Z",
+ last_commit_date: null,
+ last_commit_message: null,
+ last_modified: null,
+ uncommitted: { files: 0, added: 0, deleted: 0 },
+ run_state: "idle",
+ pinned: false,
+ next_steps_total: 0,
+ next_steps_done: 0,
+ ...overrides,
+ };
+}
+
+test("doorInitials takes the first 2 chars, uppercased", () => {
+ assert.equal(doorInitials("loopdeck"), "LO");
+ assert.equal(doorInitials("my-cool-app"), "MY");
+ assert.equal(doorInitials("a"), "A");
+});
+
+test("sortByLastActive orders most recently opened first, never-opened last", () => {
+ const older = project({ path: "/a", last_opened: "2026-01-01T00:00:00Z" });
+ const newer = project({ path: "/b", last_opened: "2026-02-01T00:00:00Z" });
+ const never = project({ path: "/c", last_opened: null });
+ const sorted = sortByLastActive([older, never, newer]);
+ assert.deepEqual(
+ sorted.map((p) => p.path),
+ ["/b", "/a", "/c"],
+ );
+});
+
+test("selectRailDoors shows every project with no overflow at or under the limit", () => {
+ const projects = Array.from({ length: RAIL_DOOR_LIMIT }, (_, i) => project({ path: `/p${i}` }));
+ const { doors, overflow } = selectRailDoors(projects);
+ assert.equal(doors.length, RAIL_DOOR_LIMIT);
+ assert.equal(overflow, false);
+});
+
+test("selectRailDoors falls back to the 5 most recently active when nobody has pinned yet", () => {
+ const projects = Array.from({ length: RAIL_DOOR_LIMIT + 3 }, (_, i) =>
+ project({ path: `/p${i}`, last_opened: `2026-01-${String(i + 1).padStart(2, "0")}T00:00:00Z` }),
+ );
+ const { doors, overflow } = selectRailDoors(projects);
+ assert.equal(overflow, true);
+ assert.equal(doors.length, RAIL_DOOR_LIMIT);
+ // Most recent 5 = the last 5 pushed (highest day-of-month).
+ assert.deepEqual(
+ doors.map((p) => p.path),
+ ["/p7", "/p6", "/p5", "/p4", "/p3"],
+ );
+});
+
+test("selectRailDoors shows pinned-only plus overflow once pins exist", () => {
+ const projects = Array.from({ length: RAIL_DOOR_LIMIT + 3 }, (_, i) => project({ path: `/p${i}` }));
+ projects[0].pinned = true;
+ projects[2].pinned = true;
+ const { doors, overflow } = selectRailDoors(projects);
+ assert.equal(overflow, true);
+ assert.deepEqual(
+ doors.map((p) => p.path).sort(),
+ ["/p0", "/p2"],
+ );
+});
+
+test("hasActiveOrQueuedRun is false with no plan", () => {
+ assert.equal(hasActiveOrQueuedRun(undefined), false);
+ assert.equal(hasActiveOrQueuedRun({ plan: null, active: false }), false);
+});
+
+test("hasActiveOrQueuedRun is true when active or a phase is queued/running", () => {
+ assert.equal(hasActiveOrQueuedRun({ plan: null, active: true }), true);
+ assert.equal(
+ hasActiveOrQueuedRun({
+ plan: { phases: [{ status: "completed" }, { status: "queued" }] },
+ active: false,
+ }),
+ true,
+ );
+ assert.equal(
+ hasActiveOrQueuedRun({
+ plan: { phases: [{ status: "completed" }, { status: "failed" }] },
+ active: false,
+ }),
+ false,
+ );
+});