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

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,220 @@
+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 } 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({
+    // Read compatibility only. sessionIds is the sole order; new writes omit
+    // the former manual subset and time-derived sorting metadata.
+    manualSessionIds: z.array(z.string().min(1)).refine((ids) => new Set(ids).size === ids.length).optional(),
+    manualOrderAt: z.number().int().nonnegative().optional(),
+    // Old admission/work caches are accepted, never read to determine order.
+    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,
+    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,261 @@
+// Official Workspace pins own membership. This controller owns one complete order
+// and a sealed, at-most-once legacy import journal; it never compensates native Pin.
+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 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))]
+}
+// New members join the complete sequence immediately. Pure native array reorders
+// cannot move existing members; neither clocks nor Session content are involved.
+const mergeOrder = (sequence, pins, reserved = new Set()) => {
+  const members = new Set(pins), ranked = new Set(sequence)
+  return [...pins.filter(id => !ranked.has(id)), ...sequence.filter(id => members.has(id) || reserved.has(id))]
+}
+export class NativePinError extends Error {
+  constructor(code, message, status = 400) { super(message); this.code = code; this.status = status }
+}
+
+/** open* returns {table,close}; subscribe returns an event unsubscriber. */
+export function createNativePinHost({ registry, openOrder, openLegacy, subscribe, now = () => new Date().toISOString() }) {
+  let pins = [], archived = [], rank = [], sequence = [], revision = 0, updatedAt = now(), epoch = 0
+  let phase = 'initializing', record, table, disposed = false, started = false, nativeValid = true, hydrated = false
+  let tail = Promise.resolve(), initialization, migration, reconcileQueued = false, persistenceError = null
+  const snapshots = [], handles = new Set(), touched = new Set(), reservedIds = 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 orderedIds = () => sequence.filter(id => pins.includes(id))
+  const orderReady = () => !disposed && nativeValid && table !== undefined && (phase === 'done' || phase === 'partial')
+  const response = () => {
+    const errors = [...warnings, ...(persistenceError ? [persistenceError] : [])]
+    return {
+      queue: { schemaVersion: 1, revision, sessionIds: orderedIds(), updatedAt },
+      ...(errors.length ? { warnings: errors } : {}),
+      migration: { status: phase },
+      writable: orderReady() && !persistenceError && sameIds(rank, orderedIds()),
+    }
+  }
+  const reservations = () => new Set([...reservedIds].filter(id => !touched.has(id) && !archived.includes(id)))
+  const nativeSnapshot = (nextPins, nextArchived, observe = true) => {
+    const a = ownedIds(nextArchived), excluded = new Set(a), p = ownedIds(nextPins).filter(id => !excluded.has(id))
+    nativeValid = true
+    if (sameIds(p, pins) && sameIds(a, archived)) return
+    const membershipChanged = changedIds(pins, p).length > 0 || changedIds(archived, a).length > 0
+    if (observe) for (const id of [...changedIds(pins, p), ...changedIds(archived, a)]) touched.add(id)
+    pins = p; archived = a
+    if (!observe) { sequence = [...p]; return }
+    if (membershipChanged) epoch++
+    // Retain all transitions while opening storage, including Unpin -> Pin of
+    // the same id. One latest snapshot would lose its re-insertion position.
+    if (!hydrated) snapshots.push([...p])
+    sequence = mergeOrder(sequence, pins, reservations())
+    if (membershipChanged) start()
+    scheduleReconcile()
+  }
+  function scheduleReconcile() {
+    if (!orderReady() || reconcileQueued) return
+    reconcileQueued = true
+    void enqueue(async () => {
+      try { await reconcile() } finally { reconcileQueued = false }
+    }).catch(() => {})
+  }
+  // Storage emits before WorkspaceRegistry's private cache is assigned. Always
+  // consume the owned event payload, never registry getters inside this callback.
+  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 initialPins = [...pins], initiallyPinned = new Set(pins)
+
+  async function save(next) {
+    const nextRank = ownedIds(next.sessionIds)
+    // Legacy fields remain readable in the v1 schema, but are no longer writers
+    // or authorities. Every new commit contains just one complete order.
+    const { manualSessionIds, manualOrderAt, taskCreatedAtBySession, taskFirstWorkAtBySession, ...base } = next
+    const value = { ...base, schemaVersion: 1, revision: revision + 1, sessionIds: nextRank, updatedAt: now() }
+    try {
+      if (record === undefined) await table.put(NATIVE_ORDER_KEY, value)
+      else await table.update(NATIVE_ORDER_KEY, () => value)
+    } catch (error) {
+      persistenceError = 'Task order was not saved; official Pin membership is unchanged: ' + messageOf(error)
+      throw error
+    }
+    // Never advance a committed revision/rank before storage acknowledges. The
+    // live sequence may already include newer events received during this write.
+    record = value; rank = [...value.sessionIds]; revision = value.revision; updatedAt = value.updatedAt
+    persistenceError = null
+    return value
+  }
+  async function reconcile() {
+    if (!orderReady() || record === undefined) return
+    while (!sameIds(rank, orderedIds())) await save({ ...record, sessionIds: orderedIds() })
+    persistenceError = null
+  }
+  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, sessionIds: [...sequence], 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'
+      reservedIds.clear()
+      sequence = orderedIds() // Remove only the unimported reservations.
+      await save({ ...record, sessionIds: [...sequence], migration: { ...record.migration, status } })
+      phase = status
+      await reconcile()
+    })
+  }
+  function hydrate(base, reserved = new Set()) {
+    for (const id of reserved) reservedIds.add(id)
+    sequence = mergeOrder(base, initialPins, reserved)
+    for (const snapshot of snapshots) sequence = mergeOrder(sequence, snapshot, reserved)
+    snapshots.length = 0; hydrated = true
+  }
+  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 = stored.revision; updatedAt = stored.updatedAt
+      hydrate(rank)
+      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: orderedIds(), 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
+    }
+    // The legacy unit is opened unchanged, read and closed; never erase its data.
+    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' } : {}),
+    }))
+    const pending = new Set(entries.filter(entry => entry.status === 'pending').map(entry => entry.sessionId))
+    hydrate([...seedIds, ...initialPins.filter(id => !seedIds.includes(id))], pending)
+    // No old import work means no fake migration phase or extra journal writes.
+    const status = pending.size ? 'running' : 'done'
+    await enqueue(async () => {
+      await save({ sessionIds: [...sequence], migration: { status, sourceRevision: seed?.revision ?? null, entries } })
+      phase = status
+      if (status === 'done') await reconcile()
+    })
+    if (status === 'running') migration = runMigration().catch(error => { if (!disposed) { warn('Legacy migration stopped: ' + messageOf(error) + '. The original queue is preserved.'); phase = 'error' } })
+  }
+  function start() {
+    if (started || disposed) return
+    started = true; phase = 'initializing'
+    initialization = initialize().catch(error => {
+      // A loaded terminal journal with a dirty sequence can retry a failed save.
+      // Opening/fencing/import failures remain terminal and must not replay Pin.
+      if (!disposed && !orderReady()) { 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)
+      if (command.action !== 'move') touched.add(command.sessionId)
+      start()
+      if (command.action === 'move' && !orderReady()) throw new NativePinError('better-tasks/order-unavailable', 'Task order is initializing, importing or unavailable; official Pin remains usable', 503)
+      return enqueue(async () => {
+        if (command.action !== 'move') {
+          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 { /* save exposes persistenceError; never undo the native result. */ }
+          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 (!orderReady()) throw new NativePinError('better-tasks/order-unavailable', 'Task ordering is 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 })
+        if (observedEpoch !== epoch) {
+          await reconcile()
+          throw new NativePinError('better-tasks/revision-conflict', 'Official membership changed while saving task order', 409)
+        }
+        sequence = next
+        return response()
+      })
+    },
+    async settled() { await initialization; await migration; await tail },
+    async dispose() {
+      if (disposed) return
+      disposed = true; off?.()
+      await initialization; await migration; await tail
+      await Promise.all([...handles].map(close))
+    },
+  }
+}