mulmoclaude 0.6.2 → 0.6.4

package/server/encore/handlers/recordValues.ts

@@ -0,0 +1,44 @@
+// `recordValues` handler — record form values against a target
+// without closing any step, then reconcile.
+
+import { z } from "zod";
+
+import { applyValues } from "../cycle.js";
+import { log } from "../../system/logger/index.js";
+import { assertKnownTargetAndStep, loadCycle, loadDsl, persistAndReconcile, workspaceRelativePath, type EncoreDispatchResult } from "./shared.js";
+
+export const RecordValuesArgs = z.object({
+  kind: z.literal("recordValues"),
+  obligationId: z.string().trim().min(1),
+  cycleId: z.string().trim().min(1),
+  targetId: z.string().trim().min(1),
+  values: z.record(z.string(), z.unknown()),
+  pendingId: z.string().trim().min(1).optional(),
+});
+
+export async function handleRecordValues(args: z.infer<typeof RecordValuesArgs>): Promise<EncoreDispatchResult> {
+  const dsl = await loadDsl(args.obligationId);
+  assertKnownTargetAndStep(dsl, args);
+  const { rel, state, body } = await loadCycle(args.obligationId, args.cycleId);
+  const nextState = applyValues(state, args.targetId, args.values);
+  // recordValues never closes anything, so the reconciler is a no-op
+  // for bells — but we still funnel through `persistAndReconcile`
+  // for uniformity (no special-case handler shape). The reconciler
+  // is cheap when nothing changed: Phase 1 sees the same live targets,
+  // Phase 2 sees the same covered keys, no notifier calls.
+  await persistAndReconcile(rel, nextState, body, args.obligationId, args.cycleId);
+  log.info("encore", "recordValues: values recorded", {
+    obligationId: args.obligationId,
+    cycleId: args.cycleId,
+    targetId: args.targetId,
+    keys: Object.keys(args.values),
+  });
+  return {
+    ok: true,
+    message: `Encore: recorded ${Object.keys(args.values).length} value(s) on ${args.targetId} in cycle ${args.cycleId}.`,
+    obligationId: args.obligationId,
+    cycleId: args.cycleId,
+    targetId: args.targetId,
+    cyclePath: workspaceRelativePath(rel),
+  };
+}

package/server/encore/handlers/resolveNotification.ts

@@ -0,0 +1,121 @@
+// `resolveNotification` handler — handle the bell-click path. Seeds
+// a fresh chat session for an active ticket, or clears an orphan
+// bell entry whose ticket was already swept.
+//
+// DOCUMENTED EXCEPTION to the reconciler-owns-the-bell rule:
+// `handleOrphanResolve` calls `encoreNotifier.clear` directly because
+// there's no ticket to reconcile against. See server/encore/INVARIANTS.md.
+
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+
+import { ticketPath } from "../paths.js";
+import { readTextOrNull, writeText } from "../../utils/files/encore-io.js";
+import * as encoreNotifier from "../notifier.js";
+import { ENCORE_PLUGIN_PKG } from "../notifier.js";
+import { startChat } from "../../api/routes/agent.js";
+import { PLUGIN_SESSION_ORIGIN_PREFIX } from "../../../src/types/session.js";
+import { ENCORE_SEED_ROLE_ID } from "../../../src/config/roles.js";
+import { log } from "../../system/logger/index.js";
+import type { Ticket } from "../tick.js";
+import { EncoreError, type EncoreDispatchResult } from "./shared.js";
+
+export const ResolveNotificationArgs = z.object({
+  kind: z.literal("resolveNotification"),
+  pendingId: z.string(),
+  /** Bell entry id, spliced onto the navigateTarget at click time
+   *  by the host's NotificationBell.vue. Lets us clear orphan bell
+   *  entries whose ticket was already swept. */
+  notificationId: z.string().optional(),
+});
+
+async function handleOrphanResolve(args: z.infer<typeof ResolveNotificationArgs>): Promise<EncoreDispatchResult> {
+  // The ticket was already swept (e.g. the LLM resolved the
+  // obligation in another chat before this click). Clear the bell
+  // entry so it disappears.
+  //
+  // DOCUMENTED EXCEPTION to the reconciler-owns-the-bell rule:
+  // there's no ticket to reconcile against, so the reconciler can't
+  // know the bell entry exists. Direct clear is the only way out.
+  let cleared = false;
+  if (args.notificationId) {
+    try {
+      await encoreNotifier.clear(args.notificationId);
+      cleared = true;
+    } catch (err) {
+      log.warn("encore", "resolveNotification: orphan clear failed", {
+        notificationId: args.notificationId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  // Distinguish three outcomes in the message so the caller can tell
+  // whether action is still needed: cleared, no-id-to-clear-against,
+  // or clear attempted but failed (warning was logged).
+  const message = orphanMessage(cleared, args.notificationId !== undefined);
+  return {
+    ok: false,
+    orphan: true,
+    message,
+    error: "ticket not found",
+    cleared,
+  };
+}
+
+function orphanMessage(cleared: boolean, hadNotificationId: boolean): string {
+  const head = "Encore: this notification has already been resolved (the ticket is gone).";
+  if (cleared) return `${head} Bell entry cleared.`;
+  if (hadNotificationId) return `${head} Bell entry clear was attempted but failed; the bell may still be visible.`;
+  return head;
+}
+
+async function seedChatForTicket(ticket: Ticket, ticketRel: string, pendingId: string): Promise<string> {
+  const chatSessionId = randomUUID();
+  const result = await startChat({
+    message: ticket.seedPrompt,
+    roleId: ENCORE_SEED_ROLE_ID,
+    chatSessionId,
+    origin: `${PLUGIN_SESSION_ORIGIN_PREFIX}${ENCORE_PLUGIN_PKG}`,
+  });
+  if (result.kind === "error") {
+    throw new EncoreError(result.status ?? 500, `resolveNotification: startChat failed — ${result.error}`);
+  }
+  await writeText(ticketRel, JSON.stringify({ ...ticket, chatSessionId }, null, 2));
+  log.info("encore", "resolveNotification: chat seeded", {
+    pendingId,
+    chatSessionId,
+    obligationId: ticket.obligationId,
+    cycleId: ticket.cycleId,
+  });
+  return chatSessionId;
+}
+
+export async function handleResolveNotification(args: z.infer<typeof ResolveNotificationArgs>): Promise<EncoreDispatchResult> {
+  const ticketRel = ticketPath(args.pendingId);
+  const raw = await readTextOrNull(ticketRel);
+  if (raw === null) return handleOrphanResolve(args);
+
+  let ticket: Ticket;
+  try {
+    ticket = JSON.parse(raw) as Ticket;
+  } catch (err) {
+    throw new EncoreError(500, `ticket ${JSON.stringify(args.pendingId)} is unparseable`, {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // Idempotency: if this ticket already has a chat session, reuse
+  // it rather than spawning a duplicate on double-click.
+  const { chatSessionId: existing } = ticket;
+  const chatSessionId = existing ?? (await seedChatForTicket(ticket, ticketRel, args.pendingId));
+  if (existing) {
+    log.info("encore", "resolveNotification: reusing existing chat", { pendingId: args.pendingId, chatSessionId });
+  }
+
+  return {
+    ok: true,
+    message: `Encore: opened chat ${chatSessionId} for ${ticket.obligationId}/${ticket.cycleId}.`,
+    chatId: chatSessionId,
+    navigateTo: `/chat/${chatSessionId}`,
+  };
+}

package/server/encore/handlers/setup.ts

@@ -0,0 +1,81 @@
+// `setup` handler — provision a new obligation from a DSL document.
+
+import { z } from "zod";
+
+import { EncoreDslInput, type EncoreDsl } from "../../../src/types/encore-dsl/schema.js";
+import { buildCycleState, serializeCycleFile } from "../cycle.js";
+import { currentCycleSlot } from "../../../src/types/encore-dsl/cadence.js";
+import { serializeIndexFile } from "../obligation.js";
+import { cycleFilePath, obligationIndexPath, slugify } from "../paths.js";
+import { exists, writeText } from "../../utils/files/encore-io.js";
+import { reconcileCycleNotifications } from "../reconcile.js";
+import { log } from "../../system/logger/index.js";
+import { EncoreError, coerceDefinitionToObject, formatZodError, workspaceRelativePath, type EncoreDispatchResult } from "./shared.js";
+
+export const SetupArgs = z.object({
+  kind: z.literal("setup"),
+  definition: z.unknown(),
+});
+
+/** Setup-time id allocation. Reject with 409 if the slugified
+ *  `displayName` collides with an existing obligation — the LLM
+ *  almost certainly intended to amend an existing obligation but
+ *  forgot to pass `obligationId`. The previous behavior (silently
+ *  auto-number `-2`, `-3`) masked that mistake and produced
+ *  parallel duplicates. The reject message tells the LLM how to
+ *  recover (pass `obligationId` to make it an amend, or change
+ *  `displayName`). See plans/feat-encore-define-tool.md. */
+async function requireUniqueObligationId(displayName: string): Promise<string> {
+  const slug = slugify(displayName);
+  if (!(await exists(obligationIndexPath(slug)))) return slug;
+  throw new EncoreError(
+    409,
+    `Obligation ${JSON.stringify(slug)} already exists (displayName: ${JSON.stringify(displayName)}). ` +
+      `To modify it, call defineEncore with obligationId: ${JSON.stringify(slug)} (this becomes an amend). ` +
+      `To create a parallel obligation, change the displayName.`,
+  );
+}
+
+export async function handleSetup(args: z.infer<typeof SetupArgs>): Promise<EncoreDispatchResult> {
+  const definitionObject = coerceDefinitionToObject(args.definition, "setup");
+  let dsl: EncoreDsl;
+  try {
+    dsl = EncoreDslInput.parse(definitionObject);
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      throw new EncoreError(400, formatZodError(err), { issues: err.issues });
+    }
+    throw err;
+  }
+
+  const obligationId = await requireUniqueObligationId(dsl.displayName);
+  const fullDsl: EncoreDsl = {
+    ...dsl,
+    id: obligationId,
+    createdAt: new Date().toISOString(),
+  };
+
+  // Provision the first cycle synchronously so the obligation has
+  // something to fire against on the very next tick.
+  const slot = currentCycleSlot(fullDsl.cadence, new Date());
+  const cycle = buildCycleState(fullDsl, slot);
+
+  await writeText(obligationIndexPath(obligationId), serializeIndexFile(fullDsl, ""));
+  await writeText(cycleFilePath(obligationId, cycle.cycleId), serializeCycleFile(cycle, ""));
+
+  // Reconcile so that if the firingPlan's first phase is already due
+  // (cycle-start with no offset, for example), the bell surfaces the
+  // notification within the same SSE turn.
+  await reconcileCycleNotifications({ obligationId, cycleId: cycle.cycleId, now: new Date(), log });
+
+  log.info("encore", "setup: obligation created", { obligationId, cycleId: cycle.cycleId });
+
+  return {
+    ok: true,
+    message: `Encore obligation ${JSON.stringify(dsl.displayName)} created (id: ${obligationId}, first cycle: ${cycle.cycleId}, deadline: ${cycle.cycleDeadline}).`,
+    obligationId,
+    cycleId: cycle.cycleId,
+    cyclePath: workspaceRelativePath(cycleFilePath(obligationId, cycle.cycleId)),
+    indexPath: workspaceRelativePath(obligationIndexPath(obligationId)),
+  };
+}

package/server/encore/handlers/shared.ts

@@ -0,0 +1,137 @@
+// Shared types and helpers used across encore handler modules.
+//
+// Each per-kind handler in this directory imports from here so that
+// `dispatch.ts` stays a thin router and handlers stay focused on
+// their own kind. EncoreError + the dispatch envelope types are
+// re-exported from `dispatch.ts` for external callers (route adapter,
+// tests).
+
+import path from "node:path";
+import { z } from "zod";
+
+import type { EncoreDsl } from "../../../src/types/encore-dsl/schema.js";
+import { parseCycleFile, serializeCycleFile, type CycleState } from "../cycle.js";
+import { parseIndexFile } from "../obligation.js";
+import { cycleFilePath, obligationIndexPath } from "../paths.js";
+import { readTextOrNull, writeText } from "../../utils/files/encore-io.js";
+import { WORKSPACE_DIRS } from "../../workspace/paths.js";
+import { reconcileCycleNotifications } from "../reconcile.js";
+import { log } from "../../system/logger/index.js";
+
+// ── error types + envelope ────────────────────────────────────────
+
+export interface EncoreDispatchBody {
+  kind: string;
+  [key: string]: unknown;
+}
+
+export interface EncoreDispatchResult {
+  ok: boolean;
+  message: string;
+  [key: string]: unknown;
+}
+
+export class EncoreError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = "EncoreError";
+  }
+}
+
+// ── DSL coercion + error formatting ───────────────────────────────
+
+export function formatZodError(err: z.ZodError): string {
+  // First issue's path + message — Claude reads this and either
+  // self-corrects or asks the user. The full issues list is in
+  // `details` for clients that want the structured form.
+  const [first] = err.issues;
+  const pathStr = first.path.length > 0 ? first.path.map((segment) => String(segment)).join(".") : "(root)";
+  return `DSL validation failed at ${pathStr}: ${first.message}. Read config/helps/encore-dsl.md for the full grammar.`;
+}
+
+/** Accept `definition` as either an object literal OR a JSON-encoded
+ *  string of one. The LLM commonly JSON.stringify's tool-call
+ *  arguments (especially for nested objects), and rejecting that
+ *  shape with "expected object, received string" reads as a schema
+ *  problem rather than a wire-format problem — the LLM tends to
+ *  retry with the same shape. Silently coercing eliminates the
+ *  whole class of mistake. The trade-off: a non-JSON string or a
+ *  JSON string that decodes to a non-object surfaces with a clear
+ *  400 instead of being silently dropped. */
+export function coerceDefinitionToObject(value: unknown, kind: string): Record<string, unknown> {
+  let coerced = value;
+  if (typeof coerced === "string") {
+    try {
+      coerced = JSON.parse(coerced);
+    } catch (err) {
+      throw new EncoreError(
+        400,
+        `${kind}: \`definition\` was provided as a string but is not valid JSON: ${err instanceof Error ? err.message : String(err)}. Pass an object literal, or a JSON-encoded string of one.`,
+      );
+    }
+  }
+  if (!coerced || typeof coerced !== "object" || Array.isArray(coerced)) {
+    const actual = Array.isArray(coerced) ? "array" : coerced === null ? "null" : typeof coerced;
+    throw new EncoreError(400, `${kind}: \`definition\` must be an object (or a JSON string of one), got ${actual}.`);
+  }
+  return coerced as Record<string, unknown>;
+}
+
+export function workspaceRelativePath(rel: string): string {
+  return path.join(WORKSPACE_DIRS.encore, rel);
+}
+
+// ── DSL / cycle loaders ───────────────────────────────────────────
+
+export async function loadDsl(obligationId: string): Promise<EncoreDsl | null> {
+  const raw = await readTextOrNull(obligationIndexPath(obligationId));
+  if (raw === null) return null;
+  try {
+    return parseIndexFile(raw).dsl;
+  } catch {
+    return null;
+  }
+}
+
+export async function loadCycle(obligationId: string, cycleId: string): Promise<{ rel: string; raw: string; state: CycleState; body: string }> {
+  const rel = cycleFilePath(obligationId, cycleId);
+  const raw = await readTextOrNull(rel);
+  if (raw === null) {
+    throw new EncoreError(404, `cycle file ${obligationId}/${cycleId}.md not found`);
+  }
+  const { state, body } = parseCycleFile(raw);
+  return { rel, raw, state, body };
+}
+
+/** The mutating-handler envelope. Write the cycle file, then run
+ *  the reconciler under the same per-plugin lock that wraps this
+ *  dispatch. The reconciler re-derives the desired bell state from
+ *  disk — it's both the trim path (closed/snoozed → out of bundle)
+ *  and the publish path (un-fired in-bundle pairs → publish). */
+export async function persistAndReconcile(rel: string, state: CycleState, body: string, obligationId: string, cycleId: string): Promise<void> {
+  await writeText(rel, serializeCycleFile(state, body));
+  await reconcileCycleNotifications({ obligationId, cycleId, now: new Date(), log });
+}
+
+/** Reject calls referencing target/step ids that don't exist in
+ *  the DSL. Without this, a typo (`pat` vs `pay`) would succeed
+ *  silently — writing a record under the bogus id, leaving the
+ *  real step still un-closed, and surfacing as "I told the LLM
+ *  I paid but the bell didn't clear". */
+export function assertKnownTargetAndStep(dsl: EncoreDsl | null, args: { obligationId: string; targetId: string; stepId?: string }): void {
+  if (!dsl) {
+    throw new EncoreError(404, `obligation ${JSON.stringify(args.obligationId)} not found`);
+  }
+  if (!dsl.targets.some((target) => target.id === args.targetId)) {
+    const known = dsl.targets.map((target) => target.id).join(", ");
+    throw new EncoreError(400, `unknown targetId ${JSON.stringify(args.targetId)} for obligation ${JSON.stringify(args.obligationId)}. Known: [${known}]`);
+  }
+  if (args.stepId !== undefined && !dsl.steps.some((step) => step.id === args.stepId)) {
+    const known = dsl.steps.map((step) => step.id).join(", ");
+    throw new EncoreError(400, `unknown stepId ${JSON.stringify(args.stepId)} for obligation ${JSON.stringify(args.obligationId)}. Known: [${known}]`);
+  }
+}

package/server/encore/handlers/snooze.ts

@@ -0,0 +1,87 @@
+// `snooze` / `unsnooze` handlers — inverse pair that mark a step as
+// suppressed (or unsuppressed) for a cycle. The reconciler treats
+// snoozed pairs as out-of-bundle, so trim/republish flows naturally.
+
+import { z } from "zod";
+
+import { recordStepSnooze, recordStepUnsnooze } from "../cycle.js";
+import { ONE_HOUR_MS } from "../../utils/time.js";
+import { log } from "../../system/logger/index.js";
+import { assertKnownTargetAndStep, loadCycle, loadDsl, persistAndReconcile, type EncoreDispatchResult } from "./shared.js";
+
+export const SnoozeArgs = z.object({
+  kind: z.literal("snooze"),
+  obligationId: z.string().trim().min(1),
+  cycleId: z.string().trim().min(1),
+  targetId: z.string().trim().min(1),
+  stepId: z.string().trim().min(1),
+  pendingId: z.string().trim().min(1).optional(),
+});
+
+export const UnsnoozeArgs = z.object({
+  kind: z.literal("unsnooze"),
+  obligationId: z.string().trim().min(1),
+  cycleId: z.string().trim().min(1),
+  targetId: z.string().trim().min(1),
+  stepId: z.string().trim().min(1),
+});
+
+export async function handleSnooze(args: z.infer<typeof SnoozeArgs>): Promise<EncoreDispatchResult> {
+  const dsl = await loadDsl(args.obligationId);
+  assertKnownTargetAndStep(dsl, args);
+  // Snooze under the unified-reconciler model: write
+  // `snoozedSteps[stepId]` on the cycle file and let the reconciler
+  // do the rest. Because `isPairInBundle` treats snoozed as
+  // out-of-bundle, Phase 1 trims this target out of any existing
+  // ticket (clearing the bell if the bundle empties); Phase 2 sees
+  // the pair as not eligible-to-fire (snooze active), so no
+  // republish. The pre-reconciler workaround ("skip the tick after
+  // snooze") is no longer needed.
+  const snoozeUntilIso = new Date(Date.now() + 24 * ONE_HOUR_MS).toISOString();
+  const { rel, state, body } = await loadCycle(args.obligationId, args.cycleId);
+  const nextState = recordStepSnooze(state, args.targetId, args.stepId, snoozeUntilIso);
+  await persistAndReconcile(rel, nextState, body, args.obligationId, args.cycleId);
+  log.info("encore", "snooze: step snoozed", {
+    obligationId: args.obligationId,
+    cycleId: args.cycleId,
+    targetId: args.targetId,
+    stepId: args.stepId,
+    snoozeUntilIso,
+  });
+  return {
+    ok: true,
+    message: `Encore: snoozed ${args.stepId} for ${args.targetId} in cycle ${args.cycleId} of ${args.obligationId}.`,
+    obligationId: args.obligationId,
+    cycleId: args.cycleId,
+    targetId: args.targetId,
+    stepId: args.stepId,
+  };
+}
+
+export async function handleUnsnooze(args: z.infer<typeof UnsnoozeArgs>): Promise<EncoreDispatchResult> {
+  const dsl = await loadDsl(args.obligationId);
+  assertKnownTargetAndStep(dsl, args);
+  // Inverse of snooze: delete `snoozedSteps[stepId]`. The reconciler
+  // sees the pair eligible to fire again (assuming the step isn't
+  // also closed) and Phase 2 publishes a fresh bell — in the same
+  // dispatch turn, no tick wait. If the step was already not
+  // snoozed, `recordStepUnsnooze` is a no-op and the reconciler
+  // sees no state change → no flicker.
+  const { rel, state, body } = await loadCycle(args.obligationId, args.cycleId);
+  const nextState = recordStepUnsnooze(state, args.targetId, args.stepId);
+  await persistAndReconcile(rel, nextState, body, args.obligationId, args.cycleId);
+  log.info("encore", "unsnooze: step unsnoozed", {
+    obligationId: args.obligationId,
+    cycleId: args.cycleId,
+    targetId: args.targetId,
+    stepId: args.stepId,
+  });
+  return {
+    ok: true,
+    message: `Encore: unsnoozed ${args.stepId} for ${args.targetId} in cycle ${args.cycleId} of ${args.obligationId}.`,
+    obligationId: args.obligationId,
+    cycleId: args.cycleId,
+    targetId: args.targetId,
+    stepId: args.stepId,
+  };
+}

package/server/encore/handlers/startObligationChat.ts

@@ -0,0 +1,64 @@
+// `startObligationChat` handler — user-initiated chat about a
+// specific obligation. Reached from the dashboard chat button
+// (`/encore` landing); NOT exposed in the LLM-facing tool schema.
+//
+// Compared to `resolveNotification` (the bell-click path):
+//   - No ticket. There's no notification to clear and no severity
+//     baseline to track — this is purely user-initiated.
+//   - No reuse / idempotency. Each click yields a fresh chat. If
+//     the user wants to continue a previous conversation, they
+//     pick it from the sidebar instead.
+//   - Seed prompt is composed here from the DSL (id + displayName)
+//     rather than read from a ticket.
+
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+
+import { startChat } from "../../api/routes/agent.js";
+import { PLUGIN_SESSION_ORIGIN_PREFIX } from "../../../src/types/session.js";
+import { ENCORE_SEED_ROLE_ID } from "../../../src/config/roles.js";
+import { ENCORE_PLUGIN_PKG } from "../notifier.js";
+import { log } from "../../system/logger/index.js";
+import { EncoreError, loadDsl, type EncoreDispatchResult } from "./shared.js";
+
+export const StartObligationChatArgs = z.object({
+  kind: z.literal("startObligationChat"),
+  obligationId: z.string().min(1),
+});
+
+function buildSeedPrompt(obligationId: string, displayName: string): string {
+  // Mention the obligationId explicitly so the LLM can call
+  // `manageEncore({ kind: "query", obligationId })` to read the
+  // current state on its first turn without guessing.
+  return `Let's talk about my "${displayName}" obligation (obligationId: ${obligationId}). Please query its current state first, then ask me what I'd like to do.`;
+}
+
+export async function handleStartObligationChat(args: z.infer<typeof StartObligationChatArgs>): Promise<EncoreDispatchResult> {
+  const dsl = await loadDsl(args.obligationId);
+  if (!dsl) {
+    throw new EncoreError(404, `obligation ${JSON.stringify(args.obligationId)} not found`);
+  }
+
+  const chatSessionId = randomUUID();
+  const result = await startChat({
+    message: buildSeedPrompt(args.obligationId, dsl.displayName),
+    roleId: ENCORE_SEED_ROLE_ID,
+    chatSessionId,
+    origin: `${PLUGIN_SESSION_ORIGIN_PREFIX}${ENCORE_PLUGIN_PKG}`,
+  });
+  if (result.kind === "error") {
+    throw new EncoreError(result.status ?? 500, `startObligationChat: startChat failed — ${result.error}`);
+  }
+
+  log.info("encore", "startObligationChat: chat seeded", {
+    obligationId: args.obligationId,
+    chatSessionId,
+  });
+
+  return {
+    ok: true,
+    message: `Encore: opened chat ${chatSessionId} for ${args.obligationId}.`,
+    chatId: chatSessionId,
+    navigateTo: `/chat/${chatSessionId}`,
+  };
+}

package/server/encore/handlers/startSetupChat.ts

@@ -0,0 +1,50 @@
+// `startSetupChat` handler — user-initiated chat for creating a new
+// obligation. Reached from the dashboard "+ Add" button (`/encore`
+// landing); NOT exposed in the LLM-facing tool schema.
+//
+// Parallel to `startObligationChat` (which discusses an existing
+// obligation) — this one has no obligation yet, so the seed prompt
+// only asks the LLM to walk the user through setup. The LLM has
+// the encore-dsl help file + `manageEncore({kind:"setup"})` already
+// in its toolbelt; we don't need to teach it the schema here.
+
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+
+import { startChat } from "../../api/routes/agent.js";
+import { PLUGIN_SESSION_ORIGIN_PREFIX } from "../../../src/types/session.js";
+import { ENCORE_SEED_ROLE_ID } from "../../../src/config/roles.js";
+import { ENCORE_PLUGIN_PKG } from "../notifier.js";
+import { log } from "../../system/logger/index.js";
+import { EncoreError, type EncoreDispatchResult } from "./shared.js";
+
+export const StartSetupChatArgs = z.object({
+  kind: z.literal("startSetupChat"),
+});
+
+const SEED_PROMPT =
+  "I'd like to set up a new recurring obligation in Encore. " +
+  "Please walk me through what to track (kind, cadence, targets, fields), " +
+  "then compose the DSL and call defineEncore when ready.";
+
+export async function handleStartSetupChat(__args: z.infer<typeof StartSetupChatArgs>): Promise<EncoreDispatchResult> {
+  const chatSessionId = randomUUID();
+  const result = await startChat({
+    message: SEED_PROMPT,
+    roleId: ENCORE_SEED_ROLE_ID,
+    chatSessionId,
+    origin: `${PLUGIN_SESSION_ORIGIN_PREFIX}${ENCORE_PLUGIN_PKG}`,
+  });
+  if (result.kind === "error") {
+    throw new EncoreError(result.status ?? 500, `startSetupChat: startChat failed — ${result.error}`);
+  }
+
+  log.info("encore", "startSetupChat: chat seeded", { chatSessionId });
+
+  return {
+    ok: true,
+    message: `Encore: opened setup chat ${chatSessionId}.`,
+    chatId: chatSessionId,
+    navigateTo: `/chat/${chatSessionId}`,
+  };
+}

package/server/encore/lock.ts

@@ -0,0 +1,61 @@
+// Per-plugin mutex. All dispatch calls and all ticks serialise
+// through one Promise-chain so:
+//
+//   - Two concurrent handler calls can't tmp+rename the same cycle
+//     file at once (writeFileAtomic ENOENT race).
+//   - A handler that kicks the tick can't race the hourly heartbeat
+//     into double-publishing the same notification.
+//
+// Implementation split:
+//   - `withLock(fn)`: appends fn to the chain; returns its result.
+//     Errors don't poison the chain — the next consumer's wait
+//     resolves regardless.
+//   - `kickTickLocked(reason)`: acquires the lock, runs the tick,
+//     releases. Handlers call this AFTER persisting; the hourly
+//     heartbeat also goes through this.
+//   - `runDispatchLocked(fn)`: thin alias for withLock — exists for
+//     readability at call sites in dispatch.ts.
+//
+// Handlers that need to kick the tick from inside their critical
+// section MUST NOT call kickTickLocked (it would deadlock). They
+// invoke `tickUnlocked` directly. The boot wiring + the hourly
+// heartbeat both call kickTickLocked so external callers don't
+// have to think about which one to pick.
+
+import { log } from "../system/logger/index.js";
+import { runTick, type TickDeps } from "./tick.js";
+
+let pluginLock: Promise<unknown> = Promise.resolve();
+
+/** Append `fn` to the per-plugin chain. Returns `fn`'s result. */
+export function withLock<T>(task: () => Promise<T>): Promise<T> {
+  const next = pluginLock.catch(() => undefined).then(task);
+  pluginLock = next.catch(() => undefined);
+  return next;
+}
+
+/** Run the tick without acquiring the lock. Callers that already
+ *  hold the lock (e.g. a handler that wants to kick the tick from
+ *  inside its critical section) use this; everyone else uses
+ *  `kickTickLocked`. */
+export async function tickUnlocked(deps: TickDeps, reason: string): Promise<void> {
+  try {
+    await runTick(deps);
+  } catch (err) {
+    log.warn("encore", "tick: unhandled error", { reason, error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+/** Acquire the lock, run the tick, release. The hourly heartbeat
+ *  and `kickTick`-from-handler calls both come through here so the
+ *  serialisation guarantee applies. */
+export async function kickTickLocked(deps: TickDeps, reason: string): Promise<void> {
+  await withLock(() => tickUnlocked(deps, reason));
+}
+
+/** Reset the lock to a fresh resolved Promise. Test-only — production
+ *  code never wants this; the chain is meant to live for the process
+ *  lifetime. */
+export function _resetLockForTesting(): void {
+  pluginLock = Promise.resolve();
+}