@codazen/harmonica-mcp 5.1.0 → 5.3.0

package/dist/index.js

@@ -21287,6 +21287,23 @@ watchPullRequest:
 
 Re-read the policy before each step rather than caching it, so a human revoking
 a toggle mid-flight takes effect on your next action.`;
+var WORK_ITEM_LIFECYCLE_INSTRUCTIONS = `WORK ITEM LIFECYCLE (CHANNEL-INDEPENDENT)
+
+When you perform substantive work for a known Work Item, keep that Work Item's
+status accurate even when the work happens outside a Harmonica Session.
+
+- Before starting, get the Work Item and transition it from \`not_started\` to
+  \`in_progress\` with \`transition_work_item_status\`. Resume a \`blocked\` item
+  only when its blocker has cleared. Do not reopen a \`done\` item unless new
+  work genuinely belongs to that same item.
+- When its requested outcome is actually complete, transition it to \`done\`.
+  If work cannot proceed, transition it to \`blocked\`. A conversation, task,
+  or Session ending is not evidence that every associated Work Item is done.
+- Manage multiple Work Items independently. Leave untouched items unchanged;
+  completing or blocking one must not change the others. A Session association
+  is useful lineage, but it is never required in order to update status.
+- If the status tool is unavailable or fails, say plainly that the Work Item
+  status was not updated rather than implying that it was.`;
 async function createMcpServer(ctx, client, registerTools, registerResources) {
   let guidelines;
   try {
@@ -21294,7 +21311,11 @@ async function createMcpServer(ctx, client, registerTools, registerResources) {
   } catch (err) {
     console.warn("[MCP] Failed to load beat guidelines for server instructions:", err);
   }
-  const instructions = [guidelines, DELIVERY_LATITUDE_INSTRUCTIONS].filter(Boolean).join("\n\n");
+  const instructions = [
+    guidelines,
+    DELIVERY_LATITUDE_INSTRUCTIONS,
+    WORK_ITEM_LIFECYCLE_INSTRUCTIONS
+  ].filter(Boolean).join("\n\n");
   const server = new McpServer({
     name: "harmonica",
     version: "0.1.0"
@@ -22429,9 +22450,9 @@ var CHECK_MAX_SCORES = {
 var BeatQualityGateError = class extends Error {
   code = "beat_quality_gate_failed";
   failure;
-  constructor(failure) {
-    super(failure.message);
-    this.failure = failure;
+  constructor(failure2) {
+    super(failure2.message);
+    this.failure = failure2;
   }
 };
 var PlanVersionsIdempotencyError = class extends Error {
@@ -22480,20 +22501,30 @@ var POLL_MAX_CONSECUTIVE_ERRORS = 3;
 async function pollForCheck(client, taskId) {
   const deadline = Date.now() + POLL_TIMEOUT_MS;
   let consecutiveErrors = 0;
+  let consecutiveMissing = 0;
   while (Date.now() < deadline) {
     const [task, err] = await client.getTask(taskId).then(
       (t) => [t, null],
       (e) => [null, e]
     );
     if (err) {
+      consecutiveMissing = 0;
       consecutiveErrors++;
       if (consecutiveErrors >= POLL_MAX_CONSECUTIVE_ERRORS)
         throw new Error(`getTask failed ${consecutiveErrors} consecutive times: ${err instanceof Error ? err.message : String(err)}`);
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
       continue;
     }
+    if (!task) {
+      consecutiveErrors = 0;
+      consecutiveMissing++;
+      if (consecutiveMissing >= POLL_MAX_CONSECUTIVE_ERRORS)
+        throw new Error(`Task ${taskId} not found after ${consecutiveMissing} consecutive attempts`);
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+      continue;
+    }
     consecutiveErrors = 0;
-    if (!task) throw new Error(`Task ${taskId} not found`);
+    consecutiveMissing = 0;
     if (task.status === "completed") {
       if (!task.result) throw new CheckResultPendingError(taskId);
       return task.result;
@@ -22801,6 +22832,18 @@ ${revision.description}`);
   }
   return sections.join("\n");
 }
+function formatRevisionPreview(revisionId, preview) {
+  if (!preview) return `No preview recorded for revision: ${revisionId}`;
+  const freshness = preview.isCurrent ? "Current \u2014 built from the head commit." : `Stale \u2014 built from ${preview.commitSha?.slice(0, 7) ?? "an unknown commit"}, which is no longer the head. Still opens.`;
+  return [
+    `# Preview: ${revisionId}`,
+    `**URL:** ${preview.url}`,
+    `**Built from:** ${preview.commitSha}`,
+    `**Recorded:** ${preview.recordedAt}`,
+    `
+${freshness}`
+  ].join("\n");
+}
 
 // ../../libs/harmonica-services/src/mcp/formatters/note-formatter.ts
 var TYPE_LABELS = {
@@ -23309,6 +23352,26 @@ ${formatDeliveryPolicy(
       }
     }
   );
+  server.tool(
+    "get_revision_preview",
+    "Get the preview link recorded for a Revision \u2014 the running environment its own pipeline published, and whether that build is still the pull request's head. A Revision with no recorded preview is reported plainly, not as an error: one whose change artifact is a document never gets one. A stale link still opens; it was built before the latest commit.",
+    {
+      revisionId: external_exports.string().describe("The revision ID (e.g., rev-abc123)")
+    },
+    async ({ revisionId }) => {
+      try {
+        const revision = await client.getRevision(revisionId);
+        if (!revision) {
+          return { content: [{ type: "text", text: `Revision not found: ${revisionId}` }], isError: true };
+        }
+        const preview = await client.resolveRevisionPreview(revisionId);
+        return { content: [{ type: "text", text: formatRevisionPreview(revisionId, preview) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to get revision preview: ${message}` }], isError: true };
+      }
+    }
+  );
 }
 async function logBeatActivity(client, params) {
   try {
@@ -24227,12 +24290,14 @@ var POLL_MAX_CONSECUTIVE_ERRORS2 = 3;
 async function pollForCheck2(client, taskId) {
   const deadline = Date.now() + POLL_TIMEOUT_MS2;
   let consecutiveErrors = 0;
+  let consecutiveMissing = 0;
   while (Date.now() < deadline) {
     const [task, err] = await client.getTask(taskId).then(
       (t) => [t, null],
       (e) => [null, e]
     );
     if (err) {
+      consecutiveMissing = 0;
       consecutiveErrors++;
       if (consecutiveErrors >= POLL_MAX_CONSECUTIVE_ERRORS2) {
         throw new Error(`getTask failed ${consecutiveErrors} times: ${err instanceof Error ? err.message : String(err)}`);
@@ -24240,8 +24305,16 @@ async function pollForCheck2(client, taskId) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS2));
       continue;
     }
+    if (!task) {
+      consecutiveErrors = 0;
+      consecutiveMissing++;
+      if (consecutiveMissing >= POLL_MAX_CONSECUTIVE_ERRORS2)
+        throw new Error(`Task ${taskId} not found after ${consecutiveMissing} consecutive attempts`);
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS2));
+      continue;
+    }
     consecutiveErrors = 0;
-    if (!task) throw new Error(`Task ${taskId} not found`);
+    consecutiveMissing = 0;
     if (task.status === "completed") {
       if (!task.result) throw new CheckResultPendingError(taskId);
       return task.result;
@@ -25344,6 +25417,14 @@ var RevisionScmSchema = external_exports.object({
   state: external_exports.enum(["draft", "open", "merged", "closed"]),
   mergeSha: external_exports.string().optional()
 });
+var RevisionPreviewSchema = external_exports.object({
+  url: external_exports.string(),
+  commitSha: external_exports.string(),
+  recordedAt: external_exports.string()
+});
+var RevisionPreviewApiSchema = RevisionPreviewSchema.extend({
+  isCurrent: external_exports.boolean()
+});
 var RevisionApiSchema = external_exports.object({
   revisionId: external_exports.string(),
   beatId: external_exports.string(),
@@ -25686,6 +25767,7 @@ var NotificationSchema2 = external_exports.object({
   systemId: external_exports.string(),
   beatId: external_exports.string().optional(),
   revisionId: external_exports.string().optional(),
+  workItemIds: external_exports.array(external_exports.string()).optional(),
   noteId: external_exports.string().optional(),
   checkId: external_exports.string().optional(),
   actorType: external_exports.enum(["user", "system"]),
@@ -25881,6 +25963,7 @@ var StartSessionRequestBodySchema = external_exports.object({
   systemId: external_exports.string().min(1),
   message: external_exports.string().min(1),
   revisionId: external_exports.string().min(1).optional(),
+  workItemIds: external_exports.array(external_exports.string().min(1)).max(50).optional(),
   /** Caller's own Session id — nests the new Session under it (B-231). */
   parentSessionId: external_exports.string().min(1).optional(),
   enableWebSearch: external_exports.boolean().optional()
@@ -25950,7 +26033,8 @@ var WORK_ITEM_EFFORT_SIZES = [
   "S",
   "M",
   "L",
-  "XL"
+  "XL",
+  "XXL"
 ];
 var WorkItemEffortSizeSchema = external_exports.enum(WORK_ITEM_EFFORT_SIZES);
 var HumanAssigneeApiSchema = external_exports.object({
@@ -26090,9 +26174,24 @@ var WORK_ORDER_SIZES = [
   "S",
   "M",
   "L",
-  "XL"
+  "XL",
+  "XXL"
 ];
 var WorkOrderSizeApiSchema = external_exports.enum(WORK_ORDER_SIZES);
+var WORK_ORDER_SIZE_VALUE_UNITS = {
+  XS: 4,
+  // half a person-day
+  S: 8,
+  // one person-day
+  M: 24,
+  // three person-days
+  L: 40,
+  // one person-week
+  XL: 80,
+  // two person-weeks
+  XXL: 160
+  // four person-weeks
+};
 var WORK_REQUEST_ORIGINS = [
   "client",
   "internal"
@@ -26135,6 +26234,9 @@ var WorkOrderApiSchema = external_exports.object({
   needsDecisionReason: NeedsDecisionReasonApiSchema.optional(),
   /** Absent when the Order arrived before it was sized, which the composition counts. */
   size: WorkOrderSizeApiSchema.optional(),
+  archived: external_exports.boolean().optional(),
+  archivedAt: external_exports.string().optional(),
+  archivedReason: external_exports.string().optional(),
   createdBy: external_exports.string().optional(),
   version: external_exports.number().optional(),
   createdAt: external_exports.string(),
@@ -26185,6 +26287,30 @@ var AccountApiSchema = external_exports.object({
   updatedAt: external_exports.string()
 }).passthrough();
 var AccountsResponseSchema = external_exports.object({ accounts: external_exports.array(AccountApiSchema) }).passthrough();
+var ManagedRelationshipStatusApiSchema = external_exports.enum(["active", "suspended", "revoked"]);
+var ManagedRelationshipApiSchema = external_exports.object({
+  relationshipId: external_exports.string(),
+  agencyOrgId: external_exports.string(),
+  customerOrgId: external_exports.string(),
+  agencyAccountId: external_exports.string(),
+  accountIds: external_exports.array(external_exports.string()),
+  status: ManagedRelationshipStatusApiSchema,
+  createdBy: external_exports.string(),
+  statusChangedBy: external_exports.string().nullish(),
+  statusChangedAt: external_exports.string().nullish(),
+  suspendedBy: external_exports.string().nullish(),
+  suspendedAt: external_exports.string().nullish(),
+  reactivatedBy: external_exports.string().nullish(),
+  reactivatedAt: external_exports.string().nullish(),
+  revokedBy: external_exports.string().nullish(),
+  revokedAt: external_exports.string().nullish(),
+  version: external_exports.number(),
+  createdAt: external_exports.string(),
+  updatedAt: external_exports.string()
+}).passthrough();
+var ManagedRelationshipsResponseSchema = external_exports.object({
+  relationships: external_exports.array(ManagedRelationshipApiSchema)
+}).passthrough();
 var AccountSystemApiSchema = external_exports.object({
   systemId: external_exports.string(),
   accountId: external_exports.string(),
@@ -26922,6 +27048,100 @@ ${formatLayerDetail(layer)}` }] };
   );
 }
 
+// ../../libs/harmonica-services/src/mcp/tools/managed-relationship-tools.ts
+function formatRelationship(relationship) {
+  if (!relationship) return "Managed relationship not found.";
+  return [
+    `ID: ${relationship.relationshipId}`,
+    `Agency Organization: ${relationship.agencyOrgId}`,
+    `Customer Organization: ${relationship.customerOrgId}`,
+    `Agency Account: ${relationship.agencyAccountId}`,
+    `Customer Accounts: ${relationship.accountIds.join(", ")}`,
+    `Status: ${relationship.status}`
+  ].join("\n");
+}
+function failure(action, error2) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  return {
+    content: [{ type: "text", text: `Failed to ${action}: ${message}` }],
+    isError: true
+  };
+}
+function registerManagedRelationshipTools(server, _ctx, client) {
+  server.tool(
+    "create_managed_relationship",
+    "Connect an agency Organization to a separately owned customer Organization and grant the agency access only to the named customer Accounts. Both Organizations, the agency commercial Account, and every customer Account must already exist. Phase 1 is administrator-provisioned; no approval request is sent.",
+    {
+      agencyOrgId: external_exports.string().describe("The managing agency Organization ID"),
+      customerOrgId: external_exports.string().describe("The customer-owned Organization ID"),
+      agencyAccountId: external_exports.string().describe("The agency-owned commercial Account for this customer"),
+      accountIds: external_exports.array(external_exports.string()).min(1).max(10).describe("Customer-owned Account IDs delegated to the agency")
+    },
+    async (input) => {
+      try {
+        const relationship = await client.createManagedRelationship(input);
+        return { content: [{ type: "text", text: `Created managed relationship.
+${formatRelationship(relationship)}` }] };
+      } catch (error2) {
+        return failure("create managed relationship", error2);
+      }
+    }
+  );
+  server.tool(
+    "list_managed_relationships",
+    "List customer Organizations and Account scopes managed by an agency Organization.",
+    { agencyOrgId: external_exports.string().describe("The managing agency Organization ID") },
+    async ({ agencyOrgId }) => {
+      try {
+        const relationships = await client.listManagedRelationships(agencyOrgId);
+        const text = relationships.length === 0 ? "No managed customer organizations found." : relationships.map(formatRelationship).join("\n\n");
+        return { content: [{ type: "text", text }] };
+      } catch (error2) {
+        return failure("list managed relationships", error2);
+      }
+    }
+  );
+  server.tool(
+    "get_managed_relationship",
+    "Get one managed relationship and its explicitly delegated customer Account IDs.",
+    { relationshipId: external_exports.string().describe("The managed relationship ID") },
+    async ({ relationshipId }) => {
+      try {
+        return {
+          content: [{
+            type: "text",
+            text: formatRelationship(await client.getManagedRelationship(relationshipId))
+          }]
+        };
+      } catch (error2) {
+        return failure("get managed relationship", error2);
+      }
+    }
+  );
+  server.tool(
+    "set_managed_relationship_status",
+    "Suspend, reactivate, or permanently revoke a managed relationship. Revoked relationships cannot be reactivated.",
+    {
+      relationshipId: external_exports.string().describe("The managed relationship ID"),
+      status: external_exports.enum(["active", "suspended", "revoked"]).describe("The target status")
+    },
+    async ({ relationshipId, status }) => {
+      try {
+        const relationship = await client.setManagedRelationshipStatus(relationshipId, status);
+        if (!relationship) {
+          return {
+            content: [{ type: "text", text: "Managed relationship not found." }],
+            isError: true
+          };
+        }
+        return { content: [{ type: "text", text: formatRelationship(relationship) }] };
+      } catch (error2) {
+        return failure("update managed relationship", error2);
+      }
+    }
+  );
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/membership-tools.ts
 var orgIdArg = external_exports.string().describe("The organization ID \u2014 see list_organizations");
 function registerMembershipTools(server, ctx, client) {
@@ -28292,22 +28512,16 @@ ${formatTree(tree.root)}` }] };
       }
       let scopeSystemId = systemId;
       if (!scopeSystemId) {
-        let bindings;
         let bindingsFetchFailed = false;
         try {
-          bindings = await client.getNotebookScopeBindings(notebookId);
+          const bindings = await client.getNotebookScopeBindings(notebookId);
           scopeSystemId = bindings?.find((b) => b.scopeType === "system")?.scopeId;
         } catch {
           bindingsFetchFailed = true;
         }
         if (!scopeSystemId) {
-          if (!bindingsFetchFailed) {
-            const hasLegacyProjectBinding = bindings?.some((b) => b.scopeType === "project");
-            if (hasLegacyProjectBinding) {
-              return { content: [{ type: "text", text: `Notebook "${notebookId}" has only a legacy 'project' scope binding \u2014 record may need B-247 migration re-check.` }], isError: true };
-            }
-          }
-          return { content: [{ type: "text", text: "No system scope: pass systemId or bind the notebook to a system first." }], isError: true };
+          const msg = bindingsFetchFailed ? "Failed to look up notebook scope binding \u2014 this may be transient. Pass an explicit systemId to proceed." : "No system scope: pass systemId or bind the notebook to a system first.";
+          return { content: [{ type: "text", text: msg }], isError: true };
         }
       }
       let tree;
@@ -28362,7 +28576,7 @@ ${formatTree(tree.root)}` }] };
   );
   server.tool(
     "update_notebook_collection",
-    "Reconfigure a placed live-collection section in place \u2014 change what it collects (note type, project scope, limit, order, significance tier) or its heading, without removing and re-adding it. Only the fields you pass change; the rest keep their current values. Identify the section by its elementId (from get_notebook_tree) and the page it sits on.",
+    "Reconfigure a placed live-collection section in place \u2014 change what it collects (note type, system scope, limit, order, significance tier) or its heading, without removing and re-adding it. Only the fields you pass change; the rest keep their current values. Identify the section by its elementId (from get_notebook_tree) and the page it sits on.",
     {
       notebookId: external_exports.string().describe("The Notebook ID"),
       elementId: external_exports.string().describe("The collection section's elementId (from get_notebook_tree)"),
@@ -28411,10 +28625,9 @@ ${formatTree(tree.root)}` }] };
         return { content: [{ type: "text", text: `Element "${elementId}" is not a live collection \u2014 its configuration cannot be edited here.` }], isError: true };
       }
       const base = existing.query;
-      const normalizedScope = systemId ? `system:${systemId}` : base.scope.replace(/^project:/, "system:");
-      const colonIdx = normalizedScope.indexOf(":");
-      if (colonIdx <= 0 || colonIdx === normalizedScope.length - 1) {
-        return { content: [{ type: "text", text: `Stored scope '${base.scope}' has no system id \u2014 pass an explicit systemId to re-bind this collection.` }], isError: true };
+      const normalizedScope = systemId ? `system:${systemId}` : base.scope;
+      if (!normalizedScope.startsWith("system:") || normalizedScope.length <= "system:".length) {
+        return { content: [{ type: "text", text: `Stored scope '${base.scope}' is not a valid system scope \u2014 pass an explicit systemId to re-bind this collection.` }], isError: true };
       }
       const mergedQuery = {
         source: "notes",
@@ -28503,9 +28716,9 @@ ${scopeText}` }] };
   );
   server.tool(
     "list_notebooks",
-    "List Notebooks reachable from a scope (org, teamspace, or system). Returns all notebooks bound to that scope.",
+    "List Notebooks reachable from a scope (org, teamspace, system, or account). Returns all notebooks bound to that scope.",
     {
-      scopeType: external_exports.enum(SCOPE_TYPE_VALUES).describe("Scope type \u2014 org, teamspace, or project"),
+      scopeType: external_exports.enum(SCOPE_TYPE_VALUES).describe("Scope type \u2014 org, teamspace, system, or account"),
       scopeId: external_exports.string().min(1).describe("ID of the scope entity"),
       includeArchived: external_exports.boolean().optional().describe("Include archived Notebooks in the results. Default: false (archived excluded).")
     },
@@ -28566,10 +28779,10 @@ ${formatNotebook(updated)}` }] };
   );
   server.tool(
     "add_notebook_shortcut",
-    "Add a curated, read-only shortcut from a scope (org, teamspace, project, or account) to a Notebook owned elsewhere in the SAME organization. Unlike set_notebook_scopes, a shortcut grants no rename/archive/delete rights over the Notebook in the consuming scope \u2014 it is a link, not ownership.",
+    "Add a curated, read-only shortcut from a scope (org, teamspace, system, or account) to a Notebook owned elsewhere in the SAME organization. Unlike set_notebook_scopes, a shortcut grants no rename/archive/delete rights over the Notebook in the consuming scope \u2014 it is a link, not ownership.",
     {
       notebookId: external_exports.string().describe("The Notebook ID to shortcut"),
-      scopeType: external_exports.enum(SCOPE_TYPE_VALUES).describe("Consuming scope type \u2014 org, teamspace, project, or account"),
+      scopeType: external_exports.enum(SCOPE_TYPE_VALUES).describe("Consuming scope type \u2014 org, teamspace, system, or account"),
       scopeId: external_exports.string().min(1).describe("ID of the consuming scope entity"),
       createdBy: external_exports.string().optional().describe("Actor ID \u2014 defaults to the session user")
     },
@@ -28598,7 +28811,7 @@ ${formatNotebook(updated)}` }] };
     "Remove a Notebook shortcut from a scope. Only removes the shortcut reference \u2014 never affects the source Notebook or its real scope bindings.",
     {
       notebookId: external_exports.string().describe("The Notebook ID"),
-      scopeType: external_exports.enum(SCOPE_TYPE_VALUES).describe("Consuming scope type \u2014 org, teamspace, project, or account"),
+      scopeType: external_exports.enum(SCOPE_TYPE_VALUES).describe("Consuming scope type \u2014 org, teamspace, system, or account"),
       scopeId: external_exports.string().min(1).describe("ID of the consuming scope entity")
     },
     async ({ notebookId, scopeType, scopeId }) => {
@@ -28621,7 +28834,7 @@ ${formatNotebook(updated)}` }] };
     "list_notebook_shortcuts",
     "List a scope\u2019s curated Notebook shortcuts \u2014 Notebooks owned elsewhere in the org that this scope has chosen to surface, hydrated with each source Notebook\u2019s live title/status.",
     {
-      scopeType: external_exports.enum(SCOPE_TYPE_VALUES).describe("Scope type \u2014 org, teamspace, project, or account"),
+      scopeType: external_exports.enum(SCOPE_TYPE_VALUES).describe("Scope type \u2014 org, teamspace, system, or account"),
       scopeId: external_exports.string().min(1).describe("ID of the scope entity")
     },
     async ({ scopeType, scopeId }) => {
@@ -28976,12 +29189,14 @@ var ROOT_CODA_POLL_MAX_CONSECUTIVE_ERRORS = 3;
 async function pollForRootCodaCheck(client, taskId) {
   const deadline = Date.now() + ROOT_CODA_POLL_TIMEOUT_MS;
   let consecutiveErrors = 0;
+  let consecutiveMissing = 0;
   while (Date.now() < deadline) {
     const [task, err] = await client.getTask(taskId).then(
       (t) => [t, null],
       (e) => [null, e]
     );
     if (err) {
+      consecutiveMissing = 0;
       consecutiveErrors++;
       if (consecutiveErrors >= ROOT_CODA_POLL_MAX_CONSECUTIVE_ERRORS) {
         throw new Error(`getTask failed ${consecutiveErrors} times: ${err instanceof Error ? err.message : String(err)}`);
@@ -28989,8 +29204,16 @@ async function pollForRootCodaCheck(client, taskId) {
       await new Promise((r) => setTimeout(r, ROOT_CODA_POLL_INTERVAL_MS));
       continue;
     }
+    if (!task) {
+      consecutiveErrors = 0;
+      consecutiveMissing++;
+      if (consecutiveMissing >= ROOT_CODA_POLL_MAX_CONSECUTIVE_ERRORS)
+        throw new Error(`Task ${taskId} not found after ${consecutiveMissing} consecutive attempts`);
+      await new Promise((r) => setTimeout(r, ROOT_CODA_POLL_INTERVAL_MS));
+      continue;
+    }
     consecutiveErrors = 0;
-    if (!task) throw new Error(`Task ${taskId} not found`);
+    consecutiveMissing = 0;
     if (task.status === "completed") {
       if (!task.result) throw new CheckResultPendingError(taskId);
       const result = task.result;
@@ -29333,12 +29556,14 @@ var POLL_MAX_CONSECUTIVE_ERRORS4 = 3;
 async function pollForCheck4(client, taskId) {
   const deadline = Date.now() + POLL_TIMEOUT_MS4;
   let consecutiveErrors = 0;
+  let consecutiveMissing = 0;
   while (Date.now() < deadline) {
     const [task, err] = await client.getTask(taskId).then(
       (t) => [t, null],
       (e) => [null, e]
     );
     if (err) {
+      consecutiveMissing = 0;
       consecutiveErrors++;
       if (consecutiveErrors >= POLL_MAX_CONSECUTIVE_ERRORS4) {
         throw new Error(`getTask failed ${consecutiveErrors} times: ${err instanceof Error ? err.message : String(err)}`);
@@ -29346,8 +29571,16 @@ async function pollForCheck4(client, taskId) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS4));
       continue;
     }
+    if (!task) {
+      consecutiveErrors = 0;
+      consecutiveMissing++;
+      if (consecutiveMissing >= POLL_MAX_CONSECUTIVE_ERRORS4)
+        throw new Error(`Task ${taskId} not found after ${consecutiveMissing} consecutive attempts`);
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS4));
+      continue;
+    }
     consecutiveErrors = 0;
-    if (!task) throw new Error(`Task ${taskId} not found`);
+    consecutiveMissing = 0;
     if (task.status === "completed") {
       if (!task.result) throw new CheckResultPendingError(taskId);
       return task.result;
@@ -30684,19 +30917,16 @@ function registerSnapshotTools(server, ctx, client) {
   );
 }
 function normalizeSnapshot(raw) {
-  const anyRaw = raw;
   return {
     ...raw,
-    // Compat: v3 and earlier snapshots have 'project' instead of 'system'
-    system: raw.system ?? anyRaw["project"],
+    system: raw.system,
     beats: raw.beats ?? [],
     beatIndex: raw.beatIndex ?? [],
     proposals: raw.proposals ?? [],
     proposalIndex: raw.proposalIndex ?? [],
     revisions: raw.revisions ?? [],
     revisionIndex: raw.revisionIndex ?? [],
-    // Compat: v3 and earlier snapshots have 'projectRevisionIndex'
-    systemRevisionIndex: raw.systemRevisionIndex ?? anyRaw["projectRevisionIndex"] ?? [],
+    systemRevisionIndex: raw.systemRevisionIndex ?? [],
     activities: raw.activities ?? [],
     activityIndex: raw.activityIndex ?? [],
     notes: raw.notes ?? [],
@@ -30709,8 +30939,7 @@ function normalizeSnapshot(raw) {
     promptLogs: raw.promptLogs ?? [],
     beatVersions: raw.beatVersions ?? [],
     beatBeatVersionIndex: raw.beatBeatVersionIndex ?? [],
-    // Compat: v3 and earlier snapshots have 'projectBeatVersionIndex'
-    systemBeatVersionIndex: raw.systemBeatVersionIndex ?? anyRaw["projectBeatVersionIndex"] ?? [],
+    systemBeatVersionIndex: raw.systemBeatVersionIndex ?? [],
     beatVersionDropAssignments: raw.beatVersionDropAssignments ?? [],
     drops: raw.drops ?? [],
     accountDropIndex: raw.accountDropIndex ?? [],
@@ -30806,8 +31035,11 @@ function assertSnapshotShape(val, sourceHint) {
   if (typeof obj["version"] !== "number" || obj["version"] <= 0) {
     throw new Error(`Snapshot${sourceHint} has an invalid or missing 'version' field \u2014 it may not be a valid project snapshot.`);
   }
-  const systemOrProject = obj["system"] ?? obj["project"];
-  if (typeof systemOrProject !== "object" || systemOrProject === null || typeof systemOrProject["systemId"] !== "string") {
+  const system = obj["system"];
+  if (typeof system !== "object" || system === null || typeof system["systemId"] !== "string") {
+    if (typeof obj["project"] === "object" && obj["project"] !== null) {
+      throw new Error(`Snapshot${sourceHint} uses the v1-v3 'project' field format, which is no longer supported. Export a fresh snapshot from your environment and re-import.`);
+    }
     throw new Error(`Snapshot${sourceHint} is missing 'system.systemId' \u2014 it may not be a valid project snapshot.`);
   }
 }
@@ -31417,7 +31649,7 @@ ${t.acceptanceCriteria}` : null,
   };
   server.tool(
     "create_track",
-    'Create a Track under a Movement. Use for scoped initiatives \u2014 client SOWs, internal phases, engagement containers \u2014 that collect Deliverables and Drops. Do NOT use for software capabilities the product provides to end users (those are Beats). Recognition cues: "this engagement", "this SOW", "this phase of work", "the client project", "this track" \u2192 Track.',
+    'Create a Track under a Movement. Use for scoped initiatives \u2014 client SOWs, internal phases, engagement containers \u2014 that collect work items and Drops. Do NOT use for software capabilities the product provides to end users (those are Beats). Recognition cues: "this engagement", "this SOW", "this phase of work", "the client project", "this track" \u2192 Track.',
     createTrackSchema,
     createTrackHandler
   );
@@ -31857,24 +32089,47 @@ function registerValueVelocityTools(server, ctx, client) {
   );
 }
 
-// ../../libs/harmonica-services/src/mcp/tools/work-item-tools.ts
-var WORK_ITEM_STATUS_ENUM = ["not_started", "in_progress", "blocked", "done"];
-function formatOwner(owner) {
-  return owner ? `${owner.name} <${owner.email}>` : "unassigned";
-}
+// ../../libs/harmonica-services/src/tool-schemas/sizing.ts
+var WORK_ORDER_SIZE_ENUM = [
+  "XS",
+  "S",
+  "M",
+  "L",
+  "XL",
+  "XXL"
+];
 var WORK_ITEM_EFFORT_SIZE_ENUM = [
   "XS",
   "S",
   "M",
   "L",
-  "XL"
+  "XL",
+  "XXL"
 ];
+var SIZE_LABELS = {
+  XS: "half a person-day",
+  S: "one person-day",
+  M: "three person-days",
+  L: "one person-week",
+  XL: "two person-weeks",
+  XXL: "four person-weeks"
+};
+var SIZE_TABLE = WORK_ORDER_SIZE_ENUM.map(
+  (size) => `${size}=${SIZE_LABELS[size]} (${WORK_ORDER_SIZE_VALUE_UNITS[size]} VU)`
+).join(", ");
+var SIZE_BASIS = `Estimate the effort with NO AI assistance \u2014 the fully-human person-hours. Do NOT size what it will actually take with AI. Person-hours, not calendar time: two people for a week is XL, not L. ${SIZE_TABLE}.`;
+
+// ../../libs/harmonica-services/src/mcp/tools/work-item-tools.ts
+var WORK_ITEM_STATUS_ENUM = ["not_started", "in_progress", "blocked", "done"];
+function formatOwner(owner) {
+  return owner ? `${owner.name} <${owner.email}>` : "unassigned";
+}
 function registerWorkItemTools(server, _ctx, client) {
   server.tool(
     "list_track_work_items",
-    'List all work items under a Track (DeliverableGroup). A work item is an owned, statused unit of operational work. Recognition cues: "what work is on this track", "list the work items" \u2192 list_track_work_items.',
+    'List all work items under a Track. A work item is an owned, statused unit of operational work. Recognition cues: "what work is on this track", "list the work items" \u2192 list_track_work_items.',
     {
-      trackId: external_exports.string().describe("The Track (DeliverableGroup) ID")
+      trackId: external_exports.string().describe("The Track ID")
     },
     async ({ trackId }) => {
       const workItems = await client.listTrackWorkItems(trackId);
@@ -31920,15 +32175,15 @@ function registerWorkItemTools(server, _ctx, client) {
   );
   server.tool(
     "create_work_item",
-    'Create a work item under a Track (DeliverableGroup). A work item is an owned, statused unit of operational work \u2014 it is NOT a Beat. Starts in "not_started" status. Optionally link it to a Beat Version for capability lineage (v2, N-4E09-6574) \u2014 the link is one-directional and never required. Optionally link it to a Work Order it delivers part of; leaving it unattached is a supported state, not a gap to fill (N-4E09-7160). Optionally link it to a Bar it is planned into; leaving it unplanned is likewise a real state, not a gap (B-298).',
+    'Create a work item under a Track. A work item is an owned, statused unit of operational work \u2014 it is NOT a Beat. Starts in "not_started" status. Optionally link it to a Beat Version for capability lineage (v2, N-4E09-6574) \u2014 the link is one-directional and never required. Optionally link it to a Work Order it delivers part of; leaving it unattached is a supported state, not a gap to fill (N-4E09-7160). Optionally link it to a Bar it is planned into; leaving it unplanned is likewise a real state, not a gap (B-298).',
     {
-      trackId: external_exports.string().describe("The Track (DeliverableGroup) ID this work item belongs to"),
+      trackId: external_exports.string().describe("The Track ID this work item belongs to"),
       title: external_exports.string().min(1).max(300).describe("Work item title"),
       ownerName: external_exports.string().min(1).optional().describe("Optional owner display name (requires ownerEmail too)"),
       ownerEmail: external_exports.string().email().optional().describe("Optional owner email (requires ownerName too). A work item may be left unowned."),
       committedEstimateHours: external_exports.number().nonnegative().optional().describe("Optional committed estimate in hours"),
-      effortSize: external_exports.enum(WORK_ITEM_EFFORT_SIZE_ENUM).optional().describe("Optional rough t-shirt effort size (delivery lens) \u2014 independent of valueUnits"),
-      valueUnits: external_exports.number().nonnegative().optional().describe("Optional Value Units (commercial lens) \u2014 independent of effortSize"),
+      effortSize: external_exports.enum(WORK_ITEM_EFFORT_SIZE_ENUM).optional().describe(`Optional rough t-shirt effort size \u2014 seeds valueUnits. ${SIZE_BASIS}`),
+      valueUnits: external_exports.number().nonnegative().optional().describe(`Optional Value Units \u2014 fully-human person-hours. Defaults from effortSize; pass only to override. ${SIZE_BASIS}`),
       costPerValueUnit: external_exports.number().nonnegative().optional().describe("Optional price per Value Unit"),
       createdBy: external_exports.string().optional().describe("Optional creator identity for audit"),
       beatVersionId: external_exports.string().min(1).optional().describe("Optional Beat Version to link for capability lineage. Must exist."),
@@ -31976,7 +32231,9 @@ function registerWorkItemTools(server, _ctx, client) {
       unassignOwner: external_exports.boolean().optional().describe("Pass true to clear the owner, leaving the work item unowned. Cannot be combined with ownerName/ownerEmail."),
       committedEstimateHours: external_exports.number().nonnegative().optional().describe("New committed estimate in hours"),
       actualHours: external_exports.number().nonnegative().optional().describe("New actual hours logged"),
-      effortSize: external_exports.enum(WORK_ITEM_EFFORT_SIZE_ENUM).nullable().optional().describe("Rough t-shirt effort size (delivery lens). Pass null to clear; omit to leave untouched."),
+      effortSize: external_exports.enum(WORK_ITEM_EFFORT_SIZE_ENUM).nullable().optional().describe(
+        `Rough t-shirt effort size. Pass null to clear; omit to leave untouched. ${SIZE_BASIS}`
+      ),
       valueUnits: external_exports.number().nonnegative().nullable().optional().describe("Value Units (commercial lens). Pass null to clear; omit to leave untouched."),
       costPerValueUnit: external_exports.number().nonnegative().nullable().optional().describe("Price per Value Unit. Pass null to clear; omit to leave untouched."),
       beatVersionId: external_exports.string().min(1).nullable().optional().describe("Link to a Beat Version for capability lineage. Pass null to unlink; omit to leave the current link untouched."),
@@ -32037,10 +32294,10 @@ function registerWorkItemTools(server, _ctx, client) {
   );
   server.tool(
     "move_work_item",
-    "Move a work item to a different Track (DeliverableGroup). Re-derives its teamspace/org scope from the new Track.",
+    "Move a work item to a different Track. Re-derives its teamspace/org scope from the new Track.",
     {
       workItemId: external_exports.string().describe("The work item ID"),
-      newTrackId: external_exports.string().describe("The destination Track (DeliverableGroup) ID. Must exist.")
+      newTrackId: external_exports.string().describe("The destination Track ID. Must exist.")
     },
     async ({ workItemId, newTrackId }) => {
       const wi = await client.moveWorkItem(workItemId, newTrackId);
@@ -32083,13 +32340,12 @@ function registerWorkItemTools(server, _ctx, client) {
 }
 
 // ../../libs/harmonica-services/src/tool-schemas/work-order.ts
-var WORK_ORDER_SIZE_ENUM = ["XS", "S", "M", "L", "XL"];
 var create_work_order = {
   workRequestId: external_exports.string().min(1).describe("The Work Request this order was split from \u2014 immutable lineage"),
   title: external_exports.string().min(1).max(300).describe("Work order title"),
   description: external_exports.string().max(1e4).optional().describe("Optional detail beyond the title"),
   size: external_exports.enum(WORK_ORDER_SIZE_ENUM).optional().describe(
-    "Optional t-shirt size. An order can arrive before it is sized; a request's composition counts unsized orders rather than hiding them."
+    "Optional t-shirt size. An order can arrive before it is sized; a request's composition counts unsized orders rather than hiding them. " + SIZE_BASIS
   ),
   createdBy: external_exports.string().optional().describe("Optional creator identity for audit")
 };
@@ -32112,13 +32368,6 @@ var NEEDS_DECISION_REASON_ENUM = [
   "exceeds_capacity",
   "incoherent_with_decision"
 ];
-var WORK_ORDER_SIZE_ENUM2 = [
-  "XS",
-  "S",
-  "M",
-  "L",
-  "XL"
-];
 function oneLine(value) {
   return value.replace(/[\r\n]+/g, " ");
 }
@@ -32134,14 +32383,14 @@ function registerWorkOrderTools(server, _ctx, client) {
     // exactly the caller this alias exists to greet. Requiring it would answer
     // the migrated caller with a schema error instead of the migration message.
     {
-      trackId: external_exports.string().optional().describe("Ignored \u2014 the Track (DeliverableGroup) ID is no longer meaningful for Order scoping")
+      trackId: external_exports.string().optional().describe("Ignored \u2014 the Track ID is no longer meaningful for Order scoping")
     },
     async () => {
       return {
         content: [
           {
             type: "text",
-            text: "list_track_work_orders is deprecated. Use list_movement_work_orders(movementId) to fetch all Orders for an engagement \u2014 Orders are now scoped to their Movement, not their Track. If you have only a Track id, its Movement is on the Track itself: get_deliverable_group(trackId) returns movementId."
+            text: "list_track_work_orders is deprecated. Use list_movement_work_orders(movementId) to fetch all Orders for an engagement \u2014 Orders are now scoped to their Movement, not their Track. If you have only a Track id, its Movement is on the Track itself: get_track(trackId) returns movementId."
           }
         ],
         // The caller asked for a list and is getting none. A result without
@@ -32226,7 +32475,9 @@ function registerWorkOrderTools(server, _ctx, client) {
       workOrderId: external_exports.string().describe("The Work Order ID"),
       title: external_exports.string().min(1).max(300).optional().describe("New title"),
       description: external_exports.string().max(1e4).nullable().optional().describe("New description. Pass null to clear; omit to leave untouched."),
-      size: external_exports.enum(WORK_ORDER_SIZE_ENUM2).nullable().optional().describe("New t-shirt size. Pass null to return it to unsized; omit to leave untouched.")
+      size: external_exports.enum(WORK_ORDER_SIZE_ENUM).nullable().optional().describe(
+        "New t-shirt size. Pass null to return it to unsized; omit to leave untouched. " + SIZE_BASIS
+      )
     },
     async ({ workOrderId, title, description, size }) => {
       if (title === void 0 && description === void 0 && size === void 0) {
@@ -32256,7 +32507,7 @@ function registerWorkOrderTools(server, _ctx, client) {
     // the callers who have already stopped sending these.
     {
       workOrderId: external_exports.string().optional().describe("Ignored \u2014 a Work Order is no longer moveable between Tracks"),
-      newTrackId: external_exports.string().optional().describe("Ignored \u2014 a Track (DeliverableGroup) is no longer a valid parent for Orders")
+      newTrackId: external_exports.string().optional().describe("Ignored \u2014 a Track is no longer a valid parent for Orders")
     },
     async () => {
       return {
@@ -32458,6 +32709,14 @@ function registerWorkRequestTools(server, _ctx, client) {
   );
 }
 
+// ../../libs/harmonica-services/src/work-item-ids.ts
+function normalizeWorkItemIds(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(
+    value.filter((id) => typeof id === "string").map((id) => id.trim()).filter(Boolean)
+  )];
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/workflow-tools.ts
 var TASK_STATUSES = ["pending", "running", "completed", "failed"];
 function registerWorkflowTools(server, ctx, client) {
@@ -32648,17 +32907,19 @@ ${JSON.stringify(task.result, null, 2)}
       systemId: external_exports.string().min(1).describe("The system ID \u2014 the trusted scope the session is rooted at"),
       message: external_exports.string().min(1).describe("Free-form first message describing what the session should do"),
       revisionId: external_exports.string().min(1).optional().describe("Optional Revision ID (rev-<uuid>). When provided, the Worker routes to the typed implementation session path (prepareRevisionImplementationSession), enabling file hint generation and richer session context. Omit for investigation, planning, or freeform sessions."),
+      workItemIds: external_exports.array(external_exports.string().min(1)).max(50).optional().describe("Optional Work Items associated with this session at kickoff. Each moves to in_progress when execution starts; the agent manages each item outcome independently."),
       parentSessionId: external_exports.string().min(1).optional().describe("Your current Session ID (sess-<uuid>). Pass it when you are kicking off this session as part of your own work \u2014 the new session then nests under yours in the session tree and can report back to you. Omit for a standalone session.")
     },
-    async ({ systemId, message, revisionId, parentSessionId }) => {
+    async ({ systemId, message, revisionId, workItemIds, parentSessionId }) => {
       try {
         await assertSystemExists(client, systemId);
         const task = await client.startSession(
           systemId,
           message,
           { name: ctx.user.name, email: ctx.user.email },
-          revisionId?.trim() || parentSessionId?.trim() ? {
+          revisionId?.trim() || workItemIds?.length || parentSessionId?.trim() ? {
             ...revisionId?.trim() && { revisionId: revisionId.trim() },
+            ...workItemIds?.length && { workItemIds: normalizeWorkItemIds(workItemIds) },
             ...parentSessionId?.trim() && { parentSessionId: parentSessionId.trim() }
           } : void 0
         );
@@ -32886,6 +33147,7 @@ var TOOL_PROFILES = Object.freeze({
     registerOrganizationTools,
     registerTeamspaceTools,
     registerMembershipTools,
+    registerManagedRelationshipTools,
     registerSystemTools,
     registerSystemLifecycleTools,
     allow(registerBeatVersionTools, ["relocate_beat_version"])
@@ -32965,6 +33227,7 @@ function registerAllTools(server, ctx, client, profile) {
   registerValueVelocityTools(server, ctx, client);
   registerNotebookTools(server, ctx, client);
   registerAccountTools(server, ctx, client);
+  registerManagedRelationshipTools(server, ctx, client);
   registerMovementTools(server, ctx, client);
   registerExternalMappingTools(server, ctx, client);
   registerWorkItemTools(server, ctx, client);
@@ -33664,6 +33927,8 @@ function createHttpClient(config2) {
       return { revision: result.revision, warnings: result.warnings ?? [] };
     },
     getRevision: (revisionId) => request("GET", `/api/revisions/${encodeURIComponent(revisionId)}`),
+    // `request` maps 404 to undefined, which is what absence must be here.
+    resolveRevisionPreview: (revisionId) => request("GET", `/api/revisions/${encodeURIComponent(revisionId)}/preview`),
     listConceptRevisions: async (systemId, options) => {
       const qs = options?.includeArchived ? "?includeArchived=true" : "";
       const result = await request("GET", `/api/systems/${encodeURIComponent(systemId)}/revisions/pending${qs}`);
@@ -34305,6 +34570,7 @@ function createHttpClient(config2) {
     // Agent sessions
     startSession: async (systemId, message, triggeredBy, options) => {
       const trimmedRevisionId = options?.revisionId?.trim();
+      const workItemIds = normalizeWorkItemIds(options?.workItemIds);
       const trimmedParentSessionId = options?.parentSessionId?.trim();
       const result = await request(
         "POST",
@@ -34314,6 +34580,7 @@ function createHttpClient(config2) {
           message,
           ...triggeredBy && { triggeredBy },
           ...trimmedRevisionId && { revisionId: trimmedRevisionId },
+          ...workItemIds?.length && { workItemIds },
           ...trimmedParentSessionId && { parentSessionId: trimmedParentSessionId }
         }
       );
@@ -34952,6 +35219,31 @@ function createHttpClient(config2) {
       const res = await request("GET", `/api/accounts/${encodeURIComponent(accountId)}/movements`);
       return res?.movements ?? [];
     },
+    createManagedRelationship: async (input) => {
+      const { agencyOrgId, ...body } = input;
+      const result = await request(
+        "POST",
+        `/api/organizations/${encodeURIComponent(agencyOrgId)}/managed-relationships`,
+        body
+      );
+      if (result === void 0) throw new Error("Resource not found when creating managed relationship");
+      return result;
+    },
+    getManagedRelationship: async (relationshipId) => request("GET", `/api/managed-relationships/${encodeURIComponent(relationshipId)}`),
+    listManagedRelationships: async (agencyOrgId) => {
+      const result = await request(
+        "GET",
+        `/api/organizations/${encodeURIComponent(agencyOrgId)}/managed-relationships`
+      );
+      return result?.relationships ?? [];
+    },
+    setManagedRelationshipStatus: async (relationshipId, status) => {
+      return request(
+        "PATCH",
+        `/api/managed-relationships/${encodeURIComponent(relationshipId)}/status`,
+        { status }
+      );
+    },
     listChildAccounts: async (accountId) => {
       const res = await request("GET", `/api/accounts/${encodeURIComponent(accountId)}/children`);
       return res?.accounts ?? [];
@@ -35471,7 +35763,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"5.1.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"5.3.0"} starting\u2026`);
   const config2 = loadConfig();
   const client = createHttpClient({
     apiBaseUrl: config2.apiBaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codazen/harmonica-mcp",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "description": "MCP server for Harmonica — connect any MCP-compatible AI assistant to Harmonica",
   "license": "MIT",
   "bin": {