@cat-factory/app 0.275.0 → 0.276.0

package/app/composables/useFrameLanes.ts

@@ -0,0 +1,177 @@
+import { computed, type Ref } from 'vue'
+import { collectReviewDebt } from '@cat-factory/contracts'
+import type { Block } from '~/types/domain'
+import {
+  groupLaneTasks,
+  runActivityAt,
+  runWaitingSince,
+  sortLaneTasks,
+  type LaneGroup,
+  type LaneTaskEntry,
+} from '~/utils/laneSort'
+import {
+  classifyTask,
+  selectDoneLaneTasks,
+  TASK_LANES,
+  type DoneLaneSelection,
+  type TaskLane,
+} from '~/utils/swimlanes'
+
+/** One rendered lane: its identity, its groups, and the count its header states. */
+export interface RenderedLane {
+  readonly lane: TaskLane
+  readonly groups: LaneGroup[]
+  /** Every task classified into this lane, BEFORE the Done lane's caps. */
+  readonly total: number
+}
+
+/** A lane entry plus the lane it was classified into. */
+interface ClassifiedEntry {
+  readonly entry: LaneTaskEntry
+  readonly lane: TaskLane
+}
+
+/**
+ * Assemble a service frame's tasks into swimlanes.
+ *
+ * This is the store-facing half of the lane model: it resolves every input the pure
+ * `classifyTask` / `sortLaneTasks` / `groupLaneTasks` functions need and nothing more, so the
+ * classification and ordering rules stay testable without a Pinia instance. It also keeps the
+ * per-frame cost linear in the frame's tasks: every cross-block lookup below is a Map read off
+ * an index the stores already maintain, never a scan per task.
+ */
+export function useFrameLanes(frameId: Ref<string>) {
+  const board = useBoardStore()
+  const execution = useExecutionStore()
+  const agentRuns = useAgentRunsStore()
+  const notifications = useNotificationsStore()
+  const settings = useWorkspaceSettingsStore()
+  const laneView = useLaneViewStore()
+  const reviews = useReviewStage()
+
+  /** Tasks directly in the frame plus those inside its modules: a module renders no box now. */
+  const tasks = computed(() => board.allTasksUnder(frameId.value))
+
+  /** Module name → the module BLOCK that materialises it, so a group header can be a drop zone. */
+  const moduleBlockIdByName = computed(
+    () => new Map(board.modulesOf(frameId.value).map((m) => [m.title, m.id])),
+  )
+
+  /**
+   * Per-block "waiting since", derived once from the workspace's open review-wait cards by the
+   * same `collectReviewDebt` the backend's friction check uses. It is the fallback source for
+   * the park surfaces that stamp no `step.pausedAt`; deriving it once rather than per task is
+   * what keeps this assembly linear.
+   */
+  const waitingSinceByBlock = computed(
+    () => new Map(collectReviewDebt(notifications.open).map((d) => [d.blockId, d.waitingSince])),
+  )
+
+  /**
+   * The module a task belongs to: the module BLOCK's title when it already lives in one, else
+   * the module it DECLARES. The engine only materialises the block on merge
+   * (`applyModuleAssignment`), so keying on the parent alone would leave every unmerged task in
+   * "no module" while its own card names one.
+   */
+  function moduleNameOf(task: Block): string | null {
+    const parent = task.parentId ? board.getBlock(task.parentId) : undefined
+    if (parent?.level === 'module') return parent.title
+    return task.moduleName?.trim() || null
+  }
+
+  function classify(task: Block, order: number): ClassifiedEntry {
+    const run = execution.getByBlock(task.id) ?? null
+    const decisions = execution.decisionsByBlock.get(task.id) ?? []
+    const allApprovals = execution.approvalsByBlock.get(task.id) ?? []
+    // The same suppression the card and the frame badge apply: an iterative reviewer mid-cycle
+    // holds a pending approval while the driver folds answers in, and nobody is waiting on it.
+    const humanApprovals = allApprovals.filter((a) => !reviews.isBackground(a.agentKind, a.blockId))
+
+    const { lane, reason } = classifyTask({
+      status: task.status,
+      // Read from the coarse per-block summary, which also covers a bootstrap run.
+      runFailed: agentRuns.byBlock[task.id]?.status === 'failed',
+      run,
+      // A park is background exactly when everything asking was suppressed AND nothing else
+      // asks. With no approvals at all it is NOT background: it is a park on a surface this
+      // layer cannot name, which `classifyTask` reports as `parked` rather than as work.
+      parkIsBackground:
+        decisions.length === 0 &&
+        humanApprovals.length === 0 &&
+        allApprovals.length > humanApprovals.length,
+      pendingDecision: decisions.length > 0,
+      pendingApproval: humanApprovals.length > 0,
+      hasUnmetDeps: board.unmetDeps(task.id).length > 0,
+    })
+
+    return {
+      lane,
+      entry: {
+        task,
+        reason,
+        order,
+        activityAt: runActivityAt(run),
+        waitingSince: runWaitingSince(run, waitingSinceByBlock.value.get(task.id) ?? null),
+        moduleName: moduleNameOf(task),
+        initiativeName: task.initiativeId
+          ? (board.getBlock(task.initiativeId)?.title ?? null)
+          : null,
+        epicName: board.epicOf(task)?.title ?? null,
+      },
+    }
+  }
+
+  /** Every task bucketed by lane, in board order, before sorting. */
+  const byLane = computed(() => {
+    const buckets = new Map<TaskLane, LaneTaskEntry[]>(TASK_LANES.map((lane) => [lane, []]))
+    tasks.value.forEach((task, order) => {
+      const { lane, entry } = classify(task, order)
+      buckets.get(lane)!.push(entry)
+    })
+    return buckets
+  })
+
+  /**
+   * What the Done lane renders, and a full account of what it withheld.
+   *
+   * Computed even while the lane is collapsed, because the collapsed header states the TOTAL:
+   * "this service has finished 312 tasks" is the fact the lane exists to carry, and a header
+   * counting only what it happens to render would understate it by two orders of magnitude.
+   *
+   * `Date.now()` is read non-reactively, as `useReviewDebt` does. The cutoff is re-evaluated
+   * whenever the board, the runs or the settings change, which on a live board is constantly; a
+   * ticking clock purely so a card could vanish mid-session would be motion nobody asked for.
+   */
+  const doneSelection = computed<DoneLaneSelection>(() =>
+    selectDoneLaneTasks(
+      (byLane.value.get('done') ?? []).map((e) => e.task),
+      {
+        maxItems: settings.settings.doneLaneMaxItems,
+        retentionDays: settings.settings.doneLaneRetentionDays,
+      },
+      Date.now(),
+    ),
+  )
+
+  const lanes = computed<RenderedLane[]>(() =>
+    TASK_LANES.map((lane) => {
+      const bucket = byLane.value.get(lane) ?? []
+      // Only the Done lane is capped; every other lane renders everything in it.
+      const visible = lane === 'done' ? admittedByCaps(bucket, doneSelection.value) : bucket
+      const ordered = sortLaneTasks(visible, laneView.sortKey, lane)
+      return {
+        lane,
+        groups: groupLaneTasks(ordered, laneView.groupKey, moduleBlockIdByName.value),
+        total: bucket.length,
+      }
+    }),
+  )
+
+  return { lanes, doneSelection }
+}
+
+/** The entries whose task survived the Done lane's caps. */
+function admittedByCaps(entries: LaneTaskEntry[], selection: DoneLaneSelection): LaneTaskEntry[] {
+  const admitted = new Set(selection.shown.map((task) => task.id))
+  return entries.filter((e) => admitted.has(e.task.id))
+}

package/app/composables/useTaskExpansion.ts

@@ -75,7 +75,7 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
   //
   // Blocks with no pipeline to show are filtered out here rather than left to the card:
   // a frame, a module, or a task with no run expands to nothing, and granting it would
-  // still lift an empty card over its neighbours (see DraggableTask's z-index).
+  // still lift an empty card over its neighbours (see LaneTask's z-index).
   function hoveredTaskId(): string | null {
     if (!pointer) return null
     const hit = document.elementFromPoint(pointer.x, pointer.y)

package/app/stores/board/placement.ts

@@ -1,4 +1,5 @@
 import type { UpdateBlockInput } from '@cat-factory/contracts'
+import { moduleNameInContainer } from '@cat-factory/contracts'
 import { useServicesStore } from '~/stores/services'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { createBoardDependencies } from './dependencies'
@@ -59,9 +60,14 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     // block in the wrong container (a structural lie that survives until re-hydrate).
     const prevParentId = b.parentId
     const prevPosition = b.position
+    const prevModuleName = b.moduleName
     const name = b.title
     b.parentId = newParentId
     b.position = position
+    // The server re-stamps a moved task's declared module from its new container, so predict the
+    // same answer here: without it the card lands in the lane group it was dragged OUT of and
+    // jumps to the right one when the response arrives.
+    if (b.level === 'task') b.moduleName = moduleNameInContainer(parent)
     try {
       upsert(
         await api.reparentBlock(useWorkspaceStore().requireId(), id, {
@@ -90,6 +96,7 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     } catch (e) {
       b.parentId = prevParentId
       b.position = prevPosition
+      b.moduleName = prevModuleName
       // A cross-home drag can be refused on merge-preset grounds, which is a condition the mover
       // can act on rather than a fault. The backend sends the machine-readable reason and no
       // translated prose, so map it here; anything else keeps the raw message as the last resort.

package/app/stores/board.spec.ts

@@ -3,6 +3,8 @@ import { setActivePinia, createPinia } from 'pinia'
 import type { Block, BlockStatus } from '~/types/domain'
 import { useBoardStore } from '~/stores/board'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { EMPTY_FRAME_SIZE } from '~/utils/framePlacement'
+import { frameContentSize, laneBodyHeightIn, LANE_GEOMETRY } from '~/utils/laneGeometry'
 
 /** Minimal Block factory — only the fields the read getters care about. */
 function block(id: string, over: Partial<Block> = {}): Block {
@@ -27,6 +29,8 @@ const moduleBlock = (id: string, parentId: string, over: Partial<Block> = {}) =>
   block(id, { level: 'module', parentId, ...over })
 const task = (id: string, parentId: string, over: Partial<Block> = {}) =>
   block(id, { level: 'task', parentId, ...over })
+const initiativeBlock = (id: string, parentId: string, over: Partial<Block> = {}) =>
+  block(id, { level: 'initiative', parentId, ...over })
 
 describe('board store read getters', () => {
   let store: ReturnType<typeof useBoardStore>
@@ -212,29 +216,77 @@ describe('board store read getters', () => {
   })
 
   describe('containerSize', () => {
-    it('returns base dimensions for an empty service', () => {
+    // A frame's size is now a function of the LANE GEOMETRY, not of its contents. That is the
+    // point of the swimlanes: each lane scrolls, so a service accumulating work no longer grows
+    // a taller and taller frame until it dwarfs its neighbours. These tests pin the INVARIANT
+    // (size independent of task count and task position) rather than the pixel arithmetic, which
+    // belongs to `LANE_GEOMETRY` and would otherwise be restated here to no purpose.
+    it('sizes a service with nothing in it to the panel it actually renders', () => {
+      // An empty service shows one "add the first task" panel, not lanes, so it reserves the
+      // panel's footprint. Reserving the lanes' would leave the frame more than twice as tall as
+      // its own contents — and, since a placement clears frames by their reserved size, would
+      // push its neighbours that much further away for a frame holding nothing.
       store.hydrate([frame('f1')])
-      expect(store.containerSize('f1')).toEqual({ w: 360, h: 220 })
+      expect(store.containerSize('f1')).toEqual(
+        frameContentSize({ hasChildren: false, initiatives: 0 }),
+      )
     })
 
-    it('grows to fit a task and adds the module header height for modules', () => {
+    it('reserves the same footprint for a new frame that a new frame will render at', () => {
+      // The drift this caught: `EMPTY_FRAME_SIZE` is what a placement decision reserves BEFORE the
+      // block exists, so it cannot measure the frame and has to predict it. A hand-copied pair
+      // went stale when the floor changed underneath it, and every new service was then dropped
+      // on top of a neighbour it had been placed to clear.
+      store.hydrate([frame('f1')])
+      expect(store.containerSize('f1')).toEqual(EMPTY_FRAME_SIZE)
+    })
+
+    it('does not grow with task count, however many tasks and wherever they sat', () => {
+      store.hydrate([frame('f1'), task('t1', 'f1')])
+      const oneTask = store.containerSize('f1')
+
       store.hydrate([
         frame('f1'),
-        moduleBlock('m1', 'f1', { position: { x: 0, y: 0 } }),
+        moduleBlock('m1', 'f1', { position: { x: 400, y: 300 } }),
         task('t1', 'm1', { position: { x: 300, y: 200 } }),
+        // A position far outside the old content extent: it used to stretch the frame to reach
+        // it, and now means nothing at all, because a task no longer renders at coordinates.
+        task('t2', 'f1', { position: { x: 4000, y: 9000 } }),
       ])
-      // module inner width/height fit the task, plus the 30px module header.
-      const size = store.containerSize('m1')
-      expect(size.w).toBe(300 + 210 + 12)
-      expect(size.h).toBe(200 + 160 + 12 + 30)
+      expect(store.containerSize('f1')).toEqual(oneTask)
+    })
+
+    it('makes room for the initiative band above the lanes', () => {
+      // Initiatives are the one child still laid out by the frame itself (in a wrapping band),
+      // so they are the one thing the frame's height still has to account for.
+      store.hydrate([frame('f1'), task('t1', 'f1')])
+      const withoutBand = store.containerSize('f1').h
+      store.hydrate([frame('f1'), task('t1', 'f1'), initiativeBlock('i1', 'f1')])
+      expect(store.containerSize('f1').h).toBe(withoutBand + LANE_GEOMETRY.initiativeHeight)
+    })
+
+    it('sizes a frame holding only an initiative for lanes, since that is what it renders', () => {
+      // `BlockNode` gates the lanes on having ANY child — tasks, modules or initiatives — so a
+      // frame with an initiative and no tasks renders three (empty) lanes. A size that disagreed
+      // with what rendered is the clipping this geometry exists to prevent.
+      store.hydrate([frame('f1'), initiativeBlock('i1', 'f1')])
+      expect(store.containerSize('f1')).toEqual(
+        frameContentSize({ hasChildren: true, initiatives: 1 }),
+      )
     })
 
-    it('expands a service to enclose its nested modules', () => {
-      store.hydrate([frame('f1'), moduleBlock('m1', 'f1', { position: { x: 400, y: 300 } })])
-      const mod = store.containerSize('m1')
-      const svc = store.containerSize('f1')
-      expect(svc.w).toBe(400 + mod.w + 12)
-      expect(svc.h).toBe(300 + mod.h + 12)
+    it('a module reports no canvas of its own, since it is no longer drawn as a box', () => {
+      store.hydrate([frame('f1'), moduleBlock('m1', 'f1'), task('t1', 'm1')])
+      expect(store.containerSize('m1').h).toBe(0)
+    })
+
+    it('keeps an explicitly resized frame at the size the user dragged it to', () => {
+      // The geometry is a FLOOR, not a fixed size: dragging the border still gives a reader more
+      // room, and a lane grows its scroll viewport into it rather than leaving dead canvas below.
+      store.hydrate([frame('f1', { size: { w: 2000, h: 1500 } }), task('t1', 'f1')])
+      const size = store.containerSize('f1')
+      expect(size).toEqual({ w: 2000, h: 1500 })
+      expect(laneBodyHeightIn(size, 0)).toBeGreaterThan(LANE_GEOMETRY.laneBodyHeight)
     })
   })
 
@@ -422,6 +474,59 @@ describe('board store optimistic rollback', () => {
     // the undo move is itself non-undoable, so no second toast is queued
     expect(actions).toHaveLength(1)
   })
+
+  it('reparentBlock predicts the declared module the server will re-stamp', async () => {
+    // The board reads a task's PARENT for its module and falls back to the name it DECLARES (a
+    // task can name a module before the engine materialises the block on merge). So a card
+    // dragged out of a module and left still declaring it re-groups under the module it was just
+    // dragged out of. The server re-stamps the name on every reparent; the optimistic write here
+    // has to predict the same answer or the card visibly jumps when the response lands.
+    //
+    // The request never settles, so what is asserted is strictly what this store put on screen
+    // BEFORE hearing back — the window the card would otherwise spend in the wrong group.
+    vi.stubGlobal('useApi', () => ({ reparentBlock: () => new Promise(() => {}) }))
+    vi.stubGlobal('useToast', () => ({ add: () => {} }))
+    setActivePinia(createPinia())
+    useWorkspaceStore().workspaceId = 'ws1'
+    const store = useBoardStore()
+    store.hydrate([
+      frame('f1'),
+      moduleBlock('m1', 'f1', { title: 'Sessions' }),
+      task('t1', 'm1', { moduleName: 'Sessions' }),
+      task('t2', 'f1'),
+    ])
+
+    // Out to the service frame: the declared name goes with it, as the empty string the store
+    // maps to NULL. Left behind, it is what files the card straight back into "Sessions".
+    void store.reparentBlock('t1', 'f1', { x: 0, y: 0 })
+    expect(store.getBlock('t1')?.moduleName).toBe('')
+
+    // And in: the destination module's title, whatever the task declared before.
+    void store.reparentBlock('t2', 'm1', { x: 0, y: 0 })
+    expect(store.getBlock('t2')?.moduleName).toBe('Sessions')
+  })
+
+  it('reparentBlock restores the declared module when the move is rejected', async () => {
+    // The same rollback contract the parent and position already had: a refused move must not
+    // leave the card grouped somewhere the server never put it.
+    vi.stubGlobal('useApi', () => ({
+      reparentBlock: async () => {
+        throw new Error('nope')
+      },
+    }))
+    vi.stubGlobal('useToast', () => ({ add: () => {} }))
+    setActivePinia(createPinia())
+    useWorkspaceStore().workspaceId = 'ws1'
+    const store = useBoardStore()
+    store.hydrate([
+      frame('f1'),
+      moduleBlock('m1', 'f1', { title: 'Sessions' }),
+      task('t1', 'm1', { moduleName: 'Sessions' }),
+    ])
+
+    await store.reparentBlock('t1', 'f1', { x: 0, y: 0 })
+    expect(store.getBlock('t1')).toMatchObject({ parentId: 'm1', moduleName: 'Sessions' })
+  })
 })
 
 describe('board store deferred delete + undo', () => {

package/app/stores/laneView.spec.ts

@@ -0,0 +1,61 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import { useLaneViewStore } from '~/stores/laneView'
+
+// The preference is PERSISTED in the reader's browser, which makes the restored value
+// untrusted input: a blob written by an older build can name a sort key this build has
+// retired, and feeding that to the comparator lookup would throw mid-sort and take the whole
+// board down over a stale preference. That narrowing is the thing worth pinning here.
+
+describe('laneView store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('defaults to the per-lane smart order with no grouping', () => {
+    const store = useLaneViewStore()
+    expect(store.sortKey).toBe('smart')
+    expect(store.groupKey).toBe('none')
+    expect(store.hasOverride).toBe(false)
+  })
+
+  it('opens with the Done lane collapsed', () => {
+    // A service with a long history would otherwise open as a wall of merged cards.
+    expect(useLaneViewStore().doneLaneCollapsed).toBe(true)
+  })
+
+  it('falls back to the default when a restored key is not in this build vocabulary', () => {
+    const store = useLaneViewStore()
+    // Exactly what a persisted blob from an older build looks like.
+    store.storedSortKey = 'sort_by_vibes'
+    store.storedGroupKey = 'group_by_astrology'
+    expect(store.sortKey).toBe('smart')
+    expect(store.groupKey).toBe('none')
+    // …and a stale value must not read as an override, or the board would claim a preference
+    // it is not actually applying.
+    expect(store.hasOverride).toBe(false)
+  })
+
+  it('reports an override so the control survives a switch to basic mode', () => {
+    const store = useLaneViewStore()
+    store.setSortKey('severity_desc')
+    expect(store.hasOverride).toBe(true)
+    store.reset()
+    expect(store.hasOverride).toBe(false)
+    expect(store.sortKey).toBe('smart')
+  })
+
+  it('treats grouping alone as an override', () => {
+    const store = useLaneViewStore()
+    store.setGroupKey('module')
+    expect(store.hasOverride).toBe(true)
+  })
+
+  it('toggles the Done lane', () => {
+    const store = useLaneViewStore()
+    store.toggleDoneLane()
+    expect(store.doneLaneCollapsed).toBe(false)
+    store.toggleDoneLane()
+    expect(store.doneLaneCollapsed).toBe(true)
+  })
+})

package/app/stores/laneView.ts

@@ -0,0 +1,85 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import {
+  isLaneGroupKey,
+  isLaneSortKey,
+  type LaneGroupKey,
+  type LaneSortKey,
+} from '~/utils/laneSort'
+
+/**
+ * How this reader wants a frame's swimlanes ordered and grouped, plus whether the Done lane
+ * is open.
+ *
+ * Per USER and per BROWSER, persisted like the interface tier and the agent tier. That is a
+ * deliberate split from the Done lane's two CAPS, which are per-workspace settings: what the
+ * board may show is a shared decision about a service's history, while the order a reader
+ * scans it in is personal and changes several times an hour. Making the order shared would
+ * mean one person's triage sweep re-arranging everyone else's board.
+ *
+ * `sortKey` defaults to `smart`, which is per-lane (see `SMART_ORDER_BY_LANE`) rather than one
+ * global order — the actionable order genuinely differs by column. The explicit keys are an
+ * OVERRIDE of that, which is why the control offering them is an advanced-tier affordance:
+ * hiding it in basic mode leaves exactly the default it would have shown.
+ */
+export const useLaneViewStore = defineStore(
+  'laneView',
+  () => {
+    // Stored raw and narrowed on read, the same split `uiMode` uses for `storedMode`. A setup
+    // store can only persist what it returns, so these are reachable directly; the narrowing
+    // below is what makes that safe rather than a trust assumption.
+    const storedSortKey = ref<string>('smart')
+    const storedGroupKey = ref<string>('none')
+    /**
+     * Collapsed by default. The lane's job is to prove finished work exists and give a route
+     * to it, and a service with a long history would otherwise open as a wall of merged
+     * cards nobody asked to read.
+     */
+    const doneLaneCollapsed = ref(true)
+
+    const sortKey = computed<LaneSortKey>(() =>
+      isLaneSortKey(storedSortKey.value) ? storedSortKey.value : 'smart',
+    )
+    const groupKey = computed<LaneGroupKey>(() =>
+      isLaneGroupKey(storedGroupKey.value) ? storedGroupKey.value : 'none',
+    )
+
+    /**
+     * Whether the reader has overridden the defaults. Drives `showOverrideField`, so a
+     * preference set in advanced mode stays visible (and clearable) after a switch to basic
+     * — the one case where hiding an override would conceal a setting the board is using.
+     */
+    const hasOverride = computed(() => sortKey.value !== 'smart' || groupKey.value !== 'none')
+
+    function setSortKey(next: LaneSortKey) {
+      storedSortKey.value = next
+    }
+
+    function setGroupKey(next: LaneGroupKey) {
+      storedGroupKey.value = next
+    }
+
+    function reset() {
+      storedSortKey.value = 'smart'
+      storedGroupKey.value = 'none'
+    }
+
+    function toggleDoneLane() {
+      doneLaneCollapsed.value = !doneLaneCollapsed.value
+    }
+
+    return {
+      storedSortKey,
+      storedGroupKey,
+      doneLaneCollapsed,
+      sortKey,
+      groupKey,
+      hasOverride,
+      setSortKey,
+      setGroupKey,
+      reset,
+      toggleDoneLane,
+    }
+  },
+  { persist: { pick: ['storedSortKey', 'storedGroupKey', 'doneLaneCollapsed'] } },
+)

package/app/stores/taskExpansion.spec.ts

@@ -4,7 +4,7 @@ import { useUiStore } from '~/stores/ui'
 
 /**
  * The expansion gate combines two independent grants (hover at any zoom, the deep zoom
- * bands otherwise). Both `TaskPipelineMini` (what renders) and `DraggableTask` (what
+ * bands otherwise). Both `TaskPipelineMini` (what renders) and `LaneTask` (what
  * stacks on top) read `isExpanded`, so these cases pin the rule they share.
  *
  * Zoom is set through the ui store's raw `zoom`, the same value the board canvas writes;

package/app/stores/taskExpansion.ts

@@ -8,7 +8,7 @@ import { useUiStore } from '~/stores/ui'
  *
  * Two independent grants, both written every frame by the board driver
  * (`useTaskExpansion`) and combined HERE so the render (`TaskPipelineMini`) and the
- * stacking (`DraggableTask`) can never disagree about which cards are expanded:
+ * stacking (`LaneTask`) can never disagree about which cards are expanded:
  *
  *  - HOVER — the card under the pointer expands at ANY zoom level. Pointing at a task
  *    is asking what it is doing right now, and that answer used to be reachable only

package/app/stores/workspaceSettings.ts

@@ -12,6 +12,10 @@ const DEFAULTS: WorkspaceSettings = {
   storeAgentContext: true,
   publishPrVerificationReport: true,
   artifactRetentionDays: 14,
+  // The board's Done swimlane keeps two weeks and 20 cards. Both cap what is RENDERED; a
+  // task aged out of the lane is still on the board's data and still counted in its total.
+  doneLaneMaxItems: 20,
+  doneLaneRetentionDays: 14,
   kaizenEnabled: true,
   delegateAgentsToRunnerPool: false,
   inputGateMode: 'standard',

package/app/utils/framePlacement.ts

@@ -8,6 +8,7 @@
  * nodes in. Sizes are the frame's rendered pixel footprint (see
  * {@link useBlockQueries.containerSize}).
  */
+import { frameContentSize } from '~/utils/laneGeometry'
 
 export interface Point {
   x: number
@@ -23,11 +24,15 @@ export interface FrameRect extends Point {
 export const FRAME_GAP = 48
 
 /**
- * Footprint of a freshly-added, empty service frame in flow-space. Mirrors the
- * empty-frame floor in {@link useBlockQueries.contentSize} (w 360, inner h 220) so a
- * placement decision made BEFORE the block exists matches how it will actually render.
+ * Footprint of a freshly-added, empty service frame in flow-space.
+ *
+ * DERIVED from the lane geometry rather than restated, because a placement decision is made
+ * BEFORE the block exists and so cannot measure it: the numbers here and the ones the frame
+ * renders at have to be the same numbers, or a new service is dropped on top of a neighbour it
+ * was placed to clear. A hand-copied pair went stale exactly that way when the frame's floor
+ * changed underneath it.
  */
-export const EMPTY_FRAME_SIZE = { w: 360, h: 220 }
+export const EMPTY_FRAME_SIZE = frameContentSize({ hasChildren: false, initiatives: 0 })
 
 /**
  * Footprint of an epic grouping node in flow-space. Epics are top-level board nodes

package/app/utils/laneGeometry.spec.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest'
+import { frameContentSize, laneBodyHeightIn, LANE_GEOMETRY } from './laneGeometry'
+
+/**
+ * These pin the RELATION between the two derivations, not their pixel arithmetic. The numbers are
+ * `LANE_GEOMETRY`'s to change; what must never change is that a frame sized by one of them hands
+ * the other back exactly what it reserved, because that is the agreement three consumers depend on
+ * (the frame's floor, what `FrameSwimlanes` renders into, and the spot placement reserves for a
+ * frame that does not exist yet).
+ */
+describe('frameContentSize', () => {
+  it('sizes a service with nothing in it to its "add the first task" panel, not to lanes', () => {
+    // An empty service renders no lanes at all, so reserving lane-sized space for it would leave
+    // the frame more than twice as tall as the one thing inside it — and push its neighbours that
+    // much further away, since placement clears frames by their reserved footprint.
+    const empty = frameContentSize({ hasChildren: false, initiatives: 0 })
+    expect(empty).toEqual({
+      w: LANE_GEOMETRY.emptyFrameWidth,
+      h: LANE_GEOMETRY.emptyFrameHeight,
+    })
+    expect(empty.h).toBeLessThan(frameContentSize({ hasChildren: true, initiatives: 0 }).h)
+  })
+
+  it('does not grow with anything except the initiative band', () => {
+    // The whole point of the lanes: a lane scrolls rather than growing, so nothing about a
+    // service's task count reaches this function. Initiatives are the one child the frame still
+    // lays out itself, so they are the one thing its height still answers to.
+    const base = frameContentSize({ hasChildren: true, initiatives: 0 })
+    expect(frameContentSize({ hasChildren: true, initiatives: 1 })).toEqual({
+      w: base.w,
+      h: base.h + LANE_GEOMETRY.initiativeHeight,
+    })
+    // A second row only once the first is full, whatever that width happens to allow.
+    const perRow = Math.floor(LANE_GEOMETRY.canvasWidth / LANE_GEOMETRY.initiativeWidth)
+    expect(frameContentSize({ hasChildren: true, initiatives: perRow }).h).toBe(
+      base.h + LANE_GEOMETRY.initiativeHeight,
+    )
+    expect(frameContentSize({ hasChildren: true, initiatives: perRow + 1 }).h).toBe(
+      base.h + 2 * LANE_GEOMETRY.initiativeHeight,
+    )
+  })
+})
+
+describe('laneBodyHeightIn', () => {
+  it('hands a frame at its floor size exactly the lane body that floor was computed from', () => {
+    // The round trip that keeps the lanes from being clipped by their own frame. Asserted for a
+    // frame with an initiative band too, since the band is the term the two have to agree about.
+    for (const initiatives of [0, 1, 5]) {
+      const floor = frameContentSize({ hasChildren: true, initiatives })
+      expect(laneBodyHeightIn(floor, initiatives)).toBe(LANE_GEOMETRY.laneBodyHeight)
+    }
+  })
+
+  it('gives a dragged-taller frame the whole extra height', () => {
+    // The contract `LANE_GEOMETRY` states and `containerSize` implements: the geometry is a FLOOR,
+    // and a reader who wants more room drags the border. The lanes kept a constant height before
+    // this, so the extra space was dead canvas below them and the gesture appeared to do nothing.
+    const floor = frameContentSize({ hasChildren: true, initiatives: 0 })
+    const dragged = { w: floor.w, h: floor.h + 300 }
+    expect(laneBodyHeightIn(dragged, 0)).toBe(LANE_GEOMETRY.laneBodyHeight + 300)
+  })
+
+  it('never returns less than the floor lane body, whatever it is handed', () => {
+    // A frame cannot be dragged below its floor, so this is only reachable by a caller measuring
+    // one mid-layout; collapsing a lane to nothing (or a negative height) is never the answer.
+    expect(laneBodyHeightIn({ w: 100, h: 0 }, 0)).toBe(LANE_GEOMETRY.laneBodyHeight)
+    expect(laneBodyHeightIn({ w: 100, h: 40 }, 12)).toBe(LANE_GEOMETRY.laneBodyHeight)
+  })
+})