@veewo/dsh-better-tasks 0.0.0-stage → 0.4.4

package/src/final-message.mjs

@@ -0,0 +1,75 @@
+import { buildSessionEventRecords } from '@deepseek-ai/dsh-session-query'
+
+export const FINAL_MESSAGE_MAX_CODE_POINTS = 4000
+
+function codePoints(value) {
+  return [...value]
+}
+
+export function deriveFinalAssistantPreview(events, records, limit = FINAL_MESSAGE_MAX_CODE_POINTS) {
+  if (!Array.isArray(events) || !Array.isArray(records) || events.length !== records.length) {
+    throw new TypeError('events and records must be equal-length arrays')
+  }
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new TypeError('limit must be a positive safe integer')
+
+  const endedTurns = new Map()
+  for (const event of events) {
+    if (event?.type === 'turn/end') endedTurns.set(event.data.turn, event.data.reason)
+  }
+  const asOfSeq = events.length === 0 ? null : Number(events.at(-1).seq)
+
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]
+    if (event?.type !== 'assistant/message' || records[index]?.surface !== 'current') continue
+    const endReason = endedTurns.get(event.data.turn)
+    if (endReason === undefined) continue
+    const blocks = Array.isArray(event.data.message?.content) ? event.data.message.content : []
+    const text = blocks
+      .filter((block) => block?.type === 'text' && typeof block.text === 'string' && block.text.trim() !== '')
+      .map((block) => block.text)
+      .join('\n')
+    if (text === '') continue
+    const points = codePoints(text)
+    return {
+      asOfSeq,
+      final: {
+        seq: Number(event.seq),
+        turn: event.data.turn,
+        text: points.slice(0, limit).join(''),
+        interrupted: event.data.interrupted === true,
+        endReason,
+      },
+      truncated: points.length > limit,
+      totalCodePoints: points.length,
+    }
+  }
+
+  return { asOfSeq, final: null, truncated: false, totalCodePoints: 0 }
+}
+
+function sendJson(res, status, value) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(value))
+}
+
+export function createFinalMessageHttpHandler({ isPinned, readSession, buildRecords = buildSessionEventRecords }) {
+  return async (req, res) => {
+    if (req.method !== 'GET') return sendJson(res, 405, { code: 'method-not-allowed' })
+    const sessionId = new URL(req.url ?? '/', 'http://localhost').searchParams.get('sessionId')?.trim()
+    if (!sessionId || !isPinned(sessionId)) {
+      return sendJson(res, 404, { code: 'better-tasks/final-session-not-pinned', message: 'session is not pinned' })
+    }
+    try {
+      const snapshot = await readSession(sessionId)
+      const records = buildRecords(sessionId, snapshot.events)
+      return sendJson(res, 200, { sessionId, ...deriveFinalAssistantPreview(snapshot.events, records) })
+    } catch (error) {
+      return sendJson(res, 500, {
+        code: 'better-tasks/final-read-failed',
+        message: String(error?.message ?? error),
+      })
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,222 @@
+import { Buffer } from 'node:buffer'
+import { z } from 'zod'
+import Schema from '@deepseek-ai/schemastery'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import {
+  PIN_QUEUE_SCHEMA_VERSION,
+  PinQueueError,
+  publicPinQueue,
+} from './pin-model.mjs'
+import { installProjectAppearance } from './project-appearance.mjs'
+import { createFinalMessageHttpHandler } from './final-message.mjs'
+import { createNativePinHost, taskFirstWorkAt } from './native-pin-host.mjs'
+import { createTaskExecutionProjection } from './task-execution.mjs'
+
+export const name = 'dsh-better-tasks'
+export const inject = ['storageDomain', 'sessionController', 'sessionQuery', 'workspaceRegistry', 'webServer']
+export const TASK_SETTINGS_NAMESPACE = 'better-tasks-ui'
+export const TASK_SETTINGS_DEFAULTS = Object.freeze({
+  detailFontSize: 13,
+  defaultTodoExpanded: false,
+  defaultGoalExpanded: false,
+  defaultFinalExpanded: true,
+  defaultInputExpanded: false,
+  columnLayout: 'auto',
+  titleEmphasis: 'task',
+  sidebarView: 'native',
+})
+export const TaskSettingsSchema = Schema.object({
+  // 0.2 exposes only volatile Config fields through settings.describe/forms.
+  // Its .volatile() is exactly .extra('volatile', true); use that public metadata
+  // API so the retained 0.1.5 build-time Schemastery can parse the same schema.
+  detailFontSize: Schema.number().step(1).min(11).max(16).default(13).extra('volatile', true),
+  defaultTodoExpanded: Schema.boolean().default(false).extra('volatile', true),
+  defaultGoalExpanded: Schema.boolean().default(false).extra('volatile', true),
+  defaultFinalExpanded: Schema.boolean().default(true).extra('volatile', true),
+  defaultInputExpanded: Schema.boolean().default(false).extra('volatile', true),
+  columnLayout: Schema.union(['auto', 'single', 'double']).default('auto').extra('volatile', true),
+  titleEmphasis: Schema.union(['project', 'task']).default('task').extra('volatile', true),
+  // D1: the sidebar body the browser shows. Host-persisted, so both generations
+  // read and write it through the same Config path.
+  sidebarView: Schema.union(['native', 'tasks']).default('native').extra('volatile', true),
+})
+
+/**
+ * The plugin's own Config schema.
+ *
+ * 0.2 derives both the settings form and the persistence namespace from a plugin's
+ * entry: the namespace is the loader entry id and the fields are this schema's
+ * keys, so the seven preference fields have to live here. The 0.1.5 runtime entry
+ * point `settings.register(namespace, schema)` does not exist in 0.2 — calling it
+ * threw inside a non-blocking inject callback, which is exactly why preferences
+ * never persisted and nothing reported itself as broken.
+ *
+ * {@link TASK_SETTINGS_NAMESPACE} is therefore both the 0.1.5 namespace and the
+ * required 0.2 row id: under the same name the values 0.1.5 wrote are read in
+ * place and a rollback loses nothing, so no copy migration is needed. A row named
+ * anything else starts at these defaults and leaves the legacy key untouched.
+ */
+export const Config = TaskSettingsSchema
+
+const pinQueueRecord = z.object({
+  schemaVersion: z.literal(PIN_QUEUE_SCHEMA_VERSION),
+  revision: z.number().int().nonnegative(),
+  sessionIds: z.array(z.string().min(1)).refine((items) => new Set(items).size === items.length, 'sessionIds must be unique'),
+  updatedAt: z.string().min(1),
+})
+
+export const pinQueueDomain = defineDomain({
+  name: 'better_tasks_pin_queue',
+  version: 1,
+  tables: { queues: domainTable(pinQueueRecord) },
+})
+
+// A new unit, not a field/table extension of the rollback-readable legacy queue.
+export const nativePinOrderDomain = defineDomain({
+  name: 'better_tasks_native_order', version: 1,
+  tables: { state: domainTable(pinQueueRecord.extend({
+    // Absent on older auto-seeded records; only an explicit drag writes this.
+    manualSessionIds: z.array(z.string().min(1)).refine((ids) => new Set(ids).size === ids.length).optional(),
+    manualOrderAt: z.number().int().nonnegative().optional(),
+    // Task admission time may differ from an older/reused Session header.
+    taskCreatedAtBySession: z.record(z.string().min(1), z.number().int().nonnegative()).optional(),
+    taskFirstWorkAtBySession: z.record(z.string().min(1), z.number().int().nonnegative()).optional(),
+    migration: z.object({
+      status: z.enum(['running', 'done', 'partial']),
+      sourceRevision: z.number().int().nonnegative().nullable(),
+      entries: z.array(z.object({
+        sessionId: z.string().min(1),
+        status: z.enum(['pending', 'attempted', 'imported', 'skipped', 'failed', 'uncertain']),
+        detail: z.string().optional(),
+      })),
+    }),
+  })) },
+})
+
+function sendJson(res, status, value) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(value))
+}
+
+async function readJson(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > 64 * 1024) throw new PinQueueError('better-tasks/request-too-large', 'request body exceeds 64 KiB')
+    chunks.push(chunk)
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  } catch {
+    throw new PinQueueError('better-tasks/invalid-json', 'request body must be valid JSON')
+  }
+}
+
+function errorStatus(error) {
+  if (error?.code === 'better-tasks/revision-conflict') return 409
+  if (error?.code === 'better-tasks/session-not-eligible') return 404
+  if (error?.code === 'better-tasks/request-too-large') return 413
+  if (typeof error?.code === 'string' && error.code.startsWith('better-tasks/')) return 400
+  return 500
+}
+
+export function createPinQueueHttpHandler({ current, eligibleSessionIds, retainedSessionIds = eligibleSessionIds, mutate, prune }) {
+  return async (req, res) => {
+    try {
+      if (req.method === 'GET') {
+        const retained = await retainedSessionIds()
+        return sendJson(res, 200, { queue: publicPinQueue(await prune(retained)) })
+      }
+      if (req.method !== 'POST') return sendJson(res, 405, { code: 'method-not-allowed' })
+      const input = await readJson(req)
+      if (input?.action === 'pin' || input?.action === 'pin-created') {
+        const eligible = input.action === 'pin-created' ? await retainedSessionIds() : await eligibleSessionIds()
+        if (!eligible.has(input.sessionId)) {
+          throw new PinQueueError('better-tasks/session-not-eligible', `session is not eligible for pinning: ${String(input.sessionId)}`)
+        }
+      }
+      const queue = await mutate(input)
+      return sendJson(res, 200, { queue: publicPinQueue(queue) })
+    } catch (error) {
+      const code = typeof error?.code === 'string' ? error.code : 'better-tasks/write-failed'
+      return sendJson(res, errorStatus(error), {
+        code,
+        message: String(error?.message ?? error),
+        ...(error?.details === undefined ? {} : { details: error.details }),
+        ...(code === 'better-tasks/revision-conflict' ? { queue: publicPinQueue(current()) } : {}),
+      })
+    }
+  }
+}
+
+export function createNativePinHttpHandler(controller) {
+  return async (req, res) => {
+    try {
+      if (req.method === 'GET') return sendJson(res, 200, controller.read())
+      if (req.method !== 'POST') return sendJson(res, 405, { code: 'method-not-allowed' })
+      return sendJson(res, 200, await controller.mutate(await readJson(req)))
+    } catch (error) {
+      const status = error?.status ?? (error?.name === 'WorkspaceUnknownSessionError' ? 404 : error?.name === 'WorkspaceArchivedSessionPinError' ? 400 : errorStatus(error))
+      return sendJson(res, status, { ...controller.current(), code: error?.code ?? 'better-tasks/write-failed', message: String(error?.message ?? error) })
+    }
+  }
+}
+
+export async function apply(ctx) {
+  // Optional projection capability must never hold core-shell activation.
+  ctx.inject(['sessionProjections'], (projectionCtx) => {
+    projectionCtx.sessionProjections.register(createTaskExecutionProjection(z))
+  })
+  ctx.inject(['settings'], (settingsCtx) => {
+    // 0.1.5: the Host settings service accepted a runtime namespace registration.
+    if (typeof settingsCtx.settings.register === 'function') {
+      settingsCtx.settings.register(TASK_SETTINGS_NAMESPACE, TaskSettingsSchema)
+      return
+    }
+    // 0.2: the schema comes from `Config` above, so the only thing left to declare
+    // is the instance-level UI policy, attributed to this plugin's fiber.
+    if (typeof settingsCtx.settings.configure === 'function') {
+      settingsCtx.effect(
+        () => settingsCtx.settings.configure({ auto: false }, ctx.fiber),
+        'dsh-better-tasks: settings presentation',
+      )
+    }
+  })
+  await installProjectAppearance(ctx)
+  // No migration/storage wait in plugin startup. Native controls are independent
+  // of this optional ordering feature; the first feature request starts its work.
+  const open = async (spec, tableName) => {
+    const domain = await ctx.storageDomain.open(spec)
+    return { table: domain.table(tableName), close: () => domain.close() }
+  }
+  const controller = createNativePinHost({
+    registry: ctx.workspaceRegistry,
+    listSessions: (signal) => ctx.sessionQuery.listSessions(signal),
+    readTaskStartedAt: async (header, signal) => typeof ctx.sessionQuery.listEvents === 'function'
+      ? taskFirstWorkAt(await ctx.sessionQuery.listEvents(header.id, signal)) : undefined,
+    openOrder: () => open(nativePinOrderDomain, 'state'),
+    openLegacy: () => open(pinQueueDomain, 'queues'),
+    subscribe: listener => ctx.on('domain/changed', listener),
+  })
+  const handler = createNativePinHttpHandler(controller)
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/api/better-tasks/pins',
+    handler,
+  }), 'dsh-better-tasks.pin-http')
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/api/better-tasks/final-message',
+    handler: createFinalMessageHttpHandler({
+      isPinned: (sessionId) => ctx.workspaceRegistry.pinnedSessionIds.includes(String(sessionId)),
+      readSession: (sessionId) => ctx.sessionQuery.readSession(sessionId),
+    }),
+  }), 'dsh-better-tasks.final-message-http')
+  ctx.effect(() => async () => {
+    await controller.dispose()
+  }, 'dsh-better-tasks.native-pin-controller-close')
+}

package/src/native-pin-host.mjs

@@ -0,0 +1,309 @@
+// Official Workspace pins own membership. This controller owns rank and a sealed,
+// at-most-once legacy import journal only; it never compensates native operations.
+const NATIVE_ORDER_KEY = 'global'
+const sameIds = (a, b) => a.length === b.length && a.every((id, index) => id === b[index])
+const ownedIds = value => {
+  if (!Array.isArray(value) || value.some(id => typeof id !== 'string' || id === '') || new Set(value).size !== value.length) throw new Error('Invalid native pin/order identities')
+  return [...value]
+}
+const projectIds = (rank, pins) => {
+  const pinned = new Set(pins), ranked = new Set(rank)
+  return [...rank.filter(id => pinned.has(id)), ...pins.filter(id => !ranked.has(id))]
+}
+const messageOf = error => String(error?.message ?? error).slice(0, 1000)
+const changedIds = (a, b) => {
+  const before = new Set(a), after = new Set(b)
+  return [...a.filter(id => !after.has(id)), ...b.filter(id => !before.has(id))]
+}
+export class NativePinError extends Error {
+  constructor(code, message, status = 400) { super(message); this.code = code; this.status = status }
+}
+
+/** First admitted work, not empty-file preparation time or later activity. */
+export function taskFirstWorkAt(events) {
+  for (const event of events) {
+    if (['agent/inbox/spliced', 'user/message', 'turn/start'].includes(event.type)
+      && Number.isSafeInteger(event.time) && event.time >= 0) return event.time
+  }
+  return undefined
+}
+
+/** open* returns {table,close}; subscribe returns an event unsubscriber. */
+export function createNativePinHost({ registry, openOrder, openLegacy, subscribe, listSessions, readTaskStartedAt, now = () => new Date().toISOString(), taskCreationNow = Date.now }) {
+  let pins = [], archived = [], rank = [], revision = 0, updatedAt = now(), epoch = 0
+  let phase = 'initializing', record, table, disposed = false, started = false, nativeValid = true
+  let tail = Promise.resolve(), initialization, migration, reconcileQueued = false
+  const handles = new Set(), touched = new Set(), warnings = [], warningSet = new Set()
+  const warn = error => { const text = messageOf(error); if (!warningSet.has(text)) { warningSet.add(text); warnings.push(text); if (warnings.length > 30) warnings.shift() } }
+  const enqueue = work => {
+    const next = tail.then(() => { if (disposed) throw new NativePinError('better-tasks/closed', 'Task ordering is closed', 503); return work() })
+    tail = next.catch(() => {})
+    return next
+  }
+  const createdAt = new Map(), firstWorkAt = new Map(), headers = new Map(), admittedHere = new Set(), lifetime = new AbortController()
+  let metadataDirty = false
+  const newestFirst = (ids) => [...ids].sort((a, b) => {
+    const left = createdAt.get(a), right = createdAt.get(b)
+    if (left === undefined || right === undefined) return left === right ? 0 : left === undefined ? 1 : -1
+    return right - left || (a < b ? -1 : a > b ? 1 : 0)
+  })
+  const orderedIds = () => {
+    const ids = projectIds(rank, pins)
+    if (record?.manualSessionIds === undefined) return newestFirst(ids)
+    const members = new Set(ids), manual = new Set(record.manualSessionIds)
+    // New tasks lead; an existing manual sequence never follows message activity.
+    return [...newestFirst(ids.filter(id => !manual.has(id))), ...record.manualSessionIds.filter(id => members.has(id))]
+  }
+  async function refreshCreatedAt() {
+    const before = orderedIds()
+    try {
+      if (typeof listSessions === 'function' && pins.some(id => !headers.has(id))) {
+        const rows = await listSessions(lifetime.signal)
+        if (disposed) return
+        for (const { header } of rows) if (pins.includes(header.id)) {
+          headers.set(header.id, header)
+          if (!createdAt.has(header.id) && Number.isSafeInteger(header.createdAt) && header.createdAt >= 0) createdAt.set(header.id, header.createdAt)
+        }
+      }
+      for (const id of [...pins]) {
+        const header = headers.get(id)
+        // Forks inherit parent work; their own creation header remains the key.
+        if (!header || header.isSeeded === true) continue
+        let timestamp = firstWorkAt.get(id)
+        if (timestamp === undefined && typeof readTaskStartedAt === 'function') {
+          try { timestamp = await readTaskStartedAt(header, lifetime.signal) }
+          catch (error) { if (!disposed) warn(error); continue }
+          if (disposed) return
+          if (!pins.includes(id) || !Number.isSafeInteger(timestamp) || timestamp < 0) continue
+          firstWorkAt.set(id, timestamp); metadataDirty = true
+          // Only work born after the manual decision leads. A delayed birth
+          // read must not override an explicit drag made after that work began.
+          const manualAt = record?.manualOrderAt ?? Date.parse(record?.updatedAt)
+          const newerThanManual = Number.isFinite(manualAt) ? timestamp > manualAt : phase === 'done' || phase === 'partial'
+          if (newerThanManual && record?.manualSessionIds?.includes(id)) {
+            record = { ...record, manualSessionIds: record.manualSessionIds.filter(value => value !== id) }
+          }
+        }
+        if (timestamp !== undefined) createdAt.set(id, Math.max(createdAt.get(id) ?? 0, timestamp))
+      }
+      for (const map of [createdAt, firstWorkAt, headers]) for (const id of map.keys()) if (!pins.includes(id)) map.delete(id)
+      if (!sameIds(before, orderedIds())) { revision++; updatedAt = now() }
+    } catch (error) { if (!disposed) warn(error) }
+  }
+  const response = () => ({
+    queue: { schemaVersion: 1, revision, sessionIds: orderedIds(), updatedAt },
+    ...(warnings.length === 0 ? {} : { warnings: [...warnings] }),
+    migration: { status: phase }, writable: !disposed && nativeValid && table !== undefined && (phase === 'done' || phase === 'partial'),
+  })
+  const nativeSnapshot = (nextPins, nextArchived, observe = true) => {
+    const p = ownedIds(nextPins), a = ownedIds(nextArchived)
+    nativeValid = true
+    if (sameIds(p, pins) && sameIds(a, archived)) return
+    if (observe) for (const id of [...changedIds(pins, p), ...changedIds(archived, a)]) touched.add(id)
+    const previous = projectIds(rank, pins)
+    // A newly admitted task goes first even if the native action reuses an old
+    // blank Session or its header is not in the metadata catalog yet. Only new
+    // membership counts; message/status updates and native pin-array order do not.
+    if (observe && phase !== 'running') {
+      const previousMembers = new Set(pins)
+      let admittedAt = taskCreationNow()
+      if (Number.isSafeInteger(admittedAt) && admittedAt >= 0) {
+        // A same-millisecond click must still precede the prior admission. This
+        // logical ordering key is never shown as a replacement Session date.
+        for (const timestamp of createdAt.values()) if (timestamp >= admittedAt && timestamp < Number.MAX_SAFE_INTEGER) admittedAt = timestamp + 1
+        for (const id of p) if (!previousMembers.has(id)) { createdAt.set(id, admittedAt); admittedHere.add(id) }
+      }
+    }
+    pins = p; archived = a; epoch++
+    if (!sameIds(previous, projectIds(rank, pins))) { revision++; updatedAt = now() }
+    scheduleReconcile()
+  }
+  function scheduleReconcile() {
+    if (!disposed && nativeValid && started && table !== undefined && (phase === 'done' || phase === 'partial') && !reconcileQueued) {
+      reconcileQueued = true
+      void enqueue(async () => { reconcileQueued = false; await refreshCreatedAt(); await reconcile() }).catch(error => { reconcileQueued = false; warn(error) })
+    }
+  }
+  // Storage emits before WorkspaceRegistry's private cache is assigned. Payload
+  // ownership is essential: never synchronously read registry getters here.
+  const off = subscribe(change => {
+    if (disposed || change?.domain !== 'workspace' || change.table !== '' || change.key !== '' || change.operation !== 'put') return
+    try { nativeSnapshot(change.value?.pinnedSessionIds, change.value?.archivedSessionIds) }
+    catch (error) { nativeValid = false; warn(error) }
+  })
+  try { nativeSnapshot(registry.pinnedSessionIds, registry.archivedSessionIds, false) }
+  catch (error) { nativeValid = false; warn(error); phase = 'error' }
+  const initiallyPinned = new Set(pins)
+
+  async function save(next) {
+    const nextRank = ownedIds(next.sessionIds)
+    const nextRevision = Math.max(revision, record?.revision ?? 0) + (sameIds(rank, nextRank) ? 0 : 1)
+    const value = { ...next, schemaVersion: 1, revision: nextRevision, sessionIds: nextRank, updatedAt: now(),
+      taskCreatedAtBySession: Object.fromEntries([...createdAt].filter(([id]) => pins.includes(id))),
+      taskFirstWorkAtBySession: Object.fromEntries([...firstWorkAt].filter(([id]) => pins.includes(id))),
+      ...(next.manualSessionIds === undefined ? {} : { manualSessionIds: next.manualSessionIds.filter(id => pins.includes(id)) }) }
+    // A singleton owner plus this controller's tail owns all writes to this domain.
+    if (record === undefined) await table.put(NATIVE_ORDER_KEY, value)
+    else await table.update(NATIVE_ORDER_KEY, () => value)
+    metadataDirty = false
+    record = value; rank = [...value.sessionIds]; revision = Math.max(revision, value.revision); updatedAt = value.updatedAt
+    return value
+  }
+  async function reconcile() {
+    if (record === undefined || phase === 'initializing' || phase === 'running') return
+    const ids = orderedIds()
+    if (sameIds(ids, rank) && record.revision === revision && !metadataDirty) return
+    await save({ ...record, sessionIds: ids })
+  }
+  async function open(factory) {
+    const handle = await factory()
+    if (disposed) { await handle.close(); throw new NativePinError('better-tasks/closed', 'Task ordering is closed', 503) }
+    handles.add(handle)
+    return handle
+  }
+  async function close(handle) { if (!handles.delete(handle)) return; await handle.close() }
+  const replaceEntry = (id, patch) => ({ ...record, migration: { ...record.migration,
+    entries: record.migration.entries.map(entry => entry.sessionId === id ? { ...entry, ...patch } : entry) } })
+
+  async function runMigration() {
+    for (const entry of record.migration.entries) {
+      if (disposed) return
+      if (entry.status !== 'pending') continue
+      await enqueue(async () => {
+        if (!nativeValid) throw new Error('Native pin state is unavailable; legacy import has stopped')
+        if (touched.has(entry.sessionId) || pins.includes(entry.sessionId) || archived.includes(entry.sessionId)) {
+          await save(replaceEntry(entry.sessionId, { status: 'skipped', detail: 'Native pin/archive activity takes precedence' })); return
+        }
+        // Durable BEFORE the side effect. An interrupted journal never retries.
+        await save(replaceEntry(entry.sessionId, { status: 'attempted' }))
+        if (disposed) return
+        if (!nativeValid) throw new Error('Native pin state became unavailable before legacy import')
+        if (touched.has(entry.sessionId) || pins.includes(entry.sessionId) || archived.includes(entry.sessionId)) {
+          await save(replaceEntry(entry.sessionId, { status: 'skipped', detail: 'Native activity while import was preparing' })); return
+        }
+        const observedEpoch = epoch
+        let outcome
+        try {
+          await registry.pinSession(entry.sessionId)
+          if (observedEpoch === epoch) nativeSnapshot(registry.pinnedSessionIds, registry.archivedSessionIds)
+          outcome = { status: 'imported' }
+        } catch (error) {
+          const known = error?.name === 'WorkspaceUnknownSessionError' || error?.name === 'WorkspaceArchivedSessionPinError'
+          outcome = { status: known ? 'skipped' : 'failed', detail: messageOf(error) }
+          warn(`Legacy task ${entry.sessionId} was not imported: ${outcome.detail}`)
+        }
+        await save(replaceEntry(entry.sessionId, outcome))
+      })
+    }
+    if (disposed) return
+    await enqueue(async () => {
+      const partial = record.migration.entries.some(entry => entry.status === 'failed' || entry.status === 'attempted')
+      const status = partial ? 'partial' : 'done'
+      // Until now legacy seed rank was retained even for not-yet-imported ids.
+      await refreshCreatedAt()
+      await save({ ...record, sessionIds: orderedIds(), migration: { ...record.migration, status } })
+      phase = status
+    })
+  }
+  async function initialize() {
+    if (!nativeValid) throw new Error('Native pin state is unavailable')
+    const order = await open(openOrder); table = order.table
+    const stored = table.get(NATIVE_ORDER_KEY)
+    if (stored !== undefined) {
+      rank = ownedIds(stored.sessionIds); record = stored; revision = Math.max(revision, stored.revision); updatedAt = stored.updatedAt
+      for (const [id, timestamp] of Object.entries(stored.taskCreatedAtBySession ?? {})) {
+        if (pins.includes(id) && !admittedHere.has(id) && Number.isSafeInteger(timestamp) && timestamp >= 0) createdAt.set(id, timestamp)
+      }
+      for (const [id, timestamp] of Object.entries(stored.taskFirstWorkAtBySession ?? {})) {
+        if (pins.includes(id) && Number.isSafeInteger(timestamp) && timestamp >= 0) firstWorkAt.set(id, timestamp)
+      }
+      await refreshCreatedAt()
+      for (const entry of stored.migration.entries) if (entry.detail && (entry.status === 'failed' || entry.status === 'uncertain')) warn(`Legacy task ${entry.sessionId}: ${entry.detail}`)
+      if (stored.migration.status === 'running') {
+        warn('Legacy pin migration was interrupted; unconfirmed entries will not be retried automatically. The original queue is preserved.')
+        await enqueue(async () => {
+          await save({ ...record, sessionIds: projectIds(rank, pins), migration: { ...record.migration, status: 'partial', entries: record.migration.entries.map(entry => entry.status === 'pending' || entry.status === 'attempted' ? { ...entry, status: 'uncertain', detail: 'Interrupted import; use the official Pin control to recover explicitly' } : entry) } })
+        })
+        phase = 'partial'
+      } else phase = stored.migration.status
+      await enqueue(reconcile)
+      return
+    }
+    await refreshCreatedAt()
+    // The legacy unit is opened with its unchanged v1 schema, read, then closed.
+    const legacy = await open(openLegacy)
+    let seed
+    try { seed = legacy.table.get(NATIVE_ORDER_KEY); if (seed !== undefined) ownedIds(seed.sessionIds) }
+    finally { await close(legacy) }
+    const seedIds = seed?.sessionIds ?? [], alreadyNative = new Set([...initiallyPinned, ...pins])
+    const entries = seedIds.map(sessionId => ({ sessionId,
+      status: alreadyNative.has(sessionId) || touched.has(sessionId) || archived.includes(sessionId) ? 'skipped' : 'pending',
+      ...(alreadyNative.has(sessionId) ? { detail: 'Already officially pinned; never an import target' } : {}),
+    }))
+    await enqueue(async () => {
+      await save({ schemaVersion: 1, revision, sessionIds: [...seedIds, ...pins.filter(id => !seedIds.includes(id))], updatedAt: now(),
+        migration: { status: 'running', sourceRevision: seed?.revision ?? null, entries } })
+      phase = 'running'
+    })
+    migration = runMigration().catch(error => { if (!disposed) { warn(`Legacy migration stopped: ${messageOf(error)}. The original queue is preserved.`); phase = 'error' } })
+  }
+  const start = () => {
+    if (started || disposed) return
+    started = true; phase = 'initializing'
+    initialization = initialize().catch(error => { if (!disposed) { phase = 'error'; warn(`Task order initialization failed: ${messageOf(error)}`) } })
+  }
+  function requireCommand(command) {
+    if (command === null || typeof command !== 'object' || typeof command.sessionId !== 'string' || command.sessionId === '') throw new NativePinError('better-tasks/invalid-request', 'A Session identity is required')
+    if (!['move', 'pin', 'pin-created', 'unpin'].includes(command.action)) throw new NativePinError('better-tasks/invalid-request', 'Unsupported task operation')
+  }
+  return {
+    read() { start(); scheduleReconcile(); return response() },
+    current: response,
+    async mutate(command) {
+      requireCommand(command)
+      // Explicit compatibility intent also counts when the native call will be
+      // an idempotent no-op and therefore emit no workspace change event.
+      if (command.action !== 'move') touched.add(command.sessionId)
+      start()
+      // Do not queue a move behind an in-flight migration I/O operation merely
+      // to return the already-known initializing/readonly state afterwards.
+      if (command.action === 'move' && !response().writable) throw new NativePinError('better-tasks/order-unavailable', 'Task ordering is initializing, migrating or unavailable; official Pin remains usable', 503)
+      return enqueue(async () => {
+        if (command.action !== 'move') {
+          // Compatibility for old clients; all new UI uses official public controls.
+          const observedEpoch = epoch
+          if (command.action === 'unpin') await registry.unpinSession(command.sessionId)
+          else await registry.pinSession(command.sessionId)
+          if (observedEpoch === epoch) nativeSnapshot(registry.pinnedSessionIds, registry.archivedSessionIds)
+          try { await reconcile() } catch (error) { warn(`Native pin change succeeded, but task order could not be saved: ${messageOf(error)}`) }
+          return response()
+        }
+        if (!Number.isSafeInteger(command.expectedRevision) || command.expectedRevision < 0) throw new NativePinError('better-tasks/invalid-request', 'expectedRevision must be a non-negative safe integer')
+        if (!response().writable) throw new NativePinError('better-tasks/order-unavailable', 'Task ordering is initializing, migrating or unavailable; official Pin remains usable', 503)
+        await reconcile()
+        if (command.expectedRevision !== revision) throw new NativePinError('better-tasks/revision-conflict', 'Task order changed', 409)
+        const ids = orderedIds(), before = command.beforeSessionId ?? null
+        if (!ids.includes(command.sessionId)) throw new NativePinError('better-tasks/not-pinned', 'Session is no longer officially pinned', 409)
+        if (before !== null && (typeof before !== 'string' || !ids.includes(before))) throw new NativePinError('better-tasks/anchor-not-pinned', 'Move anchor is no longer officially pinned', 409)
+        if (before === command.sessionId) return response()
+        const next = ids.filter(id => id !== command.sessionId)
+        next.splice(before === null ? next.length : next.indexOf(before), 0, command.sessionId)
+        if (sameIds(next, ids)) return response()
+        const observedEpoch = epoch
+        await save({ ...record, sessionIds: next, manualSessionIds: next, manualOrderAt: taskCreationNow() })
+        if (observedEpoch !== epoch) {
+          await reconcile()
+          throw new NativePinError('better-tasks/revision-conflict', 'Official membership changed while saving task order', 409)
+        }
+        return response()
+      })
+    },
+    async settled() { await initialization; await migration; await tail },
+    async dispose() {
+      if (disposed) return
+      disposed = true; lifetime.abort(); off?.()
+      await initialization; await migration; await tail
+      await Promise.all([...handles].map(close))
+    },
+  }
+}