@mp-lb/berth 0.1.1 → 0.1.3

package/dist/berth.js

@@ -5995,7 +5995,7 @@ var require_lib = __commonJS({
 });
 
 // package.json
-var version = "0.1.1";
+var version = "0.1.3";
 
 // src/runAuthCommand.ts
 import { spawn } from "node:child_process";
@@ -22749,9 +22749,6 @@ var runDeliveryCommand = async (args2) => {
   throw new Error("Use berth delivery start, complete, record or schema.");
 };
 
-// src/runInstanceCommand.ts
-import { hostname as hostname4 } from "node:os";
-
 // ../../packages/core/src/work/schemas/slugSchema.ts
 var slugSchema = external_exports.string().trim().min(1).max(80).regex(
   /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
@@ -22968,8 +22965,7 @@ var prepareInstance = async (value) => {
 
 // src/readTaskLaunchContext.ts
 import { realpath as realpath4 } from "node:fs/promises";
-import { homedir as homedir5, hostname as hostname3 } from "node:os";
-import { basename, dirname as dirname3, join as join5 } from "node:path";
+import { hostname as hostname3 } from "node:os";
 
 // ../../packages/core/src/work/inspectPreparedInstance.ts
 import { execFile as execFile3 } from "node:child_process";
@@ -23066,6 +23062,66 @@ var inspectPreparedInstance = async (value) => {
   return { directory, repositories };
 };
 
+// ../../packages/core/src/work/machineIdentity.ts
+import { randomUUID } from "node:crypto";
+import {
+  existsSync as existsSync2,
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { join as join5 } from "node:path";
+var identitySchema = external_exports.object({ id: external_exports.uuid() });
+var machineIdentity = (home = homedir5(), legacyFile) => {
+  const folder = join5(home, ".berth");
+  const path2 = join5(folder, "identity.json");
+  const read2 = () => identitySchema.parse(JSON.parse(readFileSync(path2, "utf8")));
+  if (existsSync2(path2)) return read2();
+  const appData = process.platform === "darwin" ? join5(home, "Library", "Application Support") : process.platform === "win32" ? process.env.APPDATA : join5(home, ".config");
+  const current = appData && join5(appData, "Berth");
+  const legacy = appData && join5(appData, "Factory");
+  const desktopFolder = current && legacy && !existsSync2(current) && existsSync2(legacy) ? legacy : current;
+  const oldFile = legacyFile ?? (desktopFolder ? join5(desktopFolder, "machine-id") : void 0);
+  let id = randomUUID();
+  if (oldFile && existsSync2(oldFile))
+    id = external_exports.uuid().parse(readFileSync(oldFile, "utf8").trim());
+  mkdirSync(folder, { recursive: true, mode: 448 });
+  const temporary = join5(folder, `.identity-${randomUUID()}`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify({ id }, null, 2)}
+`, {
+      mode: 384,
+      flag: "wx"
+    });
+    try {
+      linkSync(temporary, path2);
+    } catch (error51) {
+      if (error51.code !== "EEXIST") throw error51;
+    }
+  } finally {
+    if (existsSync2(temporary)) unlinkSync(temporary);
+  }
+  return read2();
+};
+
+// src/resolveSessionMachine.ts
+var resolveSessionMachine = (config2) => {
+  const { id } = machineIdentity();
+  if (process.env.BERTH_MACHINE_ID && process.env.BERTH_MACHINE_ID !== id)
+    throw new Error(
+      `BERTH_MACHINE_ID does not match this machine's identity (${id}).`
+    );
+  const machine = config2.workMachines.find((item) => item.id === id);
+  if (!machine)
+    throw new Error(
+      `This machine (${id}) is not configured. Configure it in Berth desktop work machine settings.`
+    );
+  return machine;
+};
+
 // src/readTaskLaunchContext.ts
 var readTaskLaunchContext = async (value) => {
   const taskUuid = external_exports.uuid().parse(value);
@@ -23080,29 +23136,8 @@ var readTaskLaunchContext = async (value) => {
     throw new Error("Task project is unavailable.");
   const config2 = await client.config.read.query();
   const osHostname = hostname3();
-  const configuredId = process.env.BERTH_MACHINE_ID;
   const currentCwd = await realpath4(process.cwd()).catch(() => null);
-  const cwdMatches = [];
-  if (!configuredId && currentCwd) {
-    for (const item of config2.workMachines) {
-      const folder = item.instancesFolder === "~" ? homedir5() : item.instancesFolder.startsWith("~/") ? join5(homedir5(), item.instancesFolder.slice(2)) : item.instancesFolder;
-      const root = await realpath4(folder).catch(() => null);
-      if (!root || dirname3(currentCwd) !== root) continue;
-      const registered = await listInstances(item.instancesFolder);
-      if (registered.some(
-        (instance) => instance.taskId === taskUuid && instance.slug === basename(currentCwd)
-      ))
-        cwdMatches.push(item);
-    }
-  }
-  const matches = config2.workMachines.filter(
-    (item) => configuredId ? item.id === configuredId : item.name === osHostname
-  );
-  const machine = configuredId ? matches.length === 1 ? matches[0] : void 0 : cwdMatches.length === 1 ? cwdMatches[0] : cwdMatches.length > 1 ? void 0 : matches.length === 1 ? matches[0] : config2.workMachines.length === 1 ? config2.workMachines[0] : void 0;
-  if (!machine)
-    throw new Error(
-      "Work machine is ambiguous. Set BERTH_MACHINE_ID to a configured machine UUID."
-    );
+  const machine = resolveSessionMachine(config2);
   const all = await listInstances(machine.instancesFolder);
   const linked = all.filter((instance) => instance.taskId === taskUuid);
   if (linked.some((instance) => instance.projectId !== task.projectId))
@@ -23205,14 +23240,7 @@ var runInstanceCommand = async (args2) => {
       `Task ${taskSlug} has no immutable ID; migrate it before linking an instance.`
     );
   const config2 = await client.config.read.query();
-  const matches = config2.workMachines.filter(
-    (machine2) => machine2.id === process.env.BERTH_MACHINE_ID || !process.env.BERTH_MACHINE_ID && machine2.name === hostname4()
-  );
-  const machine = matches.length === 1 ? matches[0] : !process.env.BERTH_MACHINE_ID && config2.workMachines.length === 1 ? config2.workMachines[0] : void 0;
-  if (!machine)
-    throw new Error(
-      "Configure a work machine for this hostname, or set BERTH_MACHINE_ID to select one."
-    );
+  const machine = resolveSessionMachine(config2);
   return prepareInstance({
     projectId: project.id,
     slug,
@@ -23223,6 +23251,36 @@ var runInstanceCommand = async (args2) => {
   });
 };
 
+// ../../packages/core/src/work/schemas/messageEventSchema.ts
+var messageEventSchema = external_exports.strictObject({
+  at: external_exports.iso.datetime(),
+  actor: external_exports.string().trim().min(1).nullable(),
+  action: external_exports.enum([
+    "assigned",
+    "commented",
+    "closed",
+    "reopened",
+    "requested",
+    "approved",
+    "rejected",
+    "deferred",
+    "restored"
+  ]),
+  assignee: external_exports.string().trim().min(1).nullable().optional(),
+  request: external_exports.strictObject({
+    summary: external_exports.string(),
+    evidence: external_exports.string(),
+    deliveryAttemptId: external_exports.string().nullable()
+  }).optional(),
+  note: external_exports.string().trim().max(8e3).optional()
+});
+
+// ../../packages/core/src/work/schemas/messageAppendSchema.ts
+var messageAppendSchema = messageEventSchema.omit({ at: true, request: true }).extend({
+  id: external_exports.string().min(1),
+  expectedLength: external_exports.number().int().nonnegative()
+});
+
 // ../../packages/core/src/work/schemas/messageTypeSchema.ts
 var messageTypeSchema = external_exports.string().trim().min(1).max(100).regex(/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/);
 
@@ -23247,6 +23305,7 @@ var messageListSchema = external_exports.strictObject({
 // ../../packages/core/src/work/schemas/messageCreateSchema.ts
 var messageCreateSchema = external_exports.strictObject({
   recipient: messageRecipientSchema,
+  sender: external_exports.string().trim().min(1).nullable().default(null),
   type: messageTypeSchema.default("message"),
   priority: external_exports.number().int().default(0),
   projectId: slugSchema.nullable(),
@@ -23255,14 +23314,149 @@ var messageCreateSchema = external_exports.strictObject({
   body: external_exports.string().trim().min(1).max(8e3)
 });
 
+// ../../packages/core/src/work/schemas/workerSchema.ts
+var workerSchema = external_exports.strictObject({
+  threadId: external_exports.string().trim().min(1).max(200).describe("Stable worker thread ID."),
+  host: external_exports.string().trim().min(1).max(200).describe("Host identifier for the worker thread, such as local.")
+}).describe(
+  "Structured worker destination; an identifier is not authentication or credential approval."
+);
+
+// ../../packages/core/src/work/schemas/blockerHandoffReceiptSchema.ts
+var blockerHandoffReceiptSchema = external_exports.strictObject({
+  updateCount: external_exports.number().int().positive().describe(
+    "Blocker update-log length identifying the original unblocked cycle."
+  ),
+  consumer: slugSchema.describe("Controller that reserved this cycle."),
+  worker: workerSchema,
+  reservedAt: external_exports.iso.datetime().describe("Time the reservation was saved."),
+  delivery: external_exports.strictObject({
+    receiptId: external_exports.string().trim().min(1).max(200).describe("External admitted turn or delivery receipt ID."),
+    confirmedAt: external_exports.iso.datetime().describe("Time delivery was recorded."),
+    sourceUpdateId: external_exports.uuid().optional().describe(
+      "Existing informational update used to import a historical receipt."
+    )
+  }).nullable().describe(
+    "Null means delivery is uncertain or pending; reconcile before sending. A populated delivery must not be resent."
+  )
+}).describe(
+  "Durable handoff receipt keyed by blocker update cycle; retained when reblocked."
+);
+
+// ../../packages/core/src/work/schemas/blockerEventSchema.ts
+var blockerEventSchema = external_exports.strictObject({
+  state: external_exports.enum(["blocked", "unblocked"]).describe(
+    "blocked is recorded by controller; unblocked is recorded by user."
+  ),
+  notes: external_exports.string().max(4e3).describe("Feedback or resolution notes for this change. Markdown.")
+}).describe(
+  "An append-only update in the blocker\u2019s embedded log, oldest first."
+);
+
 // ../../packages/core/src/work/schemas/messageStatusSchema.ts
 var messageStatusSchema = external_exports.enum(["active", "later", "unblocked", "archived"]).describe(
   "Message lifecycle: active, later, unblocked or archived. Berth applies no type-specific transitions."
 );
 
+// ../../packages/core/src/work/schemas/blockerStatusSchema.ts
+var blockerStatusSchema = messageStatusSchema.describe(
+  "active: user queue; later: deferred, still blocking; unblocked: resolved by the user, awaiting controller acknowledgment (whether claimed or not); archived: acknowledged. Use queue commands to transition."
+);
+
+// ../../packages/core/src/work/schemas/blockerBaseSchema.ts
+var blockerBaseSchema = external_exports.strictObject({
+  id: external_exports.uuid().describe(
+    "Immutable UUID generated by the server when this item is created."
+  ),
+  taskSlug: taskSlugSchema.describe(
+    "The existing task this blocker belongs to."
+  ),
+  status: blockerStatusSchema,
+  updates: external_exports.array(blockerEventSchema).min(1).describe(
+    "Embedded state change log, oldest first. Appended only by state-transition commands."
+  ),
+  handoffs: external_exports.array(blockerHandoffReceiptSchema).default([]).describe(
+    "Durable diagnostics handoffs, one per unblocked update cycle."
+  ),
+  createdAt: external_exports.iso.datetime().nullable().describe(
+    "Creation time in UTC, or null for imported records whose time is unknown."
+  ),
+  completedAt: external_exports.iso.datetime().nullable().describe(
+    "Time the user marked unblocked; null before unblocking or for legacy completions."
+  ),
+  acknowledgedAt: external_exports.iso.datetime().nullable().describe(
+    "Time the consumer acknowledged the item, or null before acknowledgment."
+  ),
+  dismissedAt: external_exports.iso.datetime().nullable().optional().describe(
+    "Time the user hid this pending-review cycle from the web inbox; controller acknowledgment is independent."
+  ),
+  consumer: slugSchema.nullable().describe(
+    "Controller consumer owning this acknowledgment queue item. Set atomically by pull; null before pulling."
+  ),
+  outcome: external_exports.string().max(4e3).describe(
+    "User completion note or legacy resolution; may be empty. Markdown."
+  ),
+  selectedOptionIndex: external_exports.number().int().min(-1).nullable().describe(
+    "Zero-based chosen decision option, or -1 for None of the above. Null for actions or decisions without a recorded choice."
+  )
+}).describe(
+  "Server-managed identity, queue state and completion receipt for a blocker."
+);
+
+// ../../packages/core/src/work/schemas/prioritySchema.ts
+var prioritySchema = external_exports.enum(["high", "medium", "low", "unset"]).describe("Priority: high, medium, low, or unset when not assigned.");
+
+// ../../packages/core/src/work/schemas/decisionOptionSchema.ts
+var decisionOptionSchema = external_exports.strictObject({
+  title: external_exports.string().trim().min(1).max(120).describe("Short name for this choice."),
+  body: external_exports.string().trim().min(1).max(4e3).describe(
+    "Explain this option, its consequences and tradeoffs. Markdown."
+  ),
+  priority: prioritySchema.describe(
+    "Preference for this option: high, medium, low or unset. High is the strongest recommendation."
+  )
+}).describe("One selectable option in a decision.");
+
+// ../../packages/core/src/work/schemas/decisionSchema.ts
+var decisionSchema = external_exports.strictObject({
+  background: external_exports.string().trim().min(1).max(4e3).describe("Context the user needs to understand the decision. Markdown."),
+  problem: external_exports.string().trim().min(1).max(4e3).describe("The problem or question that needs a decision. Markdown."),
+  options: external_exports.array(decisionOptionSchema).max(12).describe(
+    "Predefined choices presented to the user. The UI always adds None of the above; do not include it in this array. New decisions require at least one option; legacy decisions may have none. Completion records the chosen index or -1 for None of the above."
+  )
+}).describe("Decision content: background, problem, and prioritized options.");
+
+// ../../packages/core/src/work/schemas/actionSchema.ts
+var actionSchema = external_exports.strictObject({
+  background: external_exports.string().trim().min(1).max(4e3).describe("Context explaining why this action is needed. Markdown."),
+  instructions: external_exports.string().trim().min(1).max(6e3).describe(
+    "Concrete instructions for the user to carry out before marking done. Markdown."
+  )
+}).describe("Action content: background and instructions.");
+
+// ../../packages/core/src/work/schemas/blockerSchema.ts
+var blockerSchema = external_exports.discriminatedUnion("type", [
+  blockerBaseSchema.extend({
+    ...decisionSchema.shape,
+    type: external_exports.literal("decision").describe(
+      "A one-time decision. Once submitted its choice is final; create a new decision for a new question."
+    )
+  }),
+  blockerBaseSchema.extend({
+    ...actionSchema.shape,
+    type: external_exports.literal("action").describe(
+      "An action requiring instructions to be carried out. It may be returned with feedback and actioned again."
+    )
+  })
+]).describe(
+  "A typed blocker and its queue lifecycle. Completed content is immutable until archived so consumers receive stable results."
+);
+
 // ../../packages/core/src/work/schemas/messageSchema.ts
 var messageSchema = external_exports.strictObject({
   id: external_exports.string(),
+  sender: external_exports.string().min(1).nullable().optional(),
+  timeline: external_exports.array(messageEventSchema).optional(),
   type: messageTypeSchema,
   recipient: messageRecipientSchema,
   priority: external_exports.number().int(),
@@ -23274,7 +23468,8 @@ var messageSchema = external_exports.strictObject({
   status: messageStatusSchema,
   claimedAt: external_exports.iso.datetime().nullable(),
   consumer: external_exports.string().nullable(),
-  sourceId: external_exports.string()
+  sourceId: external_exports.string(),
+  blocker: blockerSchema.optional()
 });
 
 // ../../packages/core/src/work/schemas/messageUpdateSchema.ts
@@ -23295,28 +23490,33 @@ var runMessageCommand = async (args2) => {
   if (extra.length) throw new Error("Quote the JSON payload as one argument.");
   if (action === "schema") {
     const schemas = {
+      append: messageAppendSchema,
       create: messageCreateSchema,
       update: messageUpdateSchema,
       list: messageListSchema
     };
     const key = input ?? "create";
-    if (key !== "create" && key !== "update" && key !== "list")
-      throw new Error("Choose create, update or list schema.");
+    if (key !== "append" && key !== "create" && key !== "update" && key !== "list")
+      throw new Error("Choose create, update, append or list schema.");
     return external_exports.toJSONSchema(schemas[key], { io: "input" });
   }
   const api = createWorkClient().message;
   if (action === "types" && input === void 0) return api.types.query();
+  if (action === "read" && typeof input === "string")
+    return api.read.query(input);
   const payload = input === void 0 ? void 0 : JSON.parse(input);
   if (action === "list")
     return api.list.query(messageListSchema.optional().parse(payload));
   if (action === "read" && typeof input === "string")
     return api.read.query(input);
+  if (action === "append")
+    return api.append.mutate(messageAppendSchema.parse(payload));
   if (action === "create")
     return api.create.mutate(messageCreateSchema.parse(payload));
   if (action === "update")
     return api.update.mutate(messageUpdateSchema.parse(payload));
   throw new Error(
-    "Messages support types, create, update, read, list and schema."
+    "Messages support types, create, update, append, read, list and schema."
   );
 };
 
@@ -23463,9 +23663,6 @@ var projectReleaseTargetSchema = external_exports.strictObject({
   "One independently released part of a project: its icon, name, and URL."
 );
 
-// ../../packages/core/src/work/schemas/prioritySchema.ts
-var prioritySchema = external_exports.enum(["high", "medium", "low", "unset"]).describe("Priority: high, medium, low, or unset when not assigned.");
-
 // ../../packages/core/src/work/schemas/projectRepoSchema.ts
 var projectRepoSchema = external_exports.strictObject({
   url: linkSchema.refine((url2) => url2.length > 0, "Enter a repo URL."),
@@ -23691,14 +23888,6 @@ var taskSignOffSchema = external_exports.strictObject({
   "User sign-off for a task. Set only through the sign-off endpoint, never through task CRUD."
 );
 
-// ../../packages/core/src/work/schemas/workerSchema.ts
-var workerSchema = external_exports.strictObject({
-  threadId: external_exports.string().trim().min(1).max(200).describe("Stable worker thread ID."),
-  host: external_exports.string().trim().min(1).max(200).describe("Host identifier for the worker thread, such as local.")
-}).describe(
-  "Structured worker destination; an identifier is not authentication or credential approval."
-);
-
 // ../../packages/core/src/work/schemas/terminalWorkerSchema.ts
 var terminalWorkerSchema = external_exports.strictObject({
   sessionId: external_exports.uuid().describe("Berth terminal session UUID."),
@@ -23913,6 +24102,22 @@ var runPromptCommand = async (args2) => {
   );
 };
 
+// ../../packages/core/src/work/data/getSessionRecoveryProblem.ts
+var getSessionRecoveryProblem = (session, task) => {
+  if (!task || session.taskId !== task.uuid || task.status !== "working" || task.archivedAt)
+    return "Task is not in the working column.";
+  if (task.workerRun?.completedAt)
+    return "This worker has already completed its work.";
+  const owner = task.ownership?.worker;
+  if (owner && (!("sessionId" in owner) || owner.sessionId !== session.id || owner.machineId !== session.machineId))
+    return "Task is assigned to another worker.";
+  if (task.workerId && task.workerId !== session.workerSessionId)
+    return "Task is assigned to another worker.";
+  if (session.endedAt || !session.startedAt)
+    return "Session is not an unexpectedly exited session.";
+  return null;
+};
+
 // ../../packages/core/src/work/data/renderAgentPrompt.ts
 var import_handlebars = __toESM(require_lib(), 1);
 
@@ -23932,7 +24137,7 @@ var renderAgentPrompt = (prompts, key, variables) => import_handlebars.default.c
 })(variables);
 
 // src/runSessionCommand.ts
-import { setTimeout as delay2 } from "node:timers/promises";
+import { setTimeout as delay3 } from "node:timers/promises";
 import { realpathSync } from "node:fs";
 import { homedir as homedir6 } from "node:os";
 import { join as join6 } from "node:path";
@@ -23990,56 +24195,8 @@ var findWorkerType = (types, id) => {
   return type;
 };
 
-// ../../packages/core/src/work/data/resolveDefaultWorkerTypeId.ts
-var resolveDefaultWorkerTypeId = (types, current) => types.some((type) => type.id === current) ? current : types[0]?.id ?? null;
-
-// src/prepareTaskWorkerInstance.ts
-var prepareTaskWorkerInstance = async (taskId, instanceSlug) => {
-  external_exports.uuid().parse(taskId);
-  const config2 = await createWorkClient().config.read.query();
-  const workerTypeId = resolveDefaultWorkerTypeId(
-    config2.workerTypes ?? [],
-    config2.defaultWorkerTypeId
-  );
-  if (!workerTypeId) throw new Error("Configure a default worker type first.");
-  findWorkerType(config2.workerTypes ?? [], workerTypeId);
-  const context = await readTaskLaunchContext(taskId);
-  if (!["draft", "queue"].includes(context.task.status))
-    throw new Error(
-      "Only an unstarted Draft or Queue task can start a worker."
-    );
-  if (context.task.blocked || context.task.ownership?.worker || context.task.workerId)
-    throw new Error("Task is blocked or already assigned to a worker.");
-  if (context.state === "missing_instance") {
-    if (!context.project) throw new Error("Task has no project to prepare.");
-    await runInstanceCommand([
-      "prepare",
-      "--project",
-      context.project.id,
-      "--task",
-      context.task.slug,
-      ...instanceSlug ? ["--slug", instanceSlug] : []
-    ]);
-  } else if (context.state !== "ready") {
-    throw new Error(`Task instance is ${context.state}; cannot start worker.`);
-  }
-  return workerTypeId;
-};
-
-// src/resolveSessionMachine.ts
-import { hostname as hostname5 } from "node:os";
-var resolveSessionMachine = (config2) => {
-  const configured = process.env.BERTH_MACHINE_ID;
-  const matches = config2.workMachines.filter(
-    (item) => configured ? item.id === configured : item.name === hostname5()
-  );
-  const machine = matches.length === 1 ? matches[0] : !configured && config2.workMachines.length === 1 ? config2.workMachines[0] : void 0;
-  if (!machine)
-    throw new Error(
-      "Work machine is ambiguous. Set BERTH_MACHINE_ID to a configured machine UUID."
-    );
-  return machine;
-};
+// src/recoverTerminalSession.ts
+import { setTimeout as delay2 } from "node:timers/promises";
 
 // src/tmuxSession.ts
 import { spawnSync } from "node:child_process";
@@ -24122,6 +24279,79 @@ var attachTmuxSession = (name) => {
     throw new Error("Could not attach to the tmux session.");
 };
 
+// src/recoverTerminalSession.ts
+var recoverTerminalSession = async (session, worker) => {
+  if (session.endedAt || !session.startedAt)
+    throw new Error("Session is not an unexpectedly exited session.");
+  if (tmuxSessionExists(session.terminalSessionId))
+    throw new Error("Session is already running.");
+  if (session.workerTypeId !== "shell" && (!worker?.resumeCommand || !session.workerSessionId))
+    throw new Error(
+      "Worker has no configured resume command or conversation ID."
+    );
+  if (worker && !/{{\s*prompt\s*}}/.test(worker.resumeCommand))
+    throw new Error("Resume command must include {{prompt}} to continue work.");
+  if (worker && !/{{\s*workerSessionId\s*}}/.test(worker.resumeCommand))
+    throw new Error(
+      "Resume command must include {{workerSessionId}} to resume the original conversation."
+    );
+  const command = worker ? renderWorkerCommand(worker.resumeCommand, {
+    prompt: `Your terminal was interrupted. Review task ${session.taskId ?? ""} and your prior progress, then continue working. Respect any existing blockers and do not repeat completed actions.`,
+    sessionId: session.id,
+    workerSessionId: session.workerSessionId ?? "",
+    taskId: session.taskId ?? "",
+    directory: session.directory,
+    terminalSessionId: session.terminalSessionId
+  }) : null;
+  startTmuxSession(
+    session.terminalSessionId,
+    session.directory,
+    command,
+    session.id,
+    session.machineId
+  );
+  await delay2(250);
+  if (!tmuxSessionExists(session.terminalSessionId))
+    throw new Error("Worker exited immediately after recovery.");
+  return { id: session.id, recovered: true };
+};
+
+// ../../packages/core/src/work/data/resolveDefaultWorkerTypeId.ts
+var resolveDefaultWorkerTypeId = (types, current) => types.some((type) => type.id === current) ? current : types[0]?.id ?? null;
+
+// src/prepareTaskWorkerInstance.ts
+var prepareTaskWorkerInstance = async (taskId, instanceSlug) => {
+  external_exports.uuid().parse(taskId);
+  const config2 = await createWorkClient().config.read.query();
+  const workerTypeId = resolveDefaultWorkerTypeId(
+    config2.workerTypes ?? [],
+    config2.defaultWorkerTypeId
+  );
+  if (!workerTypeId) throw new Error("Configure a default worker type first.");
+  findWorkerType(config2.workerTypes ?? [], workerTypeId);
+  const context = await readTaskLaunchContext(taskId);
+  if (!["draft", "queue"].includes(context.task.status))
+    throw new Error(
+      "Only an unstarted Draft or Queue task can start a worker."
+    );
+  if (context.task.blocked || context.task.ownership?.worker || context.task.workerId)
+    throw new Error("Task is blocked or already assigned to a worker.");
+  if (context.state === "missing_instance") {
+    if (!context.project) throw new Error("Task has no project to prepare.");
+    await runInstanceCommand([
+      "prepare",
+      "--project",
+      context.project.id,
+      "--task",
+      context.task.slug,
+      ...instanceSlug ? ["--slug", instanceSlug] : []
+    ]);
+  } else if (context.state !== "ready") {
+    throw new Error(`Task instance is ${context.state}; cannot start worker.`);
+  }
+  return workerTypeId;
+};
+
 // src/runSessionCommand.ts
 var runSessionCommand = async (args2) => {
   const [action, value, agentValue, instanceSlug, ...extra] = args2;
@@ -24147,6 +24377,27 @@ var runSessionCommand = async (args2) => {
       live: session.machineId === machine.id ? tmuxSessionExists(session.terminalSessionId) : null
     };
   }
+  if (action === "recover" && value && !agentValue) {
+    const session = await client.terminalSession.read.query(
+      external_exports.uuid().parse(value)
+    );
+    const config2 = await client.config.read.query();
+    const machine = resolveSessionMachine(config2);
+    if (session.machineId !== machine.id)
+      throw new Error("Session belongs to another work machine.");
+    if (!session.taskId)
+      throw new Error("Only task sessions can be recovered.");
+    const tasks = await client.task.list.query({ status: "working" });
+    const problem = getSessionRecoveryProblem(
+      session,
+      tasks.find((task) => task.uuid === session.taskId)
+    );
+    if (problem) throw new Error(problem);
+    return recoverTerminalSession(
+      session,
+      session.workerTypeId === "shell" ? null : findWorkerType(config2.workerTypes ?? [], session.workerTypeId)
+    );
+  }
   if (action === "attach" && value && !agentValue) {
     const session = await client.terminalSession.read.query(
       external_exports.uuid().parse(value)
@@ -24218,7 +24469,7 @@ var runSessionCommand = async (args2) => {
         session.id,
         machine.id
       );
-      await delay2(250);
+      await delay3(250);
       if (!tmuxSessionExists(session.terminalSessionId))
         throw new Error("Agent process exited immediately after launch.");
       return client.terminalSession.update.mutate({
@@ -24324,7 +24575,7 @@ var runSessionCommand = async (args2) => {
         session.id,
         context.machine.id
       );
-      await delay2(250);
+      await delay3(250);
       if (!tmuxSessionExists(session.terminalSessionId))
         throw new Error("Agent process exited immediately after launch.");
     } catch (error51) {
@@ -24343,7 +24594,7 @@ var runSessionCommand = async (args2) => {
     });
   }
   throw new Error(
-    "Use berth session list|read|status|create|start|launch|attach|kill|delete|register|schema. Run berth --help."
+    "Use berth session list|read|status|create|start|launch|recover|attach|kill|delete|register|schema. Run berth --help."
   );
 };
 
@@ -24437,6 +24688,9 @@ var runRoleCommand = async (args2) => {
 // ../../packages/core/src/work/schemas/signOffRequestSchema.ts
 var signOffRequestSchema = external_exports.strictObject({
   slug: taskSlugSchema,
+  sender: external_exports.string().trim().min(1).optional().describe(
+    "Requesting role within the project; defaults to delivery-owner."
+  ),
   deliveryAttemptId: external_exports.uuid().optional().describe(
     "Latest recorded delivery attempt; omitted selects latest. Legacy issued requests remain valid without an attempt."
   ),
@@ -24448,128 +24702,6 @@ var signOffRequestSchema = external_exports.strictObject({
   )
 });
 
-// ../../packages/core/src/work/schemas/blockerHandoffReceiptSchema.ts
-var blockerHandoffReceiptSchema = external_exports.strictObject({
-  updateCount: external_exports.number().int().positive().describe(
-    "Blocker update-log length identifying the original unblocked cycle."
-  ),
-  consumer: slugSchema.describe("Controller that reserved this cycle."),
-  worker: workerSchema,
-  reservedAt: external_exports.iso.datetime().describe("Time the reservation was saved."),
-  delivery: external_exports.strictObject({
-    receiptId: external_exports.string().trim().min(1).max(200).describe("External admitted turn or delivery receipt ID."),
-    confirmedAt: external_exports.iso.datetime().describe("Time delivery was recorded."),
-    sourceUpdateId: external_exports.uuid().optional().describe(
-      "Existing informational update used to import a historical receipt."
-    )
-  }).nullable().describe(
-    "Null means delivery is uncertain or pending; reconcile before sending. A populated delivery must not be resent."
-  )
-}).describe(
-  "Durable handoff receipt keyed by blocker update cycle; retained when reblocked."
-);
-
-// ../../packages/core/src/work/schemas/blockerEventSchema.ts
-var blockerEventSchema = external_exports.strictObject({
-  state: external_exports.enum(["blocked", "unblocked"]).describe(
-    "blocked is recorded by controller; unblocked is recorded by user."
-  ),
-  notes: external_exports.string().max(4e3).describe("Feedback or resolution notes for this change. Markdown.")
-}).describe(
-  "An append-only update in the blocker\u2019s embedded log, oldest first."
-);
-
-// ../../packages/core/src/work/schemas/blockerStatusSchema.ts
-var blockerStatusSchema = messageStatusSchema.describe(
-  "active: user queue; later: deferred, still blocking; unblocked: resolved by the user, awaiting controller acknowledgment (whether claimed or not); archived: acknowledged. Use queue commands to transition."
-);
-
-// ../../packages/core/src/work/schemas/blockerBaseSchema.ts
-var blockerBaseSchema = external_exports.strictObject({
-  id: external_exports.uuid().describe(
-    "Immutable UUID generated by the server when this item is created."
-  ),
-  taskSlug: taskSlugSchema.describe(
-    "The existing task this blocker belongs to."
-  ),
-  status: blockerStatusSchema,
-  updates: external_exports.array(blockerEventSchema).min(1).describe(
-    "Embedded state change log, oldest first. Appended only by state-transition commands."
-  ),
-  handoffs: external_exports.array(blockerHandoffReceiptSchema).default([]).describe(
-    "Durable diagnostics handoffs, one per unblocked update cycle."
-  ),
-  createdAt: external_exports.iso.datetime().nullable().describe(
-    "Creation time in UTC, or null for imported records whose time is unknown."
-  ),
-  completedAt: external_exports.iso.datetime().nullable().describe(
-    "Time the user marked unblocked; null before unblocking or for legacy completions."
-  ),
-  acknowledgedAt: external_exports.iso.datetime().nullable().describe(
-    "Time the consumer acknowledged the item, or null before acknowledgment."
-  ),
-  dismissedAt: external_exports.iso.datetime().nullable().optional().describe(
-    "Time the user hid this pending-review cycle from the web inbox; controller acknowledgment is independent."
-  ),
-  consumer: slugSchema.nullable().describe(
-    "Controller consumer owning this acknowledgment queue item. Set atomically by pull; null before pulling."
-  ),
-  outcome: external_exports.string().max(4e3).describe(
-    "User completion note or legacy resolution; may be empty. Markdown."
-  ),
-  selectedOptionIndex: external_exports.number().int().min(-1).nullable().describe(
-    "Zero-based chosen decision option, or -1 for None of the above. Null for actions or decisions without a recorded choice."
-  )
-}).describe(
-  "Server-managed identity, queue state and completion receipt for a blocker."
-);
-
-// ../../packages/core/src/work/schemas/decisionOptionSchema.ts
-var decisionOptionSchema = external_exports.strictObject({
-  title: external_exports.string().trim().min(1).max(120).describe("Short name for this choice."),
-  body: external_exports.string().trim().min(1).max(4e3).describe(
-    "Explain this option, its consequences and tradeoffs. Markdown."
-  ),
-  priority: prioritySchema.describe(
-    "Preference for this option: high, medium, low or unset. High is the strongest recommendation."
-  )
-}).describe("One selectable option in a decision.");
-
-// ../../packages/core/src/work/schemas/decisionSchema.ts
-var decisionSchema = external_exports.strictObject({
-  background: external_exports.string().trim().min(1).max(4e3).describe("Context the user needs to understand the decision. Markdown."),
-  problem: external_exports.string().trim().min(1).max(4e3).describe("The problem or question that needs a decision. Markdown."),
-  options: external_exports.array(decisionOptionSchema).max(12).describe(
-    "Predefined choices presented to the user. The UI always adds None of the above; do not include it in this array. New decisions require at least one option; legacy decisions may have none. Completion records the chosen index or -1 for None of the above."
-  )
-}).describe("Decision content: background, problem, and prioritized options.");
-
-// ../../packages/core/src/work/schemas/actionSchema.ts
-var actionSchema = external_exports.strictObject({
-  background: external_exports.string().trim().min(1).max(4e3).describe("Context explaining why this action is needed. Markdown."),
-  instructions: external_exports.string().trim().min(1).max(6e3).describe(
-    "Concrete instructions for the user to carry out before marking done. Markdown."
-  )
-}).describe("Action content: background and instructions.");
-
-// ../../packages/core/src/work/schemas/blockerSchema.ts
-var blockerSchema = external_exports.discriminatedUnion("type", [
-  blockerBaseSchema.extend({
-    ...decisionSchema.shape,
-    type: external_exports.literal("decision").describe(
-      "A one-time decision. Once submitted its choice is final; create a new decision for a new question."
-    )
-  }),
-  blockerBaseSchema.extend({
-    ...actionSchema.shape,
-    type: external_exports.literal("action").describe(
-      "An action requiring instructions to be carried out. It may be returned with feedback and actioned again."
-    )
-  })
-]).describe(
-  "A typed blocker and its queue lifecycle. Completed content is immutable until archived so consumers receive stable results."
-);
-
 // ../../packages/core/src/work/schemas/blockerPollSchema.ts
 var blockerPollSchema = external_exports.strictObject({
   id: external_exports.uuid(),
@@ -25209,6 +25341,7 @@ berth session status <session-uuid>
 berth session create [shell|worker-type-id] [directory]
 berth session start <task-uuid> [instance-slug]
 berth session launch <task-uuid> <worker-type-id> [instance-slug]
+berth session recover <session-uuid>
 berth session attach <session-uuid>
 berth session kill <session-uuid>
 berth session delete <session-uuid>
@@ -25235,7 +25368,8 @@ berth message create '{"recipient":{"name":"delivery-owner","projectId":"bond"},
 berth message update '{"id":"<message-id>","recipient":{"name":"delivery-owner","projectId":"bond"}}'
 berth message read <message-id>
 berth message list '{"recipient":{"name":"delivery-owner","projectId":"bond"}}'
-berth message schema [create|update|list]
+berth message append '{"id":"<message-id>","expectedLength":1,"actor":"delivery-owner","action":"closed"}'
+berth message schema [create|update|append|list]
 Messages are stored records. Recipient, type, priority and status are independent.
 List includes stored messages; deleting one never deletes its task or blocker.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mp-lb/berth",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "bin": {