@h-rig/contracts 0.0.6-alpha.103 → 0.0.6-alpha.119

package/dist/index.cjs

@@ -40,9 +40,22 @@ var __export = (target, all) => {
 // packages/contracts/src/index.ts
 var exports_src = {};
 __export(exports_src, {
+  timelineEntriesFromCustomEntries: () => timelineEntriesFromCustomEntries,
   sessionIdFromSessionFile: () => sessionIdFromSessionFile,
   reduceRunJournal: () => reduceRunJournal,
+  projectWorkflowEntries: () => projectWorkflowEntries,
+  projectCollabWorkflowMarker: () => projectCollabWorkflowMarker,
+  parseWorkflowTaskSelected: () => parseWorkflowTaskSelected,
+  parseWorkflowTargetSelected: () => parseWorkflowTargetSelected,
+  parseWorkflowStatusChanged: () => parseWorkflowStatusChanged,
+  parseWorkflowStarted: () => parseWorkflowStarted,
+  parseWorkflowOperatorNote: () => parseWorkflowOperatorNote,
+  parseWorkflowInboxResolved: () => parseWorkflowInboxResolved,
+  parseWorkflowInboxRequested: () => parseWorkflowInboxRequested,
   parseStopSentinel: () => parseStopSentinel,
+  parseResumeSentinel: () => parseResumeSentinel,
+  parsePauseSentinel: () => parsePauseSentinel,
+  parseInboxResolutionSentinel: () => parseInboxResolutionSentinel,
   normalizeRunStatusToken: () => normalizeRunStatusToken,
   isTerminalRunStatus: () => isTerminalRunStatus,
   isRunSessionCustomType: () => isRunSessionCustomType,
@@ -51,8 +64,20 @@ __export(exports_src, {
   helpCatalog: () => helpCatalog,
   foldRunSessionEntries: () => foldRunSessionEntries,
   decodeRunJournalEvent: () => decodeRunJournalEvent,
+  createWorkflowTaskSelected: () => createWorkflowTaskSelected,
+  createWorkflowTargetSelected: () => createWorkflowTargetSelected,
+  createWorkflowStatusChanged: () => createWorkflowStatusChanged,
+  createWorkflowStarted: () => createWorkflowStarted,
+  createWorkflowOperatorNote: () => createWorkflowOperatorNote,
+  createWorkflowInboxResolved: () => createWorkflowInboxResolved,
+  createWorkflowInboxRequested: () => createWorkflowInboxRequested,
+  collectResolvedInboxRequests: () => collectResolvedInboxRequests,
+  collectPendingInboxRequests: () => collectPendingInboxRequests,
   canTransitionRunStatus: () => canTransitionRunStatus,
   buildStopSentinel: () => buildStopSentinel,
+  buildResumeSentinel: () => buildResumeSentinel,
+  buildPauseSentinel: () => buildPauseSentinel,
+  buildInboxResolutionSentinel: () => buildInboxResolutionSentinel,
   assertRunStatusTransition: () => assertRunStatusTransition,
   WsWelcomePayload: () => WsWelcomePayload,
   WsResponse: () => WsResponse,
@@ -330,6 +355,13 @@ __export(exports_src, {
   RUN_STATUS_TRANSITIONS: () => RUN_STATUS_TRANSITIONS,
   RIG_WS_METHODS: () => RIG_WS_METHODS,
   RIG_WS_CHANNELS: () => RIG_WS_CHANNELS,
+  RIG_WORKFLOW_TASK_SELECTED: () => RIG_WORKFLOW_TASK_SELECTED,
+  RIG_WORKFLOW_TARGET_SELECTED: () => RIG_WORKFLOW_TARGET_SELECTED,
+  RIG_WORKFLOW_STATUS_CHANGED: () => RIG_WORKFLOW_STATUS_CHANGED,
+  RIG_WORKFLOW_STARTED: () => RIG_WORKFLOW_STARTED,
+  RIG_WORKFLOW_OPERATOR_NOTE: () => RIG_WORKFLOW_OPERATOR_NOTE,
+  RIG_WORKFLOW_INBOX_RESOLVED: () => RIG_WORKFLOW_INBOX_RESOLVED,
+  RIG_WORKFLOW_INBOX_REQUESTED: () => RIG_WORKFLOW_INBOX_REQUESTED,
   RIG_STOP_SENTINEL_END: () => RIG_STOP_SENTINEL_END,
   RIG_STOP_SENTINEL: () => RIG_STOP_SENTINEL,
   RIG_RUN_TIMELINE_ENTRY: () => RIG_RUN_TIMELINE_ENTRY,
@@ -344,7 +376,11 @@ __export(exports_src, {
   RIG_RUN_APPROVAL_RESOLVED: () => RIG_RUN_APPROVAL_RESOLVED,
   RIG_RUN_APPROVAL_REQUESTED: () => RIG_RUN_APPROVAL_REQUESTED,
   RIG_RUN_ADOPTED: () => RIG_RUN_ADOPTED,
+  RIG_RESUME_SENTINEL: () => RIG_RESUME_SENTINEL,
   RIG_PROTOCOL_VERSION: () => RIG_PROTOCOL_VERSION,
+  RIG_PAUSE_SENTINEL: () => RIG_PAUSE_SENTINEL,
+  RIG_INBOX_RESOLUTION_SENTINEL: () => RIG_INBOX_RESOLUTION_SENTINEL,
+  RIG_CONTROL_SENTINEL_END: () => RIG_CONTROL_SENTINEL_END,
   REASONING_EFFORT_OPTIONS_BY_PROVIDER: () => REASONING_EFFORT_OPTIONS_BY_PROVIDER,
   QueueEntry: () => QueueEntry,
   PullRequestConfig: () => PullRequestConfig,
@@ -2295,6 +2331,85 @@ function parseStopSentinel(text, expectedRunId) {
   const reason = body.match(/(?:^|\s)reason=(.+)$/)?.[1]?.trim() ?? null;
   return { reason };
 }
+var RIG_PAUSE_SENTINEL = "<<RIG_PAUSE";
+var RIG_RESUME_SENTINEL = "<<RIG_RESUME";
+var RIG_CONTROL_SENTINEL_END = ">>";
+function buildControlSentinel(marker, runId, requestedBy) {
+  return `${marker} runId=${runId} requestedBy=${requestedBy}${RIG_CONTROL_SENTINEL_END}`;
+}
+function parseControlSentinel(marker, text, expectedRunId) {
+  const start = text.indexOf(marker);
+  if (start < 0)
+    return null;
+  const end = text.indexOf(RIG_CONTROL_SENTINEL_END, start);
+  const body = text.slice(start + marker.length, end >= 0 ? end : undefined).trim();
+  const runId = body.match(/(?:^|\s)runId=([^\s>]+)/)?.[1] ?? "";
+  if (runId && runId !== expectedRunId)
+    return null;
+  const requestedBy = body.match(/(?:^|\s)requestedBy=([^\s>]+)/)?.[1] ?? null;
+  return { requestedBy };
+}
+function buildPauseSentinel(runId, requestedBy = "rig") {
+  return buildControlSentinel(RIG_PAUSE_SENTINEL, runId, requestedBy);
+}
+function parsePauseSentinel(text, expectedRunId) {
+  return parseControlSentinel(RIG_PAUSE_SENTINEL, text, expectedRunId);
+}
+function buildResumeSentinel(runId, requestedBy = "rig") {
+  return buildControlSentinel(RIG_RESUME_SENTINEL, runId, requestedBy);
+}
+function parseResumeSentinel(text, expectedRunId) {
+  return parseControlSentinel(RIG_RESUME_SENTINEL, text, expectedRunId);
+}
+var RIG_INBOX_RESOLUTION_SENTINEL = "<<RIG_INBOX_RESOLUTION";
+function encodeInboxResolutionPayload(payload) {
+  return encodeURIComponent(JSON.stringify(payload));
+}
+function decodeInboxResolutionPayload(payload) {
+  try {
+    const parsed = JSON.parse(decodeURIComponent(payload));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return null;
+    const record = parsed;
+    if (record.kind === "approval") {
+      const requestId = typeof record.requestId === "string" ? record.requestId.trim() : "";
+      const decision = record.decision === "approve" || record.decision === "reject" ? record.decision : null;
+      const note = typeof record.note === "string" ? record.note : record.note === null ? null : undefined;
+      if (!requestId || !decision)
+        return null;
+      return { kind: "approval", requestId, decision, ...note !== undefined ? { note } : {} };
+    }
+    if (record.kind === "input") {
+      const requestId = typeof record.requestId === "string" ? record.requestId.trim() : "";
+      const answers = record.answers && typeof record.answers === "object" && !Array.isArray(record.answers) ? Object.fromEntries(Object.entries(record.answers).filter((entry) => typeof entry[1] === "string")) : null;
+      if (!requestId || !answers)
+        return null;
+      return { kind: "input", requestId, answers };
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+function buildInboxResolutionSentinel(runId, resolution, requestedBy = "rig") {
+  return `${RIG_INBOX_RESOLUTION_SENTINEL} runId=${runId} requestedBy=${requestedBy} data=${encodeInboxResolutionPayload(resolution)}${RIG_CONTROL_SENTINEL_END}`;
+}
+function parseInboxResolutionSentinel(text, expectedRunId) {
+  const start = text.indexOf(RIG_INBOX_RESOLUTION_SENTINEL);
+  if (start < 0)
+    return null;
+  const end = text.indexOf(RIG_CONTROL_SENTINEL_END, start);
+  const body = text.slice(start + RIG_INBOX_RESOLUTION_SENTINEL.length, end >= 0 ? end : undefined).trim();
+  const runId = body.match(/(?:^|\s)runId=([^\s>]+)/)?.[1] ?? "";
+  if (runId && runId !== expectedRunId)
+    return null;
+  const requestedBy = body.match(/(?:^|\s)requestedBy=([^\s>]+)/)?.[1] ?? null;
+  const payload = body.match(/(?:^|\s)data=([^\s>]+)/)?.[1] ?? "";
+  const decoded = decodeInboxResolutionPayload(payload);
+  if (!decoded)
+    return null;
+  return { ...decoded, requestedBy };
+}
 function sessionIdFromSessionFile(sessionPath) {
   if (!sessionPath)
     return null;
@@ -2353,6 +2468,384 @@ function foldRunSessionEntries(entries, runId) {
   });
   return reduceRunJournal(events);
 }
+// packages/contracts/src/workflow-journal.ts
+var RIG_WORKFLOW_STARTED = "rig.workflow.started";
+var RIG_WORKFLOW_TARGET_SELECTED = "rig.workflow.target.selected";
+var RIG_WORKFLOW_TASK_SELECTED = "rig.workflow.task.selected";
+var RIG_WORKFLOW_STATUS_CHANGED = "rig.workflow.status.changed";
+var RIG_WORKFLOW_OPERATOR_NOTE = "rig.workflow.operator.note";
+var RIG_WORKFLOW_INBOX_REQUESTED = "rig.workflow.inbox.requested";
+var RIG_WORKFLOW_INBOX_RESOLVED = "rig.workflow.inbox.resolved";
+var EMPTY_PROJECTION = {
+  started: null,
+  target: null,
+  task: null,
+  status: null,
+  notes: [],
+  inbox: [],
+  resolvedInbox: [],
+  updatedAt: null
+};
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function optionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function requiredString(value) {
+  const text = optionalString(value);
+  return text ?? null;
+}
+function timestamp(value) {
+  const text = requiredString(value);
+  if (!text)
+    return null;
+  const millis = Date.parse(text);
+  return Number.isFinite(millis) ? text : null;
+}
+function newer(left, right) {
+  if (!right)
+    return false;
+  if (!left)
+    return true;
+  return Date.parse(right) >= Date.parse(left);
+}
+function isWorkflowTarget(value) {
+  return value === "local" || value === "remote";
+}
+function isWorkflowStatus(value) {
+  return value === "starting" || value === "running" || value === "waiting-approval" || value === "waiting-input" || value === "completed" || value === "failed" || value === "stopped";
+}
+function isInboxKind(value) {
+  return value === "approval" || value === "input";
+}
+function isInboxDecision(value) {
+  return value === "approved" || value === "rejected" || value === "answered";
+}
+function parseOwner(value) {
+  const record = asRecord(value);
+  if (!record)
+    return null;
+  const githubUserId = requiredString(record.githubUserId);
+  const login = requiredString(record.login);
+  const namespaceKey = requiredString(record.namespaceKey);
+  return githubUserId && login && namespaceKey ? { githubUserId, login, namespaceKey } : null;
+}
+function parseStringArray(value) {
+  if (!Array.isArray(value))
+    return;
+  const options = value.map(optionalString).filter((option) => option !== undefined);
+  return options.length > 0 ? options : undefined;
+}
+function hasOwn(record, key) {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+function entryUpdatedAt(entry) {
+  if ("createdAt" in entry)
+    return entry.createdAt;
+  if ("selectedAt" in entry)
+    return entry.selectedAt;
+  if ("changedAt" in entry)
+    return entry.changedAt;
+  if ("notedAt" in entry)
+    return entry.notedAt;
+  if ("requestedAt" in entry)
+    return entry.requestedAt;
+  return entry.resolvedAt;
+}
+function createWorkflowStarted(input) {
+  return {
+    schemaVersion: 1,
+    workflowId: input.workflowId,
+    target: input.target,
+    selectedRepo: input.selectedRepo,
+    owner: input.owner,
+    createdAt: input.createdAt ?? new Date().toISOString()
+  };
+}
+function createWorkflowTargetSelected(input) {
+  return {
+    schemaVersion: 1,
+    target: input.target,
+    ...input.reason ? { reason: input.reason } : {},
+    selectedAt: input.selectedAt ?? new Date().toISOString()
+  };
+}
+function createWorkflowTaskSelected(input) {
+  return {
+    schemaVersion: 1,
+    taskId: input.taskId,
+    ...input.title ? { title: input.title } : {},
+    selectedAt: input.selectedAt ?? new Date().toISOString()
+  };
+}
+function createWorkflowStatusChanged(input) {
+  return {
+    schemaVersion: 1,
+    status: input.status,
+    ...input.detail ? { detail: input.detail } : {},
+    changedAt: input.changedAt ?? new Date().toISOString()
+  };
+}
+function createWorkflowOperatorNote(input) {
+  return {
+    schemaVersion: 1,
+    ...input.noteId ? { noteId: input.noteId } : {},
+    note: input.note,
+    notedAt: input.notedAt ?? new Date().toISOString()
+  };
+}
+function createWorkflowInboxRequested(input) {
+  return {
+    schemaVersion: 1,
+    requestId: input.requestId,
+    kind: input.kind,
+    title: input.title,
+    ...input.body ? { body: input.body } : {},
+    ...input.options && input.options.length > 0 ? { options: input.options } : {},
+    requestedAt: input.requestedAt ?? new Date().toISOString()
+  };
+}
+function createWorkflowInboxResolved(input) {
+  const base = {
+    schemaVersion: 1,
+    requestId: input.requestId,
+    decision: input.decision,
+    resolvedAt: input.resolvedAt ?? new Date().toISOString()
+  };
+  return hasOwn(input, "answer") ? { ...base, answer: input.answer } : base;
+}
+function parseWorkflowStarted(data) {
+  const record = asRecord(data);
+  if (!record || record.schemaVersion !== 1)
+    return null;
+  const workflowId = requiredString(record.workflowId);
+  const target = optionalString(record.target);
+  const selectedRepo = requiredString(record.selectedRepo);
+  const owner = parseOwner(record.owner);
+  const createdAt = timestamp(record.createdAt);
+  if (!workflowId || !isWorkflowTarget(target) || !selectedRepo || !owner || !createdAt)
+    return null;
+  return {
+    schemaVersion: 1,
+    workflowId,
+    target,
+    selectedRepo,
+    owner,
+    createdAt
+  };
+}
+function parseWorkflowTargetSelected(data) {
+  const record = asRecord(data);
+  if (!record || record.schemaVersion !== 1)
+    return null;
+  const target = optionalString(record.target);
+  const selectedAt = timestamp(record.selectedAt);
+  if (!isWorkflowTarget(target) || !selectedAt)
+    return null;
+  const reason = optionalString(record.reason);
+  return {
+    schemaVersion: 1,
+    target,
+    ...reason ? { reason } : {},
+    selectedAt
+  };
+}
+function parseWorkflowTaskSelected(data) {
+  const record = asRecord(data);
+  if (!record || record.schemaVersion !== 1)
+    return null;
+  const taskId = requiredString(record.taskId);
+  const selectedAt = timestamp(record.selectedAt);
+  if (!taskId || !selectedAt)
+    return null;
+  const title = optionalString(record.title);
+  return { schemaVersion: 1, taskId, ...title ? { title } : {}, selectedAt };
+}
+function parseWorkflowStatusChanged(data) {
+  const record = asRecord(data);
+  if (!record || record.schemaVersion !== 1)
+    return null;
+  const status = optionalString(record.status);
+  const changedAt = timestamp(record.changedAt);
+  if (!changedAt || !isWorkflowStatus(status))
+    return null;
+  const detail = optionalString(record.detail);
+  return { schemaVersion: 1, status, ...detail ? { detail } : {}, changedAt };
+}
+function parseWorkflowOperatorNote(data) {
+  const record = asRecord(data);
+  if (!record || record.schemaVersion !== 1)
+    return null;
+  const note = requiredString(record.note);
+  const notedAt = timestamp(record.notedAt);
+  if (!note || !notedAt)
+    return null;
+  const noteId = optionalString(record.noteId);
+  return { schemaVersion: 1, ...noteId ? { noteId } : {}, note, notedAt };
+}
+function parseWorkflowInboxRequested(data) {
+  const record = asRecord(data);
+  if (!record || record.schemaVersion !== 1)
+    return null;
+  const requestId = requiredString(record.requestId);
+  const kind = optionalString(record.kind);
+  const title = requiredString(record.title);
+  const requestedAt = timestamp(record.requestedAt);
+  if (!requestId || !isInboxKind(kind) || !title || !requestedAt)
+    return null;
+  const body = optionalString(record.body);
+  const options = parseStringArray(record.options);
+  return {
+    schemaVersion: 1,
+    requestId,
+    kind,
+    title,
+    ...body ? { body } : {},
+    ...options ? { options } : {},
+    requestedAt
+  };
+}
+function parseWorkflowInboxResolved(data) {
+  const record = asRecord(data);
+  if (!record || record.schemaVersion !== 1)
+    return null;
+  const requestId = requiredString(record.requestId);
+  const decision = optionalString(record.decision);
+  const resolvedAt = timestamp(record.resolvedAt);
+  if (!requestId || !isInboxDecision(decision) || !resolvedAt)
+    return null;
+  const base = { schemaVersion: 1, requestId, decision, resolvedAt };
+  return hasOwn(record, "answer") ? { ...base, answer: record.answer } : base;
+}
+function collectPendingInboxRequests(entries) {
+  const requested = new Map;
+  const resolved = new Map;
+  for (const entry of entries) {
+    if (entry.type !== "custom")
+      continue;
+    if (entry.customType === RIG_WORKFLOW_INBOX_REQUESTED) {
+      const request = parseWorkflowInboxRequested(entry.data);
+      if (request && newer(requested.get(request.requestId)?.requestedAt, request.requestedAt))
+        requested.set(request.requestId, request);
+    } else if (entry.customType === RIG_WORKFLOW_INBOX_RESOLVED) {
+      const resolution = parseWorkflowInboxResolved(entry.data);
+      if (resolution && newer(resolved.get(resolution.requestId), resolution.resolvedAt))
+        resolved.set(resolution.requestId, resolution.resolvedAt);
+    }
+  }
+  for (const [requestId, request] of requested) {
+    const resolvedAt = resolved.get(requestId);
+    if (resolvedAt && Date.parse(resolvedAt) >= Date.parse(request.requestedAt))
+      requested.delete(requestId);
+  }
+  return Array.from(requested.values()).sort((a, b) => Date.parse(b.requestedAt) - Date.parse(a.requestedAt));
+}
+function collectResolvedInboxRequests(entries) {
+  const requested = new Map;
+  const resolved = new Map;
+  for (const entry of entries) {
+    if (entry.type !== "custom")
+      continue;
+    if (entry.customType === RIG_WORKFLOW_INBOX_REQUESTED) {
+      const request = parseWorkflowInboxRequested(entry.data);
+      if (request && newer(requested.get(request.requestId), request.requestedAt))
+        requested.set(request.requestId, request.requestedAt);
+    } else if (entry.customType === RIG_WORKFLOW_INBOX_RESOLVED) {
+      const resolution = parseWorkflowInboxResolved(entry.data);
+      if (resolution && newer(resolved.get(resolution.requestId)?.resolvedAt, resolution.resolvedAt)) {
+        resolved.set(resolution.requestId, resolution);
+      }
+    }
+  }
+  for (const [requestId, resolution] of resolved) {
+    const requestedAt = requested.get(requestId);
+    if (requestedAt && Date.parse(requestedAt) > Date.parse(resolution.resolvedAt))
+      resolved.delete(requestId);
+  }
+  return Array.from(resolved.values()).sort((a, b) => Date.parse(b.resolvedAt) - Date.parse(a.resolvedAt));
+}
+function projectCollabWorkflowMarker(collab) {
+  const status = createWorkflowStatusChanged({
+    status: collab.stale ? "stopped" : "running",
+    detail: collab.stale ? "Stale OMP collab session discovered from the sanctioned collab registry." : "Live OMP collab session discovered from the sanctioned collab registry.",
+    changedAt: collab.updatedAt
+  });
+  return {
+    started: null,
+    target: null,
+    task: null,
+    status,
+    notes: [],
+    inbox: [],
+    resolvedInbox: [],
+    updatedAt: newer(collab.startedAt, collab.updatedAt) ? collab.updatedAt : collab.startedAt
+  };
+}
+function projectWorkflowEntries(entries) {
+  let started = null;
+  let target = null;
+  let task = null;
+  let status = null;
+  const notes = [];
+  let updatedAt = null;
+  for (const entry of entries) {
+    if (entry.type !== "custom")
+      continue;
+    if (entry.customType === RIG_WORKFLOW_STARTED) {
+      const parsed = parseWorkflowStarted(entry.data);
+      if (parsed && newer(started?.createdAt, parsed.createdAt))
+        started = parsed;
+    } else if (entry.customType === RIG_WORKFLOW_TARGET_SELECTED) {
+      const parsed = parseWorkflowTargetSelected(entry.data);
+      if (parsed && newer(target?.selectedAt, parsed.selectedAt))
+        target = parsed;
+    } else if (entry.customType === RIG_WORKFLOW_TASK_SELECTED) {
+      const parsed = parseWorkflowTaskSelected(entry.data);
+      if (parsed && newer(task?.selectedAt, parsed.selectedAt))
+        task = parsed;
+    } else if (entry.customType === RIG_WORKFLOW_STATUS_CHANGED) {
+      const parsed = parseWorkflowStatusChanged(entry.data);
+      if (parsed && newer(status?.changedAt, parsed.changedAt))
+        status = parsed;
+    } else if (entry.customType === RIG_WORKFLOW_OPERATOR_NOTE) {
+      const parsed = parseWorkflowOperatorNote(entry.data);
+      if (parsed)
+        notes.push(parsed);
+    }
+  }
+  notes.sort((a, b) => Date.parse(b.notedAt) - Date.parse(a.notedAt));
+  for (const value of [started, target, task, status, ...notes].map((entry) => entry ? entryUpdatedAt(entry) : null)) {
+    if (newer(updatedAt, value))
+      updatedAt = value;
+  }
+  const inbox = collectPendingInboxRequests(entries);
+  const resolvedInbox = collectResolvedInboxRequests(entries);
+  for (const entry of [...inbox, ...resolvedInbox]) {
+    if (newer(updatedAt, entryUpdatedAt(entry)))
+      updatedAt = entryUpdatedAt(entry);
+  }
+  if (!started && !target && !task && !status && notes.length === 0 && inbox.length === 0 && resolvedInbox.length === 0 && !updatedAt)
+    return EMPTY_PROJECTION;
+  return { started, target, task, status, notes, inbox, resolvedInbox, updatedAt };
+}
+// packages/contracts/src/run-timeline.ts
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function timelineEntriesFromCustomEntries(entries) {
+  return entries.flatMap((entry) => {
+    if (entry.customType !== CUSTOM_TYPE_FOR["timeline-entry"] || !isRecord(entry.data))
+      return [];
+    const payload = isRecord(entry.data.payload) ? entry.data.payload : entry.data;
+    const type = typeof payload.type === "string" ? payload.type : "timeline";
+    const stage = typeof payload.stage === "string" ? payload.stage : typeof payload.name === "string" ? payload.name : null;
+    const status = typeof payload.status === "string" ? payload.status : typeof payload.outcome === "string" ? payload.outcome : null;
+    const detail = typeof payload.detail === "string" ? payload.detail : typeof payload.message === "string" ? payload.message : null;
+    const at = typeof entry.data.at === "string" ? entry.data.at : typeof payload.at === "string" ? payload.at : null;
+    return [{ at, type, stage, status, detail }];
+  });
+}
 // packages/contracts/src/run-status.ts
 var OPERATOR_INACTIVE_RUN_STATUSES = new Set([
   "completed",
@@ -5540,14 +6033,15 @@ var TOP_LEVEL_SECTIONS = [
     subtitle: "every run is an isolated, collaborative OMP session on the selected target",
     commands: [
       {
-        command: "rig run start <task|#issue|--next>",
+        command: "rig run [start] <task|#issue|--next>",
         description: "Dispatch a run for a task (refuses if one is already active; --force overrides).",
         usecase: "Kick off work on a specific issue, or let Rig pick the next ready one.",
         examples: [
-          "rig run start 204            # by task/issue id",
-          "rig run start --next         # next ready task by deps/priority",
+          "rig run 204                  # by task/issue id",
+          "rig run --next               # next ready task by deps/priority",
+          "rig run --title 'Fix API' 204 # title override before the task ref",
           "rig run start 204 --force    # dispatch even if a run is already active",
-          "rig run start 204 --model opus-4.8   # override the agent model"
+          "rig run start 204 --model opus-4.8 --prompt 'focus tests'"
         ]
       },
       {
@@ -5592,15 +6086,27 @@ var TOP_LEVEL_SECTIONS = [
       },
       {
         command: "rig run stop <id> [--reason <text>]",
-        description: "Request a graceful stop of a run.",
+        description: "Request a graceful stop of a run (terminal).",
         usecase: "Halt a run that's off-track or no longer needed.",
         examples: ["rig run stop 019ee11f", "rig run stop 019ee11f --reason 'superseded by #210'"]
       },
       {
-        command: "rig run resume|restart <id>",
-        description: "Re-dispatch a task (detached runs start fresh).",
+        command: "rig run pause <id>",
+        description: "Park a live run (running \u2192 paused) without finalizing; the session stays attachable.",
+        usecase: "Hold an autonomous run mid-flight \u2014 free the agent without losing its place.",
+        examples: ["rig run pause 019ee11f"]
+      },
+      {
+        command: "rig run resume <id>",
+        description: "Resume a paused run (paused \u2192 running); the agent continues. A dead/stale run is re-dispatched fresh instead.",
+        usecase: "Un-pause a parked run, or retry a finished one.",
+        examples: ["rig run resume 019ee11f"]
+      },
+      {
+        command: "rig run restart <id>",
+        description: "Re-dispatch a task as a fresh run (new runId, clean runtime).",
         usecase: "Retry a failed/stopped run from a clean slate.",
-        examples: ["rig run restart 019ee11f", "rig run resume 019ee11f"]
+        examples: ["rig run restart 019ee11f"]
       },
       {
         command: "rig run timeline|replay <id>",
@@ -5616,12 +6122,12 @@ var TOP_LEVEL_SECTIONS = [
     subtitle: "github-issues / files task sources feed dispatch",
     commands: [
       {
-        command: "rig task list [--search <t>] [--status <s>]",
+        command: "rig task list [--search <t>] [--state <open|closed>]",
         description: "List tasks from the configured source, with filters.",
         usecase: "Find what's available to dispatch; filter by text or lifecycle status.",
         examples: [
           "rig task list",
-          "rig task list --status open",
+          "rig task list --state open",
           "rig task list --search 'auth'"
         ]
       },
@@ -5633,10 +6139,10 @@ var TOP_LEVEL_SECTIONS = [
         examples: ["rig task show 204", "rig task info 204"]
       },
       {
-        command: "rig task scope|deps|status <id>",
-        description: "Inspect a task's scope globs, dependencies, or lifecycle status.",
+        command: "rig task scope|deps --task <id>; rig task status",
+        description: "Inspect a task's scope globs/dependencies, or show project task status.",
         usecase: "Check what files a run may touch / what's blocking it.",
-        examples: ["rig task scope 204", "rig task deps 204", "rig task status 204"]
+        examples: ["rig task scope --task 204", "rig task deps --task 204", "rig task status"]
       },
       { command: "rig task lookup <term>", description: "Find a task by id/title substring.", examples: ["rig task lookup revoke-invite"] },
       { command: "rig task record \u2026", description: "Write task state/metadata back to the source.", usecase: "Programmatically update task lifecycle from scripts/CI." },
@@ -5689,20 +6195,19 @@ var TOP_LEVEL_SECTIONS = [
     title: "Placement & target \u2014 local vs remote execution",
     subtitle: "where runs execute; the backbone relay/registry is shared",
     commands: [
-      { command: "rig server status", description: "Show the selected placement (local/remote) and project-root link.", examples: ["rig server status"] },
+      { command: "rig server status", description: "Show the selected placement (local/remote) and task source.", examples: ["rig server status"] },
       { command: "rig server list", description: "List configured server targets.", examples: ["rig server list"] },
       {
-        command: "rig server use <alias>",
+        command: "rig server use <local|alias>",
         description: "Select a server target (execution placement).",
         usecase: "Switch a repo between local and a remote host for run execution.",
         examples: ["rig server use local", "rig server use prod-box"]
       },
       {
-        command: "rig server add|remove <alias>",
+        command: "rig server add --alias <alias> --host <host> [--port <n>] | remove <alias>",
         description: "Configure or remove a remote server target.",
-        examples: ["rig server add prod-box ubuntu@host", "rig server remove prod-box"]
+        examples: ["rig server add --alias prod-box --host ubuntu@host", "rig server remove prod-box"]
       },
-      { command: "rig server repair-link", description: "Repair the project-root link for the selected target.", usecase: "Fix a remote that shows unavailable after a host/checkout change.", examples: ["rig server repair-link"] },
       {
         command: "rig remote <list|add|test|status|\u2026>",
         description: "Lower-level remote endpoint management + run control over a remote.",
@@ -5721,10 +6226,10 @@ var TOP_LEVEL_SECTIONS = [
         examples: ["rig inbox approvals", "rig inbox inputs"]
       },
       {
-        command: "rig inbox approve <id> | respond <id> <text>",
-        description: "Approve an entry or answer a user-input prompt.",
-        usecase: "Unblock a paused run from the CLI.",
-        examples: ["rig inbox approve abc123", "rig inbox respond abc123 'use option B'"]
+        command: "rig inbox approve --run <id> --request <id> --decision approve|reject | respond --run <id> --request <id> --text <answer>",
+        description: "Attempt to resolve an approval or answer a user-input prompt; attach if one-shot delivery is unavailable.",
+        usecase: "Resolve pending requests from automation when the live run accepts out-of-band resolution.",
+        examples: ["rig inbox approve --run run1 --request abc123 --decision approve", "rig inbox respond --run run1 --request abc123 --text 'use option B'"]
       },
       { command: "rig inbox watch", description: "Stream inbox changes live.", examples: ["rig inbox watch"] },
       { command: "rig doctor", description: "Cheap health checks: session discovery, registry, selected target, workflow entries.", usecase: "First thing to run when something seems off.", examples: ["rig doctor"] }
@@ -5735,14 +6240,14 @@ var TOP_LEVEL_SECTIONS = [
     subtitle: "logs, artifacts, diffs, failure analysis",
     commands: [
       {
-        command: "rig inspect run-logs|logs --run <id>",
-        description: "Tail a run's process / session logs.",
+        command: "rig inspect run-logs --run <id> | logs --task <id>",
+        description: "Print run/session log lines.",
         usecase: "Debug why a run failed or stalled.",
-        examples: ["rig inspect run-logs --run 019ee11f", "rig inspect logs --run 019ee11f"]
+        examples: ["rig inspect run-logs --run 019ee11f", "rig inspect logs --task 204"]
       },
       { command: "rig inspect runs", description: "List runs from on-disk runtime state.", examples: ["rig inspect runs"] },
-      { command: "rig inspect artifact(s) --task <id>", description: "Inspect a task/run's artifacts.", examples: ["rig inspect artifacts --task 204"] },
-      { command: "rig inspect diff|graph", description: "Run diff / task dependency graph.", examples: ["rig inspect diff", "rig inspect graph"] },
+      { command: "rig inspect artifact --task <id> --file <name> | artifacts --task <id>", description: "Inspect a task/run's artifacts.", examples: ["rig inspect artifacts --task 204", "rig inspect artifact --task 204 --file task-result.json"] },
+      { command: "rig inspect diff --task <id> | graph [--task <id>]", description: "Run diff / task dependency graph.", examples: ["rig inspect diff --task 204", "rig inspect graph --task 204"] },
       { command: "rig inspect failures --task <id>", description: "Classified failure diagnostics for a task's runs.", usecase: "Triage repeated failures on one task.", examples: ["rig inspect failures --task 204"] },
       { command: "rig stats", description: "Aggregate run stats over a window.", examples: ["rig stats", "rig stats --since 7d"] }
     ]
@@ -5783,15 +6288,14 @@ var PRIMARY_GROUPS = [
   {
     name: "server",
     summary: "Compatibility server selector; the product Server target screen lives in Rig Cockpit.",
-    usage: ["rig server <status|list|add|use|repair-link|start> [options]"],
+    usage: ["rig server <status|list|add|use|remove> [options]"],
     commands: [
-      { command: "status", description: "Legacy automation-only: show the selected server and project-root link.", primary: true },
+      { command: "status", description: "Legacy automation-only: show the selected placement and task source.", primary: true },
       { command: "use local", description: "Legacy automation-only: switch this repo to local execution placement.", primary: true },
-      { command: "add <alias> <url>", description: "Legacy automation-only: save a remote server URL.", primary: true },
+      { command: "add --alias <alias> --host <host> [--port <n>]", description: "Legacy automation-only: save a remote execution target.", primary: true },
       { command: "use <alias>", description: "Legacy automation-only: select a remote execution target alias.", primary: true },
-      { command: "repair-link [--prepare|--backfill-only] [--repo owner/repo]", description: "Legacy automation-only: repair a server-host checkout link.", primary: true },
-      { command: "list", description: "Legacy automation-only: list saved local/remote server aliases.", primary: true },
-      { command: "start [--host <host>] [--port <n>]", description: "Legacy diagnostic-only: start a local rig-server process." }
+      { command: "remove <alias>", description: "Legacy automation-only: remove a saved remote execution target.", primary: true },
+      { command: "list", description: "Legacy automation-only: list saved local/remote server aliases.", primary: true }
     ],
     examples: [
       "rig server status        # legacy automation only",
@@ -5807,9 +6311,9 @@ var PRIMARY_GROUPS = [
       { command: "list [--assignee <login|me|@me>] [--state open|closed]", description: "Legacy automation-only: list tasks from the configured source.", primary: true },
       { command: "next [filters]", description: "Legacy automation-only: render the next matching task card.", primary: true },
       { command: "show <id>|--task <id> [--raw]", description: "Legacy automation-only: show a task payload for scripts.", primary: true },
-      { command: "run [#<issue>|<task-id>|--task <id>]", description: "Legacy/fenced: dispatch through the old task-run CLI path; not the task-detail dispatch path.", primary: true },
+      { command: "run [#<issue>|<task-id>|--task <id>] [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>]", description: "Legacy/fenced: dispatch through the CLI run path; not the task-detail dispatch path.", primary: true },
       { command: "ready", description: "Legacy automation-only: list task IDs that old dispatch can run now." },
-      { command: "validate|verify [--task <id>]", description: "Legacy automation-only: run configured task checks/review gates." },
+      { command: "validate|verify [--task <id>]", description: "Legacy automation-only: run configured task checks/review gates; failing checks exit nonzero." },
       { command: "details --task <id>", description: "Legacy automation-only: show full task info from the configured source." },
       { command: "reopen [--task <id> | --all] [--reason <text>]", description: "Legacy automation-only: reopen closed task(s) in the configured source." },
       { command: "artifacts|artifact-dir|artifact-write", description: "Legacy automation-only: inspect or write task artifacts." }
@@ -5817,30 +6321,30 @@ var PRIMARY_GROUPS = [
     examples: [
       "rig task list --assignee @me --limit 20   # legacy automation only",
       "rig task show 123 --raw                   # legacy automation only",
-      "rig task run #123 --runtime-adapter pi    # explicit legacy dispatch only"
+      "rig task run #123 --model opus-4.8 --prompt 'focus tests'"
     ],
     next: ["For normal UX, run bare `rig`, use Cockpit Server/Tasks, then dispatch from Task detail."]
   },
   {
     name: "run",
     summary: "Legacy automation-only run-record inspection; OMP Runs/collab is the live surface.",
-    usage: ["rig run <list|status|show|steer|stop|resume|restart> [options]"],
+    usage: ["rig run [start] <task|#issue|--next> [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>]", "rig run <list|status|show|steer|stop|resume|restart> [options]"],
     commands: [
+      { command: "[start] <task|#issue|--next> [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>]", description: "Legacy automation-only: dispatch a task run through the unified run launcher.", primary: true },
       { command: "list", description: "Legacy automation-only: list old run records from selected server/local state.", primary: true },
       { command: "status", description: "Legacy automation-only: render old active/recent run-record groups; not live OMP status.", primary: true },
       { command: "show <id>|--run <id> [--raw]", description: "Legacy automation-only: show an old run-record payload for scripts.", primary: true },
       { command: "attach <run-id>|--run <id>", description: "Legacy/fenced: not the Rig Cockpit attach path; use OMP Runs or `rig join <link>`.", primary: true },
       { command: "steer <run-id> --message <text>", description: "Legacy automation-only: queue steering into an old live worker.", primary: true },
-      { command: "stop [<run-id>|--run <id>]", description: "Legacy automation-only: request stop for old run records.", primary: true },
-      { command: "resume [<run-id>]", description: "Legacy automation-only: resume an interrupted old run record." },
-      { command: "restart [<run-id>]", description: "Legacy automation-only: re-dispatch an old run from a clean runtime." },
-      { command: "timeline --run <id> [--follow]", description: "Legacy automation-only: stream raw old timeline events." },
-      { command: "replay <run-id>|--run <id> [--with-session]", description: "Legacy automation-only: print an old consolidated run timeline." },
-      { command: "delete|cleanup", description: "Legacy automation-only: remove completed old run records/artifacts." }
+      { command: "stop <run-id>|--run <id> [--reason <text>]", description: "Legacy automation-only: request stop for old run records.", primary: true },
+      { command: "resume <run-id>|--run <id>", description: "Legacy automation-only: resume an interrupted old run record." },
+      { command: "restart <run-id>|--run <id>", description: "Legacy automation-only: re-dispatch an old run from a clean runtime." },
+      { command: "timeline|replay <run-id>|--run <id> [--with-session]", description: "Legacy automation-only: print an old consolidated run timeline." },
+      { command: "delete|cleanup [<run-id>|--run <id>]", description: "Legacy automation-only: remove stale live-registry entries; journals are retained." }
     ],
     examples: [
-      "rig run list          # legacy automation only",
-      "rig run show <run-id> # legacy automation only",
+      "rig run 204          # dispatch task 204",
+      "rig run --title 'Fix API' 204",
       "rig run stop <run-id> # legacy automation only"
     ],
     next: [
@@ -5856,7 +6360,7 @@ var PRIMARY_GROUPS = [
       { command: "approvals [--run <id>] [--task <id>]", description: "Legacy automation-only: list pending approval records.", primary: true },
       { command: "inputs [--run <id>] [--task <id>]", description: "Legacy automation-only: list pending user-input records.", primary: true },
       { command: "approve --run <id> --request <id> --decision approve|reject", description: "Legacy automation-only: resolve an approval record." },
-      { command: "respond --run <id> --request <id> --answer key=value", description: "Legacy automation-only: answer a user-input record." }
+      { command: "respond --run <id> --request <id> --text <answer> | --answer <answer>", description: "Legacy automation-only: answer a user-input record." }
     ],
     examples: [
       "rig inbox approvals # legacy automation only"
@@ -5878,15 +6382,17 @@ var PRIMARY_GROUPS = [
   {
     name: "inspect",
     summary: "Legacy automation-only artifact/log inspection; normal UX is OMP session history.",
-    usage: ["rig inspect <logs|artifacts|failures|graph|audit> --task <id>"],
+    usage: ["rig inspect <logs|artifact|artifacts|run-logs|runs|failures|graph|diff> [options]"],
     commands: [
       { command: "logs --task <id>", description: "Legacy automation-only: latest old run log for a task.", primary: true },
+      { command: "run-logs --run <id>", description: "Legacy automation-only: log lines for a specific run.", primary: true },
+      { command: "runs", description: "Legacy automation-only: list projected runs." },
+      { command: "artifact --task <id> --file <name>", description: "Legacy automation-only: preview one completion artifact." },
       { command: "artifacts --task <id>", description: "Legacy automation-only: list completion artifacts.", primary: true },
+      { command: "diff --task <id>", description: "Legacy automation-only: list task changed files." },
       { command: "failures --task <id>", description: "Legacy automation-only: recorded failures for a task.", primary: true },
-      { command: "graph", description: "Legacy automation-only: task dependency graph." },
-      { command: "audit", description: "Legacy automation-only: controlled-command audit trail." }
+      { command: "graph [--task <id>]", description: "Legacy automation-only: task dependency graph." }
     ],
-    examples: ["rig inspect logs --task <id> # legacy automation only"],
     next: ["For normal UX, use the OMP Runs screen and OMP session history."]
   },
   {