@everfir/az8-cli 0.3.0-preview.1 → 0.3.0-preview.3

package/dist/main.js

@@ -14175,11 +14175,47 @@ var CANVAS_OPERATION_REGISTRY = [
     },
     required: ["referenceViewNodeId", "viewNodeId"]
   }),
+  write2("insertPromptReference", "Bind one visible image, text, or video View Node and place its platform At token in the Prompt", "silent", {
+    properties: {
+      placement: {
+        anyOf: [
+          { enum: ["start", "end"], type: "string" },
+          {
+            additionalProperties: false,
+            properties: {
+              anchor: {
+                additionalProperties: false,
+                properties: {
+                  occurrence: { minimum: 1, type: "integer" },
+                  text: stringSchema()
+                },
+                required: ["text"],
+                type: "object"
+              },
+              kind: { enum: ["before", "after"], type: "string" }
+            },
+            required: ["anchor", "kind"],
+            type: "object"
+          }
+        ]
+      },
+      referenceViewNodeId: stringSchema(),
+      viewNodeId: stringSchema()
+    },
+    required: ["referenceViewNodeId", "viewNodeId"]
+  }),
   write2("removeVisualReference", "Remove one Canvas View Node reference from a generation Draft", "silent", {
     properties: { referenceId: stringSchema(), viewNodeId: stringSchema() },
     required: ["referenceId", "viewNodeId"]
   }),
   write2("startGeneration", "Estimate current Draft inputs, start a Workflow Run, and acknowledge immediate Canvas writes", "barrier", { properties: { viewNodeId: stringSchema() }, required: ["viewNodeId"] }, "workflow-accepted"),
+  write2("reconcileGenerationStart", "Reconcile one known Workflow Run with its target without starting another Run", "barrier", {
+    properties: {
+      viewNodeId: stringSchema(),
+      workflowRunId: stringSchema()
+    },
+    required: ["viewNodeId", "workflowRunId"]
+  }),
   read("getWorkflowRun", "Read one Workflow Run", {
     properties: { workflowRunId: stringSchema() },
     required: ["workflowRunId"]
@@ -14246,10 +14282,25 @@ function sizeSchema() {
 }
 
 // ../../packages/project-canvas-runtime/dist/operation-usage.js
+function attachCanvasOperationIndeterminateResult(value, result3) {
+  const cause = value instanceof Error ? value : new Error("Unexpected Canvas Operation failure.");
+  const error51 = new Error(cause.message, { cause });
+  return Object.assign(error51, {
+    indeterminate: true,
+    operationResult: structuredClone(result3),
+    ..."timedOut" in cause && cause.timedOut === true ? { timedOut: true } : {}
+  });
+}
 function attachCanvasOperationUsage(value, usage) {
   const error51 = value instanceof Error ? value : new Error("Unexpected Canvas Operation failure.");
   return Object.assign(error51, { operationUsage: usage });
 }
+function readCanvasOperationIndeterminateResult(value) {
+  if (typeof value !== "object" || value === null || !("operationResult" in value))
+    return void 0;
+  const result3 = value.operationResult;
+  return typeof result3 === "object" && result3 !== null && !Array.isArray(result3) ? result3 : void 0;
+}
 function readCanvasOperationUsage(value) {
   if (typeof value !== "object" || value === null || !("operationUsage" in value))
     return void 0;
@@ -15022,6 +15073,37 @@ function addVisualReferenceToDraft(draft, definition, reference, sourceDataType,
   }
   return appendPromptReferenceToken(nextDraft, slot.name, reference.id, reference.viewNodeId, now);
 }
+function insertPromptReferenceIntoDraft(draft, definition, reference, sourceDataType, placement, now) {
+  const withReference = addVisualReferenceToDraft(draft, definition, reference, sourceDataType, now);
+  const binding = Object.entries(withReference.inputs.slots).flatMap(([slotName, values]) => values.flatMap((value, index) => value.kind === "view-node" && value.id === reference.id ? [{ index, slotName, value }] : []))[0];
+  if (!binding)
+    throw new Error(`Generation Reference ${reference.id} does not exist in the Draft.`);
+  if (binding.value.sourceDataType !== "image" && binding.value.sourceDataType !== "text" && binding.value.sourceDataType !== "video") {
+    throw new Error("Prompt References must resolve to image, text, or video content.");
+  }
+  const promptSlot = requirePromptSlot(definition);
+  const withoutExistingToken = removePromptReferenceToken(withReference, reference.id);
+  const promptValues = withoutExistingToken.inputs.slots[promptSlot.name] ?? [];
+  const existingLiteral = promptValues.find((value) => value.kind === "literal" && value.assetType === "text");
+  const promptInput = existingLiteral ?? literal(withoutExistingToken, promptSlot.name, "text", "");
+  const prompt = promptInput.content;
+  const token = `{{@${binding.value.sourceDataType}:${binding.slotName}:${binding.index}:${reference.id}|view-node|${encodeURIComponent(reference.viewNodeId)}}}`;
+  const content = placement === "start" ? prompt.trim() ? `${token}
+${prompt}` : token : placement === "end" ? prompt.trim() ? `${prompt}${prompt.endsWith("\n") ? "" : "\n"}${token}` : token : insertAtPromptAnchor(prompt, token, placement);
+  return {
+    ...structuredClone(withoutExistingToken),
+    inputs: {
+      slots: {
+        ...structuredClone(withoutExistingToken.inputs.slots),
+        [promptSlot.name]: [
+          { ...promptInput, content },
+          ...promptValues.filter((value) => value.id !== promptInput.id)
+        ]
+      }
+    },
+    updatedAt: now
+  };
+}
 function removeVisualReferenceFromDraft(draft, referenceId, now) {
   let removed = false;
   let removedTextReference = false;
@@ -15068,21 +15150,57 @@ function appendPromptReferenceToken(draft, slotName, referenceId, viewNodeId, no
   };
 }
 function removePromptReferenceToken(draft, referenceId) {
-  const pattern = new RegExp(PROMPT_REFERENCE_TOKEN_PATTERN, "g");
   const slots = Object.fromEntries(Object.entries(draft.inputs.slots).map(([slotName, values]) => [
     slotName,
     values.map((value) => {
       if (value.kind !== "literal" || value.assetType !== "text")
         return value;
-      const lines = value.content.split("\n").flatMap((line) => {
-        const content = line.replace(pattern, (token, _type, _slot, _index, bindingId) => bindingId === referenceId ? "" : token);
-        return content.trim() ? [content] : [];
-      });
-      return { ...value, content: lines.join("\n") };
+      return { ...value, content: removeReferenceTokenFromContent(value.content, referenceId) };
     })
   ]));
   return { ...draft, inputs: { slots } };
 }
+function insertAtPromptAnchor(prompt, token, placement) {
+  const anchor = placement.anchor.text;
+  if (!anchor.trim())
+    throw new Error("placement.anchor.text must be non-empty.");
+  const indexes = [];
+  let from2 = 0;
+  while (from2 <= prompt.length - anchor.length) {
+    const index2 = prompt.indexOf(anchor, from2);
+    if (index2 < 0)
+      break;
+    indexes.push(index2);
+    from2 = index2 + Math.max(anchor.length, 1);
+  }
+  if (indexes.length === 0) {
+    throw new Error(`Prompt anchor ${JSON.stringify(anchor)} does not exist.`);
+  }
+  const occurrence = placement.anchor.occurrence;
+  if (occurrence === void 0 && indexes.length !== 1) {
+    throw new Error(`Prompt anchor ${JSON.stringify(anchor)} is ambiguous; placement.anchor.occurrence is required.`);
+  }
+  const index = indexes[(occurrence ?? 1) - 1];
+  if (index === void 0) {
+    throw new Error(`Prompt anchor ${JSON.stringify(anchor)} does not have occurrence ${String(occurrence)}.`);
+  }
+  const insertionIndex = placement.kind === "before" ? index : index + anchor.length;
+  return `${prompt.slice(0, insertionIndex)}${token}${prompt.slice(insertionIndex)}`;
+}
+function removeReferenceTokenFromContent(content, referenceId) {
+  const matches2 = [...content.matchAll(new RegExp(PROMPT_REFERENCE_TOKEN_PATTERN, "g"))].filter((match) => match[4] === referenceId);
+  let next = content;
+  for (const match of matches2.reverse()) {
+    let start = match.index;
+    let end = start + match[0].length;
+    if (start === 0 && next[end] === "\n")
+      end += 1;
+    else if (end === next.length && next[start - 1] === "\n")
+      start -= 1;
+    next = `${next.slice(0, start)}${next.slice(end)}`;
+  }
+  return next;
+}
 function createDefaultSlots(definition) {
   return Object.fromEntries(definition.inputSchema.map((slot) => {
     if (slot.defaultValue === void 0)
@@ -15322,7 +15440,8 @@ function createGenerationExecutionOperations(input) {
   if (definitionChanges || Object.keys(editInput).length > 2) {
     operations.push({ input: editInput, name: "editGenerationDraft" });
   }
-  const currentReferences = definitionChanges ? [] : readGenerationDraftReferences(input.currentDraft);
+  const promptSlotName = resolvePromptSlot(input.definition)?.name;
+  const currentReferences = (definitionChanges ? [] : readGenerationDraftReferences(input.currentDraft)).filter((reference) => editInput.prompt === void 0 || reference.sourceSlotName !== promptSlotName);
   const desiredKeys = new Set(input.assignments.map((item) => referenceKey(item.reference)));
   for (const current of currentReferences) {
     if (!current.draftInputId || desiredKeys.has(referenceKey(current)))
@@ -15823,7 +15942,14 @@ async function resolveEffectiveTextInputContent(input) {
   if (!literal3)
     return null;
   const fragmentsByBindingId = /* @__PURE__ */ new Map();
-  for (const reference of input.references) {
+  const bindingsById = /* @__PURE__ */ new Map();
+  for (const [slotName, references] of Object.entries(input.allReferencesBySlot)) {
+    for (const reference of references) {
+      if (reference.kind !== "literal")
+        bindingsById.set(reference.id, { reference, slotName });
+    }
+  }
+  for (const reference of Object.values(input.allReferencesBySlot).flat()) {
     if (reference.kind !== "view-node" || reference.sourceDataType !== "text")
       continue;
     const content = await input.resolveViewNodeTextContent(reference.viewNodeId);
@@ -15831,8 +15957,17 @@ async function resolveEffectiveTextInputContent(input) {
       fragmentsByBindingId.set(reference.id, content.trim());
   }
   const positionedBindingIds = /* @__PURE__ */ new Set();
-  const positionedContent = literal3.content.replace(new RegExp(PROMPT_REFERENCE_TOKEN_PATTERN2, "g"), (token, _contentType, _slotName, _index, bindingId) => {
+  const positionedContent = literal3.content.replace(new RegExp(PROMPT_REFERENCE_TOKEN_PATTERN2, "g"), (token, contentType, slotName, _rawIndex, bindingId, encodedViewNodeId) => {
     if (!bindingId)
+      throw new Error("Prompt contains an At token without a binding identity.");
+    const binding = bindingsById.get(bindingId);
+    if (!binding || binding.slotName !== slotName || binding.reference.sourceDataType !== contentType) {
+      throw new Error(`Prompt At token ${bindingId} does not match its Generation binding.`);
+    }
+    if (encodedViewNodeId && (binding.reference.kind !== "view-node" || binding.reference.viewNodeId !== decodePromptViewNodeId(encodedViewNodeId))) {
+      throw new Error(`Prompt At token ${bindingId} does not match its View Node.`);
+    }
+    if (contentType !== "text")
       return token;
     const content = fragmentsByBindingId.get(bindingId);
     if (content === void 0)
@@ -15841,11 +15976,21 @@ async function resolveEffectiveTextInputContent(input) {
     return content;
   });
   const trailingFragments = [...fragmentsByBindingId.entries()].flatMap(([bindingId, content]) => positionedBindingIds.has(bindingId) ? [] : [content]);
-  if (new RegExp(PROMPT_REFERENCE_TOKEN_PATTERN2).test(positionedContent)) {
+  const unresolvedTextToken = [
+    ...positionedContent.matchAll(new RegExp(PROMPT_REFERENCE_TOKEN_PATTERN2, "g"))
+  ].some((match) => match[1] === "text");
+  if (unresolvedTextToken) {
     throw new Error("Prompt contains an unresolved Text View Node reference.");
   }
   return appendUniqueTextFragments(positionedContent, trailingFragments);
 }
+function decodePromptViewNodeId(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    throw new Error("Prompt At token contains an invalid View Node identity.");
+  }
+}
 function appendUniqueTextFragments(base, fragments) {
   let result3 = base;
   for (const fragment of fragments) {
@@ -15865,6 +16010,7 @@ async function prepareGenerationInput(input) {
   for (const slot of input.definition.inputSchema) {
     const references = input.draft.inputs.slots[slot.name] ?? [];
     const effectiveText = slot.name === promptSlot?.name ? await resolveEffectiveTextInputContent({
+      allReferencesBySlot: input.draft.inputs.slots,
       references,
       resolveViewNodeTextContent: input.resolveViewNodeTextContent
     }) : null;
@@ -15981,10 +16127,15 @@ var CoreNodeCreativeLoop = class {
       return this.editDraft(input, timeoutMs);
     if (name === "addVisualReference")
       return this.addVisualReference(input, timeoutMs);
+    if (name === "insertPromptReference")
+      return this.insertPromptReference(input, timeoutMs);
     if (name === "removeVisualReference")
       return this.removeVisualReference(input, timeoutMs);
     if (name === "startGeneration")
       return this.startGeneration(input, timeoutMs);
+    if (name === "reconcileGenerationStart") {
+      return this.reconcileGenerationStart(input, timeoutMs);
+    }
     if (name === "getWorkflowRun")
       return this.getWorkflowRun(input);
     if (name === "waitWorkflowRun")
@@ -16011,6 +16162,18 @@ var CoreNodeCreativeLoop = class {
     for (const id2 of ids)
       await this.recoverWorkflowRun(id2, timeoutMs);
   }
+  observePendingWorkflowRuns(ids, timeoutMs) {
+    for (const id2 of new Set(ids)) {
+      if (!this.isPending(id2))
+        continue;
+      void this.recoverWorkflowRun(id2, timeoutMs).catch((error51) => {
+        if (isSettlementWriteAttempt(error51))
+          this.context.reportBackgroundError(error51);
+        else
+          this.scheduleWorkflowRunRecovery(id2, timeoutMs, error51);
+      });
+    }
+  }
   close() {
     this.closed = true;
     for (const subscription of this.subscriptions.values())
@@ -16160,23 +16323,26 @@ var CoreNodeCreativeLoop = class {
     const draft = requireDraft(target);
     const definition = await this.requireDefinition(draft.definitionId);
     const referenceViewNodeId = requireString3(input.referenceViewNodeId, "referenceViewNodeId");
-    const referenceViewNode = this.requireViewNode(referenceViewNodeId);
-    if (referenceViewNode.type !== "resource") {
-      throw new Error("Generation References require a resource View Node.");
-    }
-    let sourceDataType = referenceViewNode.contentType ?? "";
-    const referenceCoreNodeId = this.resolveViewNodeCoreNodeId(referenceViewNode);
-    if (sourceDataType !== "text" || asRecord3(referenceViewNode.data).mode === "content") {
-      if (!referenceCoreNodeId)
-        throw new Error("Referenced View Node has no current Core Node.");
-      const coreNode = await this.requireCoreNode(referenceCoreNodeId);
-      sourceDataType = readCoreNodeDataType2(coreNode);
-    }
+    const sourceDataType = await this.resolveReferenceDataType(referenceViewNodeId);
     const referenceId = `input_ref_${crypto.randomUUID().replaceAll("-", "")}`;
     const nextDraft = addVisualReferenceToDraft(draft, definition, { id: referenceId, kind: "view-node", viewNodeId: referenceViewNodeId }, sourceDataType, this.context.now());
     await this.replaceDraft(target, nextDraft, "Add Visual Reference", timeoutMs);
     return attention(target.id, { referenceId, viewNodeId: target.id });
   }
+  async insertPromptReference(input, timeoutMs) {
+    assertOnlyKeys3(input, ["placement", "referenceViewNodeId", "viewNodeId"]);
+    const target = this.requireTarget(requireString3(input.viewNodeId, "viewNodeId"));
+    const draft = requireDraft(target);
+    const definition = await this.requireDefinition(draft.definitionId);
+    const referenceViewNodeId = requireString3(input.referenceViewNodeId, "referenceViewNodeId");
+    const sourceDataType = await this.resolveReferenceDataType(referenceViewNodeId);
+    const existing = Object.values(draft.inputs.slots).flat().find((reference) => reference.kind === "view-node" && reference.viewNodeId === referenceViewNodeId);
+    const referenceId = existing?.id ?? `input_ref_${crypto.randomUUID().replaceAll("-", "")}`;
+    const placement = parsePromptReferencePlacement(input.placement);
+    const nextDraft = insertPromptReferenceIntoDraft(draft, definition, { id: referenceId, kind: "view-node", viewNodeId: referenceViewNodeId }, sourceDataType, placement, this.context.now());
+    await this.replaceDraft(target, nextDraft, "Insert Prompt Reference", timeoutMs);
+    return attention(target.id, { placement, referenceId, viewNodeId: target.id });
+  }
   async removeVisualReference(input, timeoutMs) {
     assertOnlyKeys3(input, ["referenceId", "viewNodeId"]);
     const target = this.requireTarget(requireString3(input.viewNodeId, "viewNodeId"));
@@ -16187,7 +16353,8 @@ var CoreNodeCreativeLoop = class {
   }
   async startGeneration(input, timeoutMs) {
     let estimate;
-    let runAccepted = false;
+    let acceptedRun;
+    let acceptedTargetId;
     try {
       assertOnlyKeys3(input, ["viewNodeId"]);
       const target = this.requireTarget(requireString3(input.viewNodeId, "viewNodeId"));
@@ -16200,6 +16367,10 @@ var CoreNodeCreativeLoop = class {
         resolveViewNodeCoreNodeId: (id2) => this.resolveViewNodeCoreNodeId(this.requireViewNode(id2)),
         resolveViewNodeTextContent: (id2) => this.resolveViewNodeTextContent(this.requireViewNode(id2))
       });
+      const targetSnapshot = structuredClone(target);
+      const targetData = normalizeOptionalRecord(target.data, "View Node data");
+      const targetHistory = readGenerationHistory(target.history);
+      const effectivePrompt = readPrompt(prepared.effectiveDraft);
       estimate = await this.systems.workflowRuntime.estimateRun({ definitionId: definition.id, inputs: prepared.estimateInputs }, { timeoutMs });
       if (!estimate.canAfford)
         throw new Error("Insufficient credits to start this generation.");
@@ -16218,7 +16389,8 @@ var CoreNodeCreativeLoop = class {
           { slotName: output.slotName, targetId: target.id, targetSlot: draft.id }
         ]
       }, { timeoutMs });
-      runAccepted = true;
+      acceptedRun = run;
+      acceptedTargetId = target.id;
       this.runs.set(run.id, run);
       const timestamp = this.context.now();
       const historyEntry = {
@@ -16234,15 +16406,15 @@ var CoreNodeCreativeLoop = class {
         },
         updatedAt: timestamp
       };
-      const { creationIntent: _creationIntent, ...data } = asRecord3(target.data);
+      const { creationIntent: _creationIntent, ...data } = targetData;
       const after = {
-        ...structuredClone(target),
+        ...targetSnapshot,
         data: {
           ...data,
-          ...readPrompt(prepared.effectiveDraft) === null ? {} : { prompt: readPrompt(prepared.effectiveDraft) }
+          ...effectivePrompt === null ? {} : { prompt: effectivePrompt }
         },
         draft: null,
-        history: toDocumentJson([...readGenerationHistory(target.history), historyEntry]),
+        history: toDocumentJson([...targetHistory, historyEntry]),
         updatedAt: timestamp
       };
       await this.context.commit({
@@ -16264,8 +16436,15 @@ var CoreNodeCreativeLoop = class {
         usage: estimatedUsage(estimate)
       };
     } catch (error51) {
-      const usage = runAccepted && estimate ? estimatedUsage(estimate) : isIndeterminateWrite(error51) ? unknownUsage(estimate) : notConsumedUsage(estimate);
-      throw attachCanvasOperationUsage(error51, usage);
+      const failure = acceptedRun && acceptedTargetId ? attachCanvasOperationIndeterminateResult(error51, {
+        canvasAcknowledged: false,
+        reconciliationRequired: true,
+        status: acceptedRun.status,
+        viewNodeId: acceptedTargetId,
+        workflowRunId: acceptedRun.id
+      }) : error51;
+      const usage = acceptedRun && estimate ? estimatedUsage(estimate) : isIndeterminateWrite(error51) ? unknownUsage(estimate) : notConsumedUsage(estimate);
+      throw attachCanvasOperationUsage(failure, usage);
     }
   }
   async getWorkflowRun(input) {
@@ -16273,6 +16452,133 @@ var CoreNodeCreativeLoop = class {
     const run = await this.refreshRun(requireString3(input.workflowRunId, "workflowRunId"), 15e3);
     return { result: { workflowRun: run } };
   }
+  async reconcileGenerationStart(input, timeoutMs) {
+    assertOnlyKeys3(input, ["viewNodeId", "workflowRunId"]);
+    const target = this.requireTarget(requireString3(input.viewNodeId, "viewNodeId"));
+    const workflowRunId = requireString3(input.workflowRunId, "workflowRunId");
+    const run = await this.systems.workflowRuntime.getRun(workflowRunId);
+    if (!run)
+      throw new Error(`Workflow Run ${workflowRunId} does not exist.`);
+    this.recordRun(run);
+    const sync = await this.systems.projectContent.syncProject(this.context.projectId, 0, {
+      timeoutMs
+    });
+    this.projection.merge(sync.contents);
+    const history = readGenerationHistory(target.history);
+    const existing = history.find((entry) => entry.runtime.instanceIds.includes(run.id));
+    if (existing) {
+      if (existing.definitionId !== run.definitionId) {
+        return reconciliationResult(target.id, run.id, "conflict", {
+          reason: "The existing History entry and Workflow Run use different Definitions."
+        });
+      }
+      const repairedPendingState = !isTerminalWorkflowRunStatus(run.status) && !this.isPending(run.id);
+      if (isTerminalWorkflowRunStatus(run.status))
+        await this.settleRun(run, timeoutMs);
+      else if (repairedPendingState) {
+        await this.context.commit({
+          addPendingWorkflowInstanceIds: [run.id],
+          after: [],
+          before: [],
+          history: "barrier",
+          label: "Reconcile generation start",
+          timeoutMs
+        });
+        this.watchRun(run.id, timeoutMs);
+      }
+      return reconciliationResult(target.id, run.id, "consistent", {
+        repairedPendingState,
+        workflowStatus: run.status
+      });
+    }
+    const draft = readGenerationDraft(target.draft);
+    if (!draft) {
+      return reconciliationResult(target.id, run.id, "conflict", {
+        reason: "The target has neither a matching History entry nor its original Draft.",
+        workflowStatus: run.status
+      });
+    }
+    if (draft.definitionId !== run.definitionId) {
+      return reconciliationResult(target.id, run.id, "conflict", {
+        reason: "The target Draft and Workflow Run use different Definitions.",
+        workflowStatus: run.status
+      });
+    }
+    if (!isTerminalWorkflowRunStatus(run.status)) {
+      return reconciliationResult(target.id, run.id, "running-insufficient", {
+        reason: "The running Workflow does not yet expose authoritative target output evidence. Wait for a terminal state; do not start another Run.",
+        workflowStatus: run.status
+      });
+    }
+    if (run.status !== "completed") {
+      return reconciliationResult(target.id, run.id, "terminal", {
+        reason: "The Workflow ended without a completed output, so no History entry was invented.",
+        workflowStatus: run.status
+      });
+    }
+    const submittedAt = parseWorkflowTimestamp(run.createdAt);
+    if (submittedAt === null) {
+      return reconciliationResult(target.id, run.id, "insufficient", {
+        reason: "The completed Workflow Run has no trustworthy submission timestamp.",
+        workflowStatus: run.status
+      });
+    }
+    if ((draft.updatedAt ?? draft.createdAt) > submittedAt) {
+      return reconciliationResult(target.id, run.id, "conflict", {
+        reason: "The target Draft changed after the Workflow Run was submitted.",
+        workflowStatus: run.status
+      });
+    }
+    const definition = await this.requireDefinition(run.definitionId);
+    const primaryOutput = requirePrimaryOutput(definition, target.contentType);
+    const targetOutputs = sync.contents.filter((content) => content.sourceId === run.id || content.workflowInstanceId === run.id).flatMap((content) => content.outputs).filter((output) => output.targetId === target.id && output.targetSlot === draft.id && output.slotName === primaryOutput.slotName);
+    if (targetOutputs.length === 0) {
+      return reconciliationResult(target.id, run.id, "insufficient", {
+        reason: "The completed Workflow Run has no Project Content output bound to this target and Draft.",
+        workflowStatus: run.status
+      });
+    }
+    const outputCoreNodeIds = new Set(run.outputs.map((output) => output.coreNodeId));
+    if (outputCoreNodeIds.size > 0 && targetOutputs.every((output) => !outputCoreNodeIds.has(output.coreNodeId))) {
+      return reconciliationResult(target.id, run.id, "conflict", {
+        reason: "Workflow and Project Content outputs disagree.",
+        workflowStatus: run.status
+      });
+    }
+    const timestamp = this.context.now();
+    const historyEntry = {
+      ...draft,
+      runtime: {
+        ...run.definitionVersion === void 0 ? {} : { expectedDefinitionVersion: run.definitionVersion },
+        instanceIds: [run.id],
+        materializedInputs: inferReconciledMaterializedInputs(draft, run),
+        originClientId: "unknown",
+        submittedAt
+      },
+      updatedAt: timestamp
+    };
+    const { creationIntent: _creationIntent, ...data } = normalizeOptionalRecord(target.data, "View Node data");
+    const prompt = readPrompt(draft);
+    const after = {
+      ...structuredClone(target),
+      data: { ...data, ...prompt === null ? {} : { prompt } },
+      draft: null,
+      history: toDocumentJson([...history, historyEntry]),
+      updatedAt: timestamp
+    };
+    await this.context.commit({
+      after: [after],
+      before: [target],
+      history: "barrier",
+      label: "Reconcile generation start",
+      ...this.isPending(run.id) ? { removePendingWorkflowInstanceIds: [run.id] } : {},
+      timeoutMs
+    });
+    return reconciliationResult(target.id, run.id, "repaired", {
+      outputCoreNodeIds: [...new Set(targetOutputs.map((output) => output.coreNodeId))],
+      workflowStatus: run.status
+    });
+  }
   async waitWorkflowRun(input, timeoutMs) {
     assertOnlyKeys3(input, ["workflowRunId"]);
     const id2 = requireString3(input.workflowRunId, "workflowRunId");
@@ -16479,6 +16785,21 @@ var CoreNodeCreativeLoop = class {
     this.definitions.set(id2, definition);
     return definition;
   }
+  async resolveReferenceDataType(referenceViewNodeId) {
+    const referenceViewNode = this.requireViewNode(referenceViewNodeId);
+    if (referenceViewNode.type !== "resource") {
+      throw new Error("Generation References require a resource View Node.");
+    }
+    let sourceDataType = referenceViewNode.contentType ?? "";
+    const referenceCoreNodeId = this.resolveViewNodeCoreNodeId(referenceViewNode);
+    if (sourceDataType !== "text" || asRecord3(referenceViewNode.data).mode === "content") {
+      if (!referenceCoreNodeId)
+        throw new Error("Referenced View Node has no current Core Node.");
+      const coreNode = await this.requireCoreNode(referenceCoreNodeId);
+      sourceDataType = readCoreNodeDataType2(coreNode);
+    }
+    return sourceDataType;
+  }
   requireTarget(id2) {
     const viewNode = this.requireViewNode(id2);
     requireSupportedContentType(viewNode.contentType);
@@ -16524,8 +16845,6 @@ var CoreNodeCreativeLoop = class {
       data: {
         ...contentType === "text" ? { mode: "content" } : {},
         ...data,
-        creator_id: this.context.actor.id,
-        creator_name: this.context.actor.displayName,
         ...name ? { label: name } : {}
       },
       draft: null,
@@ -16563,6 +16882,14 @@ function createEstimatedCompletionTimes(estimate, submittedAt) {
 function attention(viewNodeId, result3) {
   return { attention: { kind: "view-nodes", viewNodeIds: [viewNodeId] }, result: result3 };
 }
+function reconciliationResult(viewNodeId, workflowRunId, reconciliationStatus, detail) {
+  return attention(viewNodeId, {
+    ...detail,
+    reconciliationStatus,
+    viewNodeId,
+    workflowRunId
+  });
+}
 function requireDraft(viewNode) {
   const draft = readGenerationDraft(viewNode.draft);
   if (!draft)
@@ -16588,6 +16915,38 @@ function readPrompt(draft) {
   }
   return null;
 }
+function inferReconciledMaterializedInputs(draft, run) {
+  const materialized = {};
+  for (const [slotName, bindings] of Object.entries(draft.inputs.slots)) {
+    const references = bindings.filter((binding) => binding.kind !== "literal");
+    if (references.length === 0)
+      continue;
+    const input = run.inputs[slotName];
+    if (typeof input !== "object" || input === null || Array.isArray(input) || !("coreNodeIds" in input) || !Array.isArray(input.coreNodeIds)) {
+      continue;
+    }
+    const coreNodeIds = input.coreNodeIds.filter((coreNodeId) => typeof coreNodeId === "string" && Boolean(coreNodeId));
+    if (references.length === 1) {
+      const reference = references[0];
+      if (reference)
+        materialized[slotName] = [{ coreNodeIds, inputRefId: reference.id }];
+      continue;
+    }
+    if (references.length !== coreNodeIds.length)
+      continue;
+    materialized[slotName] = references.map((reference, index) => ({
+      coreNodeIds: [coreNodeIds[index]],
+      inputRefId: reference.id
+    }));
+  }
+  return materialized;
+}
+function parseWorkflowTimestamp(value) {
+  if (!value)
+    return null;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : null;
+}
 function parseConfig2(value) {
   const record2 = asRecord3(value);
   for (const item of Object.values(record2)) {
@@ -16616,11 +16975,51 @@ function asRecord3(value) {
   }
   return value;
 }
+function normalizeOptionalRecord(value, field) {
+  if (value === void 0 || value === null)
+    return {};
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${field} must be an object when present.`);
+  }
+  return structuredClone(value);
+}
 function requireString3(value, field) {
   if (typeof value !== "string" || !value.trim())
     throw new Error(`${field} must be non-empty.`);
   return value.trim();
 }
+function parsePromptReferencePlacement(value) {
+  if (value === void 0 || value === "end")
+    return "end";
+  if (value === "start")
+    return "start";
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("placement must be start, end, or an anchor placement object.");
+  }
+  const placement = value;
+  assertOnlyKeys3(placement, ["anchor", "kind"]);
+  if (placement.kind !== "before" && placement.kind !== "after") {
+    throw new Error("placement.kind must be before or after.");
+  }
+  if (typeof placement.anchor !== "object" || placement.anchor === null || Array.isArray(placement.anchor)) {
+    throw new Error("placement.anchor must be an object.");
+  }
+  const anchor = placement.anchor;
+  assertOnlyKeys3(anchor, ["occurrence", "text"]);
+  const text = requirePlainString2(anchor.text, "placement.anchor.text");
+  if (!text.trim())
+    throw new Error("placement.anchor.text must be non-empty.");
+  if (anchor.occurrence !== void 0 && (!Number.isInteger(anchor.occurrence) || anchor.occurrence < 1)) {
+    throw new Error("placement.anchor.occurrence must be a positive integer.");
+  }
+  return {
+    anchor: {
+      ...anchor.occurrence === void 0 ? {} : { occurrence: anchor.occurrence },
+      text
+    },
+    kind: placement.kind
+  };
+}
 function requirePlainString2(value, field) {
   if (typeof value !== "string")
     throw new Error(`${field} must be a string.`);
@@ -16775,8 +17174,6 @@ var ExternalMediaImporter = class {
         data: {
           contentBindingError: null,
           contentBindingStatus: "pending",
-          creator_id: this.context.actor.id,
-          creator_name: this.context.actor.displayName,
           [IMPORT_INTENT_DATA_KEY]: structuredClone(intent),
           label: intent.name
         },
@@ -17086,9 +17483,12 @@ var MediaUploader = class {
     this.systems = systems;
     this.projection = systems.projectContentProjection;
   }
-  async execute(input, timeoutMs) {
+  async execute(input, timeoutMs, onProgress) {
     const request = normalizeUploadRequest(input);
-    const prepared = await this.systems.mediaUpload.prepare(request.source);
+    const safeProgress = safeProgressListener(onProgress);
+    const prepared = await this.systems.mediaUpload.prepare(request.source, {
+      onProgress: safeProgress
+    });
     try {
       const descriptor2 = requireValidDescriptor(prepared.descriptor);
       const intent = await createIntent(request, descriptor2);
@@ -17122,9 +17522,10 @@ var MediaUploader = class {
       let uploaded = false;
       let coreNodeId;
       try {
-        const object2 = await prepared.upload({ timeoutMs });
+        const object2 = await prepared.upload({ onProgress: safeProgress, timeoutMs });
         uploaded = true;
         const fileUrl = requireUploadedMediaUrl(object2.url);
+        await safeProgress({ operation: "uploadMedia", stage: "creating-content" });
         const completion = await this.systems.projectContent.completeMediaUploads(this.context.projectId, [
           {
             asset: {
@@ -17158,6 +17559,7 @@ var MediaUploader = class {
         await this.updateBindingStatus(viewNode, "failed", errorMessage2(error51), timeoutMs);
         throw error51;
       }
+      await safeProgress({ operation: "uploadMedia", stage: "updating-canvas" });
       await this.updateBindingStatus(viewNode, "ready", null, timeoutMs);
       return result2(viewNode.id, coreNodeId, intent, true, uploaded);
     } finally {
@@ -17201,8 +17603,6 @@ var MediaUploader = class {
         data: {
           contentBindingError: null,
           contentBindingStatus: "pending",
-          creator_id: this.context.actor.id,
-          creator_name: this.context.actor.displayName,
           label: intent.name,
           [UPLOAD_INTENT_DATA_KEY]: structuredClone(intent)
         },
@@ -17263,6 +17663,14 @@ var MediaUploader = class {
     return after;
   }
 };
+function safeProgressListener(listener) {
+  return async (progress) => {
+    try {
+      await listener?.(progress);
+    } catch {
+    }
+  };
+}
 var MediaUploadIndeterminateError = class extends Error {
   indeterminate = true;
   timedOut = false;
@@ -17991,6 +18399,7 @@ var SemanticCanvasRuntime = class {
   unsubscribeRemote;
   commands;
   contentProjection;
+  creationProvenanceSuffix;
   creativeLoop;
   externalMediaImporter;
   mediaUploader;
@@ -18000,12 +18409,12 @@ var SemanticCanvasRuntime = class {
   constructor(options) {
     this.options = options;
     this.now = options.now ?? Date.now;
+    this.creationProvenanceSuffix = normalizeCreationProvenanceSuffix(options.clientName);
     this.commands = createProjectCanvasCommandExecutor(options.document, this.now);
     this.contentProjection = new ProjectContentProjection(options.projectContents);
     this.projectionRevision = options.initialRevision ?? 1;
     this.snapshot = options.document.getSnapshot();
     const operationContext = {
-      actor: options.actor,
       canWrite: options.role !== "viewer",
       clientInstanceId: options.clientInstanceId ?? "unknown",
       commit: async (input) => {
@@ -18031,6 +18440,8 @@ var SemanticCanvasRuntime = class {
     this.unsubscribeRemote = options.document.subscribeRemoteChange(() => {
       const previous = this.snapshot;
       this.snapshot = options.document.getSnapshot();
+      const previousPending = new Set(previous.pendingWorkflowInstanceIds);
+      const addedPendingWorkflowInstanceIds = this.snapshot.pendingWorkflowInstanceIds.filter((id2) => !previousPending.has(id2));
       const viewNodeChanges = diffSemanticViewNodes(previous.viewNodes, this.snapshot.viewNodes);
       this.projectionRevision += 1;
       this.emit({
@@ -18042,6 +18453,9 @@ var SemanticCanvasRuntime = class {
         revision: this.projectionRevision
       });
       this.scheduleProjectContentRefresh();
+      if (addedPendingWorkflowInstanceIds.length > 0) {
+        this.creativeLoop?.observePendingWorkflowRuns(addedPendingWorkflowInstanceIds, 15e3);
+      }
     });
   }
   get revision() {
@@ -18124,7 +18538,7 @@ var SemanticCanvasRuntime = class {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
   }
-  async execute(name, input, timeoutMs) {
+  async execute(name, input, timeoutMs, options = {}) {
     this.requireCapability(name);
     if (name === "importExternalMedia") {
       if (!this.externalMediaImporter)
@@ -18135,7 +18549,7 @@ var SemanticCanvasRuntime = class {
     if (name === "uploadMedia") {
       if (!this.mediaUploader)
         throw new Error("Media upload system is unavailable.");
-      const result3 = await this.mediaUploader.execute(input, timeoutMs);
+      const result3 = await this.mediaUploader.execute(input, timeoutMs, options.onProgress);
       return { ...result3, revision: this.projectionRevision };
     }
     if (isCreativeLoopOperation(name)) {
@@ -18342,15 +18756,18 @@ var SemanticCanvasRuntime = class {
     };
   }
   async commit(entry, timeoutMs) {
-    await this.applyHistoryState(entry.after, entry.viewNodeIds, entry.label, timeoutMs);
-    this.undoStack.push({ ...entry, kind: "reversible" });
+    const after = this.stampCreatedViewNodes(entry.after, entry.before);
+    await this.applyHistoryState(after, entry.viewNodeIds, entry.label, timeoutMs);
+    this.undoStack.push({ ...entry, after, kind: "reversible" });
     this.redoStack.length = 0;
   }
   async applyOperationPlan(plan, timeoutMs) {
     if (plan.changes.length > 0) {
+      const before = plan.changes.map((change) => change.before);
+      const after = this.stampCreatedViewNodes(plan.changes.map((change) => change.after), before);
       const entry = {
-        after: plan.changes.map((change) => change.after),
-        before: plan.changes.map((change) => change.before),
+        after,
+        before,
         kind: "reversible",
         label: plan.label,
         viewNodeIds: plan.changes.map((change) => change.viewNodeId)
@@ -18387,16 +18804,23 @@ var SemanticCanvasRuntime = class {
     });
   }
   async applySemanticChanges(changes, label, timeoutMs, history, addPendingWorkflowInstanceIds, removePendingWorkflowInstanceIds) {
+    const preparedChanges = changes.map((change) => ({
+      ...change,
+      after: change.before === null ? this.stampCreatedViewNode(change.after) : structuredClone(change.after)
+    }));
     const previous = this.snapshot;
     this.snapshot = await this.commands.changeViewNodes({
       ...addPendingWorkflowInstanceIds ? { addPendingWorkflowInstanceIds } : {},
-      changes: changes.map((change) => ({ state: change.after, viewNodeId: change.viewNodeId })),
+      changes: preparedChanges.map((change) => ({
+        state: change.after,
+        viewNodeId: change.viewNodeId
+      })),
       operationName: label,
       ...removePendingWorkflowInstanceIds ? { removePendingWorkflowInstanceIds } : {},
       timeoutMs
     });
     this.projectionRevision += 1;
-    const viewNodeIds = changes.map((change) => change.viewNodeId);
+    const viewNodeIds = preparedChanges.map((change) => change.viewNodeId);
     const viewNodeChanges = diffSemanticViewNodes(previous.viewNodes, this.snapshot.viewNodes, viewNodeIds);
     this.emit({
       changedViewNodeIds: viewNodeIds,
@@ -18406,8 +18830,8 @@ var SemanticCanvasRuntime = class {
     });
     if (history === "undoable") {
       this.undoStack.push({
-        after: changes.map((change) => change.after),
-        before: changes.map((change) => change.before),
+        after: preparedChanges.map((change) => change.after),
+        before: preparedChanges.map((change) => change.before),
         kind: "reversible",
         label,
         viewNodeIds
@@ -18418,6 +18842,22 @@ var SemanticCanvasRuntime = class {
       this.redoStack.length = 0;
     }
   }
+  stampCreatedViewNodes(after, before) {
+    return after.map((viewNode, index) => viewNode !== null && before[index] === null ? this.stampCreatedViewNode(viewNode) : structuredClone(viewNode));
+  }
+  stampCreatedViewNode(viewNode) {
+    if (!this.creationProvenanceSuffix)
+      return structuredClone(viewNode);
+    const data = typeof viewNode.data === "object" && viewNode.data !== null && !Array.isArray(viewNode.data) ? structuredClone(viewNode.data) : {};
+    delete data.creator_id;
+    delete data.creator_name;
+    data.createdByCli = this.creationProvenanceSuffix;
+    if (viewNode.type === "note") {
+      data.creator_id = this.options.actor.id;
+      data.creator_name = `${this.options.actor.displayName} (${this.creationProvenanceSuffix})`;
+    }
+    return { ...structuredClone(viewNode), data };
+  }
   nextNotePosition() {
     const count = this.snapshot.viewNodes.length;
     return { x: 160 + count % 4 * 348, y: 160 + Math.floor(count / 4) * 348 };
@@ -18472,7 +18912,7 @@ function duplicateInputContainsResource(snapshot, input) {
   return snapshot.viewNodes.some((viewNode) => ids.has(viewNode.id) && viewNode.type === "resource");
 }
 function isCreativeLoopOperation(name) {
-  return name === "getCoreNode" || name === "placeCoreNode" || name === "createGenerationTarget" || name === "createMediaTarget" || name === "planGeneration" || name === "editGenerationDraft" || name === "addVisualReference" || name === "removeVisualReference" || name === "startGeneration" || name === "getWorkflowRun" || name === "waitWorkflowRun";
+  return name === "getCoreNode" || name === "placeCoreNode" || name === "createGenerationTarget" || name === "createMediaTarget" || name === "planGeneration" || name === "editGenerationDraft" || name === "addVisualReference" || name === "insertPromptReference" || name === "removeVisualReference" || name === "startGeneration" || name === "reconcileGenerationStart" || name === "getWorkflowRun" || name === "waitWorkflowRun";
 }
 function createViewNodeId() {
   return `view_node_${crypto.randomUUID().replaceAll("-", "")}`;
@@ -18510,6 +18950,17 @@ function requireString6(value, field) {
     throw new Error(`${field} must be a string.`);
   return value;
 }
+function normalizeCreationProvenanceSuffix(value) {
+  if (value === void 0)
+    return null;
+  const normalized = value.trim();
+  if (!normalized)
+    throw new Error("clientName must be non-empty when provided.");
+  if (normalized.includes("(") || normalized.includes(")")) {
+    throw new Error("clientName must not contain parentheses.");
+  }
+  return normalized;
+}
 
 // src/integrations/backend.ts
 var BackendRequestError = class extends Error {
@@ -23176,10 +23627,12 @@ var HASH_BUFFER_BYTES = 256 * 1024;
 function createNodeCanvasMediaUploadSystem(config2, cwd = process.cwd()) {
   const backend = new Az8BackendClient(config2);
   return {
-    async prepare(sourceReference) {
+    async prepare(sourceReference, options) {
+      const report = createProgressReporter(options?.onProgress);
+      await report({ bytesCompleted: 0, operation: "uploadMedia", stage: "inspecting" });
       const source = await openUploadSource(sourceReference, cwd);
       try {
-        const descriptor2 = await inspectUploadSource(source.handle, source.absolutePath);
+        const descriptor2 = await inspectUploadSource(source.handle, source.absolutePath, report);
         return createPreparedUpload(config2, backend, source.handle, source.absolutePath, descriptor2);
       } catch (error51) {
         await source.handle.close().catch(() => void 0);
@@ -23213,7 +23666,7 @@ async function openUploadSource(sourceReference, cwd) {
   }
   return { absolutePath, handle };
 }
-async function inspectUploadSource(handle, absolutePath) {
+async function inspectUploadSource(handle, absolutePath, report) {
   const before = await handle.stat();
   if (!Number.isSafeInteger(before.size) || before.size < 1) {
     throw new Error("Media upload source must contain at least one byte.");
@@ -23232,6 +23685,7 @@ async function inspectUploadSource(handle, absolutePath) {
       chunk2.copy(header, bytes, 0, Math.min(chunk2.byteLength, header.byteLength - bytes));
     }
     bytes += bytesRead;
+    await report(uploadProgress("inspecting", bytes, before.size));
   }
   const after = await handle.stat();
   if (after.size !== before.size || after.mtimeMs !== before.mtimeMs) {
@@ -23268,6 +23722,10 @@ function createPreparedUpload(config2, backend, handle, absolutePath, descriptor
       if (closed) throw new Error("Prepared media upload is already closed.");
       if (attempted) throw new Error("Prepared media upload can only be attempted once.");
       attempted = true;
+      await reportProgress(options?.onProgress, {
+        operation: "uploadMedia",
+        stage: "requesting-upload"
+      });
       const presign = await backend.request("core_nodes/upload/presign", {
         json: { format: descriptor2.extension, type: descriptor2.mediaType },
         method: "POST",
@@ -23276,12 +23734,20 @@ function createPreparedUpload(config2, backend, handle, absolutePath, descriptor
       });
       const uploadUrl = requireHttpUrl(presign.upload_url, "upload");
       const fileUrl = requireHttpUrl(presign.file_url, "file");
-      await putPreparedFile(config2, handle, absolutePath, descriptor2, uploadUrl, options?.timeoutMs);
+      await putPreparedFile(
+        config2,
+        handle,
+        absolutePath,
+        descriptor2,
+        uploadUrl,
+        options?.timeoutMs,
+        createProgressReporter(options?.onProgress)
+      );
       return { url: fileUrl };
     }
   };
 }
-async function putPreparedFile(config2, handle, absolutePath, descriptor2, uploadUrl, timeoutMs) {
+async function putPreparedFile(config2, handle, absolutePath, descriptor2, uploadUrl, timeoutMs, report) {
   const originalStat = await handle.stat();
   const uploadHandle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
   let uploadStat;
@@ -23302,11 +23768,15 @@ async function putPreparedFile(config2, handle, absolutePath, descriptor2, uploa
   );
   const hash2 = createHash("sha256");
   let bytes = 0;
+  await report(uploadProgress("uploading", 0, descriptor2.bytes));
   const meter = new Transform({
     transform(chunk2, _encoding, callback) {
       hash2.update(chunk2);
       bytes += chunk2.byteLength;
-      callback(null, chunk2);
+      Promise.resolve(report(uploadProgress("uploading", bytes, descriptor2.bytes))).then(
+        () => callback(null, chunk2),
+        callback
+      );
     }
   });
   const source = uploadHandle.createReadStream({
@@ -23342,6 +23812,35 @@ async function putPreparedFile(config2, handle, absolutePath, descriptor2, uploa
     throw new Error("Media upload source changed before the upload completed.");
   }
 }
+function createProgressReporter(listener) {
+  let lastStage = "";
+  let lastReportedAt = 0;
+  return async (progress) => {
+    if (!listener) return;
+    const now = Date.now();
+    const complete = progress.bytesTotal !== void 0 && progress.bytesCompleted === progress.bytesTotal;
+    const stageChanged = progress.stage !== lastStage;
+    if (!stageChanged && !complete && now - lastReportedAt < 500) return;
+    lastStage = progress.stage;
+    lastReportedAt = now;
+    await reportProgress(listener, progress);
+  };
+}
+async function reportProgress(listener, progress) {
+  try {
+    await listener?.(progress);
+  } catch {
+  }
+}
+function uploadProgress(stage, bytesCompleted, bytesTotal) {
+  return {
+    bytesCompleted,
+    bytesTotal,
+    operation: "uploadMedia",
+    percent: Math.min(100, Math.round(bytesCompleted / bytesTotal * 1e3) / 10),
+    stage
+  };
+}
 function requireHttpUrl(value, kind) {
   if (typeof value !== "string" || !value.trim()) {
     throw new Error(`Media upload presign returned no ${kind} URL.`);
@@ -23410,8 +23909,19 @@ var COLLABORATION_SESSION_STATES = [
 ];
 
 // src/canvas/watch/interest-registry.ts
+var SYSTEM_WORKFLOW_TERMINAL_INTEREST_KEY = "system.workflow-terminal";
 var CollaborationInterestRegistry = class {
   interests = /* @__PURE__ */ new Map();
+  constructor(includeSystemWorkflowTerminal = false) {
+    if (includeSystemWorkflowTerminal) {
+      this.interests.set(SYSTEM_WORKFLOW_TERMINAL_INTEREST_KEY, {
+        filter: { terminalOnly: true },
+        key: SYSTEM_WORKFLOW_TERMINAL_INTEREST_KEY,
+        kind: "workflow",
+        system: true
+      });
+    }
+  }
   patch(input) {
     const upserts = input.upsert ?? [];
     const removals = input.remove ?? [];
@@ -23421,6 +23931,9 @@ var CollaborationInterestRegistry = class {
     for (const entry of upserts) {
       const key = requireKey(entry.key);
       const current = next.get(key);
+      if (current?.system) {
+        throw interestError("system-interest-readonly", `System Interest ${key} cannot be changed.`);
+      }
       if (entry.patch.kind !== void 0 && !isInterestKind(entry.patch.kind)) {
         throw interestError(
           "interest-kind-invalid",
@@ -23441,6 +23954,9 @@ var CollaborationInterestRegistry = class {
     }
     for (const rawKey of removals) {
       const key = requireKey(rawKey);
+      if (next.get(key)?.system) {
+        throw interestError("system-interest-readonly", `System Interest ${key} cannot be removed.`);
+      }
       if (next.delete(key)) changedKeys.push(key);
     }
     this.interests.clear();
@@ -23646,6 +24162,7 @@ function projectWorkflowRun(run, observedAt) {
     status: run.status,
     summary: {
       definitionId: run.definitionId,
+      workflowRunId: run.id,
       ...run.error ? {
         error: {
           ...run.error.code ? { code: run.error.code } : {},
@@ -23655,6 +24172,7 @@ function projectWorkflowRun(run, observedAt) {
       ...run.progress === void 0 ? {} : { progress: run.progress },
       ...run.outputs.length > 0 ? {
         outputs: run.outputs.map((output) => ({
+          coreNodeId: output.coreNodeId,
           role: output.role,
           slotName: output.slotName,
           ...output.viewNodeId ? { viewNodeId: output.viewNodeId } : {}
@@ -23709,16 +24227,18 @@ function safeWorkflowMessage(value) {
 
 // src/canvas/watch/watch.ts
 var AgentCollaborationWatch = class {
-  interests = new CollaborationInterestRegistry();
+  interests;
   maxChangesPerDelivery;
   maxPendingChanges;
   maxRecentResults;
   now;
   pending = [];
   recent = [];
+  workflowWatermarks = /* @__PURE__ */ new Map();
   activeWait = null;
   continuityLost = false;
   constructor(options = {}) {
+    this.interests = new CollaborationInterestRegistry(options.includeSystemWorkflowTerminal);
     this.maxChangesPerDelivery = positive(
       options.maxChangesPerDelivery ?? 64,
       "maxChangesPerDelivery"
@@ -23728,7 +24248,13 @@ var AgentCollaborationWatch = class {
     this.now = options.now ?? Date.now;
   }
   patchInterests(input) {
-    return this.interests.patch(input);
+    const result3 = this.interests.patch(input);
+    for (const key of result3.changedKeys) {
+      for (const watermarkKey of this.workflowWatermarks.keys()) {
+        if (watermarkKey.startsWith(`${key}\0`)) this.workflowWatermarks.delete(watermarkKey);
+      }
+    }
+    return result3;
   }
   getInterests() {
     return this.interests.getAll();
@@ -23752,10 +24278,24 @@ var AgentCollaborationWatch = class {
   recordMany(facts) {
     if (this.continuityLost) return;
     for (const fact of facts) {
-      for (const interest of this.interests.matching(fact)) this.enqueue(interest.key, fact);
+      for (const interest of this.interests.matching(fact)) {
+        this.recordWorkflowWatermark(interest.key, fact);
+        this.enqueue(interest.key, fact);
+      }
     }
     if (this.activeWait && (this.pending.length > 0 || this.continuityLost)) this.deliverActive();
   }
+  recordAuthoritativeWorkflow(fact) {
+    if (fact.domain !== "workflow" || this.continuityLost) return;
+    for (const interest of this.interests.matching(fact)) {
+      const key = workflowWatermarkKey(interest.key, fact.ref);
+      const fingerprint = workflowFingerprint(fact);
+      if (this.workflowWatermarks.get(key) === fingerprint) continue;
+      this.workflowWatermarks.set(key, fingerprint);
+      this.enqueue(interest.key, fact);
+    }
+    if (this.activeWait && this.pending.length > 0) this.deliverActive();
+  }
   wait(options) {
     const timeoutMs = positive(options.timeoutMs, "timeoutMs");
     if (this.activeWait)
@@ -23789,6 +24329,11 @@ var AgentCollaborationWatch = class {
   resynchronize() {
     this.continuityLost = false;
     this.pending.length = 0;
+    this.workflowWatermarks.clear();
+  }
+  recordWorkflowWatermark(interest, fact) {
+    if (fact.domain !== "workflow") return;
+    this.workflowWatermarks.set(workflowWatermarkKey(interest, fact.ref), workflowFingerprint(fact));
   }
   enqueue(interest, fact) {
     const terminalPending = this.pending.find(
@@ -23832,6 +24377,7 @@ var AgentCollaborationWatch = class {
       merged: entry.merged,
       quietForMs: Math.max(0, now - entry.lastObservedAt),
       ref: entry.fact.ref,
+      ...entry.fact.domain === "canvas" ? { source: entry.fact.source } : {},
       summary: structuredClone(entry.fact.summary)
     }));
     const result3 = {
@@ -23908,6 +24454,18 @@ function positive(value, field) {
 function watchError(code, message) {
   return Object.assign(new Error(message), { code });
 }
+function workflowWatermarkKey(interest, runId) {
+  return `${interest}\0${runId}`;
+}
+function workflowFingerprint(fact) {
+  return JSON.stringify({
+    changeKind: fact.changeKind,
+    kind: fact.kind,
+    status: fact.status,
+    summary: fact.summary,
+    terminal: fact.terminal
+  });
+}
 
 // src/canvas/session.ts
 var CanvasSession = class {
@@ -23916,7 +24474,7 @@ var CanvasSession = class {
     this.projectId = projectId;
     this.dependencies = dependencies;
     this.clientInstanceId = clientInstanceId;
-    this.watch = dependencies.watch ?? new AgentCollaborationWatch();
+    this.watch = dependencies.watch ?? new AgentCollaborationWatch({ includeSystemWorkflowTerminal: true });
     this.health = {
       connectionAttempts: 0,
       connectionId: null,
@@ -23934,6 +24492,7 @@ var CanvasSession = class {
   runtime = null;
   unsubscribeRuntime = null;
   observationListeners = /* @__PURE__ */ new Set();
+  knownWorkflowRunIds = /* @__PURE__ */ new Set();
   projectionRevision = 0;
   actorId = null;
   collaborationContext = null;
@@ -23983,6 +24542,7 @@ var CanvasSession = class {
       const connectionId = this.health.connectionId;
       const runtime = new SemanticCanvasRuntime({
         actor: { displayName: actor.displayName, id: actor.accountId },
+        clientName: normalizedClientName,
         clientInstanceId: this.clientInstanceId,
         document: document2,
         foundationData,
@@ -24001,9 +24561,15 @@ var CanvasSession = class {
         workflowRuntime
       });
       this.runtime = runtime;
+      for (const workflowRunId of runtime.getSnapshot().pendingWorkflowInstanceIds) {
+        this.knownWorkflowRunIds.add(workflowRunId);
+      }
       this.projectionRevision = runtime.revision;
       this.unsubscribeRuntime = runtime.subscribe((observation) => {
         this.projectionRevision = observation.revision;
+        if (observation.workflowRun) {
+          this.knownWorkflowRunIds.add(observation.workflowRun.id);
+        }
         this.watch.recordMany(projectCanvasObservation(observation, Date.now()));
         const legacyObservation = {
           ...observation.changedViewNodeIds ? { changedViewNodeIds: observation.changedViewNodeIds } : {},
@@ -24022,13 +24588,60 @@ var CanvasSession = class {
       throw error51;
     }
   }
-  async execute(name, input, timeoutMs) {
+  async execute(name, input, timeoutMs, options = {}) {
     const runtime = this.requireRuntime();
-    const result3 = await runtime.execute(name, input, timeoutMs);
+    if (typeof input.workflowRunId === "string" && input.workflowRunId) {
+      this.knownWorkflowRunIds.add(input.workflowRunId);
+    }
+    const result3 = await runtime.execute(name, input, timeoutMs, options);
+    if (typeof result3.result.workflowRunId === "string" && result3.result.workflowRunId) {
+      this.knownWorkflowRunIds.add(result3.result.workflowRunId);
+    }
     this.projectionRevision = result3.revision;
     if (result3.attention) this.publishAttention(result3.attention);
     return result3;
   }
+  async catchUpWorkflowInterests(timeoutMs) {
+    const runtime = this.requireRuntime();
+    const deadline = Date.now() + timeoutMs;
+    const knownWorkflowRunIds = [...this.knownWorkflowRunIds];
+    const runIds = [
+      ...new Set(
+        this.watch.getInterests().filter((interest) => interest.kind === "workflow").flatMap((interest) => interest.filter.runIds ?? knownWorkflowRunIds)
+      )
+    ];
+    for (const workflowRunId of runIds) {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs < 1) break;
+      try {
+        const result3 = await runtime.execute("getWorkflowRun", { workflowRunId }, remainingMs);
+        const workflowRun = result3.result.workflowRun;
+        if (!isWorkflowRun(workflowRun)) continue;
+        for (const fact of projectCanvasObservation(
+          { kind: "workflow", revision: result3.revision, workflowRun },
+          Date.now()
+        )) {
+          this.watch.recordAuthoritativeWorkflow(fact);
+        }
+      } catch {
+      }
+    }
+  }
+  acknowledgeWatchDelivery(result3) {
+    if (result3.status !== "ready") return;
+    for (const change of result3.changes) {
+      if (change.source !== "remote" || !change.kind.startsWith("note.") && !change.kind.startsWith("view-node.")) {
+        continue;
+      }
+      const bounds = this.requireRuntime().resolveAttentionBounds({
+        kind: "view-nodes",
+        viewNodeIds: [change.ref]
+      });
+      if (!bounds) continue;
+      this.publishAttentionBounds(bounds);
+      return;
+    }
+  }
   getCapabilities(detail) {
     return this.requireRuntime().capabilities.map(
       (descriptor2) => detail ? descriptor2 : {
@@ -24142,6 +24755,9 @@ function isIndeterminateWrite4(value) {
 function isWorkflowRecoveryExhausted(value) {
   return typeof value === "object" && value !== null && "workflowRecoveryExhausted" in value && value.workflowRecoveryExhausted === true;
 }
+function isWorkflowRun(value) {
+  return typeof value === "object" && value !== null && "id" in value && typeof value.id === "string" && "status" in value && typeof value.status === "string" && "definitionId" in value && typeof value.definitionId === "string" && "outputs" in value && Array.isArray(value.outputs);
+}
 
 // src/canvas/client.ts
 var CANVAS_QUERY_TARGETS = [
@@ -24226,7 +24842,9 @@ var CanvasClient = class {
     };
     this.receipts.push(receipt);
     try {
-      const operation = await this.session.execute(name, input.input, input.timeoutMs ?? 15e3);
+      const operation = await this.session.execute(name, input.input, input.timeoutMs ?? 15e3, {
+        onProgress: input.onProgress
+      });
       Object.assign(receipt, {
         completedAt: (/* @__PURE__ */ new Date()).toISOString(),
         projectionRevisionAfter: operation.revision,
@@ -24236,6 +24854,7 @@ var CanvasClient = class {
       });
       return { receipt };
     } catch (error51) {
+      const operationResult2 = readCanvasOperationIndeterminateResult(error51);
       const operationUsage = readCanvasOperationUsage(error51);
       const indeterminate = isIndeterminateError(error51);
       const timedOut = indeterminate && (error51 instanceof IndeterminateBackendWriteError && error51.timedOut || readTimedOut(error51) || error51 instanceof Error && /timed out/i.test(error51.message));
@@ -24247,6 +24866,7 @@ var CanvasClient = class {
           message: safeCanvasMessage(error51),
           outcome: indeterminate ? "indeterminate" : "failed"
         },
+        ...operationResult2 ? { result: redactCanvasRecord(operationResult2) } : {},
         status: timedOut ? "timed-out" : "failed",
         ...operationUsage ? { usage: operationUsage } : {}
       });
@@ -24397,7 +25017,7 @@ import { chmod, unlink } from "node:fs/promises";
 import net from "node:net";
 var MAX_RPC_REQUEST_BYTES = 1024 * 1024;
 var MAX_RPC_RESPONSE_BYTES = 16 * 1024 * 1024;
-async function requestAgentSession(socketPath, request, timeoutMs = 5e3, signal) {
+async function requestAgentSession(socketPath, request, timeoutMs = 5e3, signal, onProgress) {
   return new Promise((resolve, reject) => {
     const socket = net.createConnection(socketPath);
     let source = "";
@@ -24427,14 +25047,23 @@ async function requestAgentSession(socketPath, request, timeoutMs = 5e3, signal)
         finish(rpcError("session-rpc-too-large", "Agent Session RPC response is too large."));
         return;
       }
-      const newline = source.indexOf("\n");
-      if (newline < 0) return;
-      try {
-        const response = JSON.parse(source.slice(0, newline));
-        if (!response.ok) finish(rpcError(response.error.code, response.error.message));
-        else finish(void 0, response.value);
-      } catch {
-        finish(rpcError("invalid-session-rpc", "Agent Session RPC response is invalid."));
+      while (!settled) {
+        const newline = source.indexOf("\n");
+        if (newline < 0) return;
+        const line = source.slice(0, newline);
+        source = source.slice(newline + 1);
+        try {
+          const message = JSON.parse(line);
+          if ("type" in message && message.type === "progress") {
+            void Promise.resolve(onProgress?.(message.progress)).catch(() => void 0);
+            continue;
+          }
+          const response = message;
+          if (!response.ok) finish(rpcError(response.error.code, response.error.message));
+          else finish(void 0, response.value);
+        } catch {
+          finish(rpcError("invalid-session-rpc", "Agent Session RPC response is invalid."));
+        }
       }
     });
     socket.once("error", (error51) => finish(error51));
@@ -24473,7 +25102,10 @@ async function listenAgentSessionRpc(socketPath, handler) {
       handled = true;
       try {
         const request = JSON.parse(source.slice(0, newline));
-        const value = await handler(request, { signal: abortController2.signal });
+        const value = await handler(request, {
+          reportProgress: (progress) => writeProgress(socket, progress),
+          signal: abortController2.signal
+        });
         writeResponse(socket, { ok: true, value });
       } catch (error51) {
         writeResponse(
@@ -24505,6 +25137,13 @@ async function listenAgentSessionRpc(socketPath, handler) {
     }
   };
 }
+function writeProgress(socket, progress) {
+  if (socket.destroyed || !socket.writable) return Promise.resolve();
+  return new Promise((resolve) => {
+    socket.write(`${JSON.stringify({ progress, type: "progress" })}
+`, () => resolve());
+  });
+}
 function writeResponse(socket, response) {
   if (socket.destroyed) return;
   socket.end(`${JSON.stringify(response)}
@@ -24856,7 +25495,16 @@ async function startAgentSessionDaemon(spec, dependencies = {}) {
       }
       if (request.kind === "delivery.ack") {
         const acknowledged = outstandingDelivery?.deliveryId === request.deliveryId;
-        if (acknowledged) outstandingDelivery = void 0;
+        if (acknowledged) {
+          const result3 = outstandingDelivery?.result;
+          outstandingDelivery = void 0;
+          if (result3) {
+            try {
+              client.session.acknowledgeWatchDelivery?.(result3);
+            } catch {
+            }
+          }
+        }
         return { acknowledged };
       }
       if (request.kind === "interests.get") return watch.getInterests();
@@ -24882,7 +25530,10 @@ async function startAgentSessionDaemon(spec, dependencies = {}) {
       }
       if (request.kind === "watch.wait") {
         if (outstandingDelivery) return outstandingDelivery;
-        const result3 = await watch.wait({ signal: context.signal, timeoutMs: request.timeoutMs });
+        const startedAt = Date.now();
+        await client.session.catchUpWorkflowInterests?.(Math.min(request.timeoutMs, 15e3));
+        const remainingMs = Math.max(1, request.timeoutMs - (Date.now() - startedAt));
+        const result3 = await watch.wait({ signal: context.signal, timeoutMs: remainingMs });
         if (result3.status !== "ready") return { result: result3 };
         outstandingDelivery = { deliveryId: crypto.randomUUID(), result: result3 };
         return outstandingDelivery;
@@ -24897,6 +25548,7 @@ async function startAgentSessionDaemon(spec, dependencies = {}) {
           return await client.executeOperation({
             input: request.input,
             name: request.name,
+            onProgress: context.reportProgress,
             requestId: request.requestId,
             ...request.timeoutMs ? { timeoutMs: request.timeoutMs } : {}
           });
@@ -24905,6 +25557,7 @@ async function startAgentSessionDaemon(spec, dependencies = {}) {
           () => client.executeOperation({
             input: request.input,
             name: request.name,
+            onProgress: context.reportProgress,
             requestId: request.requestId,
             ...request.timeoutMs ? { timeoutMs: request.timeoutMs } : {}
           })
@@ -24949,6 +25602,8 @@ async function createCanvasClient(spec, dependencies) {
     executeOperation: (input) => client.executeOperation(input),
     query: (input) => client.query(input),
     session: {
+      acknowledgeWatchDelivery: (result3) => session.acknowledgeWatchDelivery(result3),
+      catchUpWorkflowInterests: (timeoutMs) => session.catchUpWorkflowInterests(timeoutMs),
       getContext: () => session.getCollaborationContext(),
       getHealth: () => session.getHealth(),
       getIdentity: () => session.getIdentity(),
@@ -25351,6 +26006,11 @@ var CanvasProtocolServer = class {
     const outcome = await this.client.executeOperation({
       input: request.payload.input,
       name: request.payload.name,
+      onProgress: (progress) => this.output.emitMandatory({
+        payload: progress,
+        requestId: request.requestId,
+        type: "operationProgress"
+      }),
       requestId: request.requestId,
       ...request.payload.timeoutMs ? { timeoutMs: request.payload.timeoutMs } : {}
     });
@@ -28990,6 +29650,9 @@ async function runCanvasOneShot(config2, command, dependencies = {}) {
       input: command.input,
       name: command.name,
       requestId: command.requestId,
+      ...dependencies.onProgress ? {
+        onProgress: (progress) => dependencies.onProgress?.({ ...progress, requestId: command.requestId })
+      } : {},
       ...command.timeoutMs ? { timeoutMs: command.timeoutMs } : {}
     });
     return operationResult(command, outcome);
@@ -29175,18 +29838,21 @@ function resolveDownloadableCoreNodeMedia(coreNode) {
 
 // src/media/download.ts
 var DEFAULT_RESOLUTION_TIMEOUT_MS = 15e3;
+var DEFAULT_DOWNLOAD_ATTEMPTS = 3;
 var FILE_TYPE_HEADER_BYTES2 = 64 * 1024;
 var MediaDownloadError = class extends Error {
-  constructor(code, message, exitCode, retryable) {
+  constructor(code, message, exitCode, retryable, details = {}) {
     super(message);
     this.code = code;
     this.exitCode = exitCode;
     this.retryable = retryable;
+    this.details = details;
     this.name = "MediaDownloadError";
   }
   code;
   exitCode;
   retryable;
+  details;
 };
 async function runCanvasMediaDownload(config2, command, dependencies = {}) {
   const requestedAbsolutePath = path6.resolve(dependencies.cwd ?? process.cwd(), command.outputPath);
@@ -29201,42 +29867,80 @@ async function runCanvasMediaDownload(config2, command, dependencies = {}) {
   } catch (error51) {
     return failureResult2(command, error51, requestedAbsolutePath);
   }
-  let client;
-  let media;
-  try {
-    client = dependencies.mediaDownloadClientFactory?.(config2, command.projectId) ?? new CanvasClient(config2, command.projectId);
-    try {
-      await client.connect(normalizeCanvasClientName(command.clientName));
-    } catch {
-      throw new MediaDownloadError(
-        "canvas-connection-failed",
-        "Unable to establish a ready Project Canvas context.",
-        2,
-        true
-      );
-    }
-    throwIfCancelled(dependencies.signal);
-    media = await resolveMediaSource(client, command, dependencies.randomUUID);
-  } catch (error51) {
-    return failureResult2(command, error51, outputTarget.absolutePath);
-  } finally {
-    client?.close();
+  const maximumAttempts = dependencies.maxAttempts ?? DEFAULT_DOWNLOAD_ATTEMPTS;
+  if (!Number.isInteger(maximumAttempts) || maximumAttempts < 1 || maximumAttempts > 3) {
+    return failureResult2(
+      command,
+      new MediaDownloadError(
+        "invalid-download-attempts",
+        "Download attempt limit must be between 1 and 3.",
+        1,
+        false,
+        { phase: "setup" }
+      ),
+      outputTarget.absolutePath,
+      0,
+      0
+    );
   }
-  try {
-    const file2 = await transferMedia(config2, media, outputTarget, command, dependencies);
-    return {
-      exitCode: 0,
-      output: {
-        file: file2,
-        format: "az8.canvas.media-download.v1",
-        media: { coreNodeId: media.coreNodeId, mediaType: media.mediaType },
-        projectId: command.projectId,
-        source: command.source
+  const deadlineAt = command.timeoutMs ? Date.now() + command.timeoutMs : null;
+  let lastError;
+  for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
+    try {
+      throwIfCancelled(dependencies.signal);
+      const remainingMs = remainingDownloadMs(deadlineAt);
+      const attemptCommand = {
+        ...command,
+        ...remainingMs === void 0 ? {} : { timeoutMs: remainingMs }
+      };
+      const media = await resolveMediaForAttempt(config2, attemptCommand, dependencies);
+      const file2 = await transferMedia(config2, media, outputTarget, attemptCommand, dependencies);
+      return {
+        exitCode: 0,
+        output: {
+          attempts: { completed: attempt, maximum: maximumAttempts },
+          file: file2,
+          format: "az8.canvas.media-download.v1",
+          media: { coreNodeId: media.coreNodeId, mediaType: media.mediaType },
+          projectId: command.projectId,
+          source: command.source
+        }
+      };
+    } catch (error51) {
+      lastError = error51;
+      const failure = normalizeDownloadError(error51);
+      if (!failure.retryable || failure.code === "download-cancelled" || failure.code === "download-timed-out" || attempt === maximumAttempts) {
+        return failureResult2(command, failure, outputTarget.absolutePath, attempt, maximumAttempts);
       }
-    };
-  } catch (error51) {
-    return failureResult2(command, error51, outputTarget.absolutePath);
+      try {
+        await waitForDownloadRetry(
+          downloadRetryDelay(attempt, dependencies.random?.() ?? Math.random()),
+          deadlineAt,
+          dependencies
+        );
+      } catch (retryError) {
+        return failureResult2(
+          command,
+          retryError,
+          outputTarget.absolutePath,
+          attempt,
+          maximumAttempts
+        );
+      }
+    }
   }
+  return failureResult2(
+    command,
+    lastError,
+    outputTarget.absolutePath,
+    maximumAttempts,
+    maximumAttempts
+  );
+}
+function downloadRetryDelay(attempt, random) {
+  const boundedRandom = Number.isFinite(random) ? Math.max(0, Math.min(1, random)) : 0.5;
+  const base = Math.min(250 * 2 ** (attempt - 1), 1e3);
+  return Math.min(1e3, Math.round(base * (0.75 + boundedRandom * 0.5)));
 }
 function formatCanvasMediaDownloadResult(result3) {
   return `${JSON.stringify(result3.output, null, 2)}
@@ -29252,7 +29956,8 @@ async function resolveMediaSource(client, command, randomUUID4) {
         "view-node-media-unavailable",
         safeCanvasMessage(error51),
         1,
-        false
+        false,
+        { cause: sanitizeDownloadCause(error51), phase: "source-resolution" }
       );
     }
   } else {
@@ -29270,7 +29975,8 @@ async function resolveMediaSource(client, command, randomUUID4) {
       "core-node-resolution-failed",
       outcome.receipt.error?.message ?? `Core Node ${coreNodeId} could not be resolved.`,
       indeterminate ? 2 : 1,
-      indeterminate
+      indeterminate,
+      { phase: "core-node-resolution" }
     );
   }
   const coreNode = parseCoreNode(outcome.receipt.result?.coreNode, coreNodeId);
@@ -29289,7 +29995,8 @@ function parseCoreNode(value, expectedId) {
       "core-node-response-invalid",
       `Core Node ${expectedId} returned an invalid record.`,
       2,
-      true
+      true,
+      { phase: "core-node-resolution" }
     );
   }
   const record2 = value;
@@ -29298,7 +30005,8 @@ function parseCoreNode(value, expectedId) {
       "core-node-response-invalid",
       `Core Node ${expectedId} returned an invalid record.`,
       2,
-      true
+      true,
+      { phase: "core-node-resolution" }
     );
   }
   return value;
@@ -29309,7 +30017,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "invalid-output-path",
       "Download output path must not be blank.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   const absolutePath = path6.resolve(cwd, requestedPath);
@@ -29322,7 +30031,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "output-parent-unavailable",
       "Download output parent directory does not exist or cannot be accessed.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   if (!parent.isDirectory()) {
@@ -29330,7 +30040,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "output-parent-not-directory",
       "Download output parent is not a directory.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   let existing;
@@ -29342,7 +30053,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
         "output-target-unavailable",
         "Download output target cannot be inspected.",
         1,
-        false
+        false,
+        { phase: "output-setup" }
       );
     }
   }
@@ -29351,7 +30063,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "output-target-exists",
       "Download output target already exists; pass --overwrite to replace a regular file.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   if (existing && (!existing.isFile() || existing.isSymbolicLink())) {
@@ -29359,7 +30072,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "output-target-not-regular-file",
       "Download output target must be a regular file and must not be a symbolic link.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   return { absolutePath, existed: Boolean(existing), parentPath };
@@ -29370,9 +30084,9 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
   let response;
   try {
     response = await config2.fetch(media.url, { redirect: "follow", signal: deadline.signal });
-  } catch {
+  } catch (error51) {
     deadline.cleanup();
-    throw transferFailure(deadline);
+    throw transferFailure(deadline, error51);
   }
   if (!response.ok) {
     deadline.cleanup();
@@ -29381,7 +30095,8 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
       "media-http-error",
       `Media server returned HTTP ${response.status}.`,
       retryable ? 2 : 1,
-      retryable
+      retryable,
+      { phase: "media-transfer" }
     );
   }
   const contentType = normalizeContentType(response.headers.get("content-type"));
@@ -29391,8 +30106,9 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
     throw new MediaDownloadError(
       "media-content-type-mismatch",
       `Media response is ${headerFamily}, but Core Node ${media.coreNodeId} is ${media.mediaType}.`,
-      2,
-      true
+      1,
+      false,
+      { phase: "media-verification" }
     );
   }
   if (contentType === "text/html" || contentType === "application/json") {
@@ -29400,8 +30116,9 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
     throw new MediaDownloadError(
       "media-content-type-mismatch",
       "Media response returned a non-media document.",
-      2,
-      true
+      1,
+      false,
+      { phase: "media-verification" }
     );
   }
   const remoteContentLength = readContentLength(response);
@@ -29434,7 +30151,8 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
         "output-finalize-failed",
         "Temporary download file could not be finalized.",
         1,
-        false
+        false,
+        { phase: "output-finalize" }
       );
     }
     let detected;
@@ -29445,7 +30163,8 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
         "media-verification-failed",
         "Downloaded media could not be inspected safely.",
         1,
-        false
+        false,
+        { phase: "media-verification" }
       );
     }
     validateDownloadedMedia(media, contentType, detected);
@@ -29467,12 +30186,13 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
   } catch (error51) {
     await temporary.handle.close().catch(() => void 0);
     if (error51 instanceof MediaDownloadError) throw error51;
-    if (deadline.signal.aborted) throw transferFailure(deadline);
+    if (deadline.signal.aborted) throw transferFailure(deadline, error51);
     throw new MediaDownloadError(
       "media-download-internal-failed",
       "Media download could not complete its local processing.",
       2,
-      true
+      true,
+      { cause: sanitizeDownloadCause(error51), phase: "media-transfer" }
     );
   } finally {
     deadline.cleanup();
@@ -29523,7 +30243,8 @@ async function streamResponseToFile(response, handle, deadline, expectedBytes) {
       "media-response-body-missing",
       "Media response has no readable body.",
       2,
-      true
+      true,
+      { phase: "media-transfer" }
     );
   }
   const reader = response.body.getReader();
@@ -29541,16 +30262,17 @@ async function streamResponseToFile(response, handle, deadline, expectedBytes) {
     }
   } catch (error51) {
     if (error51 instanceof MediaDownloadError) throw error51;
-    if (deadline.signal.aborted) throw transferFailure(deadline);
+    if (deadline.signal.aborted) throw transferFailure(deadline, error51);
     if (readFsCode2(error51)) {
       throw new MediaDownloadError(
         "output-write-failed",
         "Temporary download file could not be written completely.",
         1,
-        false
+        false,
+        { cause: sanitizeDownloadCause(error51), phase: "output-write" }
       );
     }
-    throw transferFailure(deadline);
+    throw transferFailure(deadline, error51);
   } finally {
     reader.releaseLock();
   }
@@ -29559,7 +30281,8 @@ async function streamResponseToFile(response, handle, deadline, expectedBytes) {
       "media-content-length-mismatch",
       `Media response declared ${expectedBytes} bytes but delivered ${bytes}.`,
       2,
-      true
+      true,
+      { phase: "media-transfer" }
     );
   }
   return { bytes, sha256: hash2.digest("hex") };
@@ -29573,7 +30296,8 @@ async function writeAll(handle, value) {
         "output-write-stalled",
         "Temporary download file stopped accepting data.",
         1,
-        false
+        false,
+        { phase: "output-write" }
       );
     }
     offset += bytesWritten;
@@ -29585,8 +30309,9 @@ function validateDownloadedMedia(media, contentType, detected) {
     throw new MediaDownloadError(
       "media-content-mismatch",
       `Downloaded file is ${detectedFamily}, but Core Node ${media.coreNodeId} is ${media.mediaType}.`,
-      2,
-      true
+      1,
+      false,
+      { phase: "media-verification" }
     );
   }
   const headerMatches = readMediaFamily(contentType) === media.mediaType;
@@ -29595,8 +30320,9 @@ function validateDownloadedMedia(media, contentType, detected) {
     throw new MediaDownloadError(
       "media-content-unverified",
       `Downloaded file could not be verified as ${media.mediaType} media.`,
-      2,
-      true
+      1,
+      false,
+      { phase: "media-verification" }
     );
   }
 }
@@ -29614,14 +30340,16 @@ async function commitTemporaryFile(temporaryPath, outputTarget, overwrite) {
         "output-target-exists",
         "Download output target was created before the download could be committed.",
         1,
-        false
+        false,
+        { phase: "output-commit" }
       );
     }
     throw new MediaDownloadError(
       "output-commit-failed",
       "Verified media could not be committed to the output path.",
       1,
-      false
+      false,
+      { cause: sanitizeDownloadCause(error51), phase: "output-commit" }
     );
   }
 }
@@ -29645,18 +30373,29 @@ function createTransferSignal(external, timeoutMs) {
     signal: controller.signal
   };
 }
-function transferFailure(deadline) {
+function transferFailure(deadline, cause) {
   if (deadline.external?.aborted) {
-    return new MediaDownloadError("download-cancelled", "Media download was cancelled.", 130, true);
+    return new MediaDownloadError(
+      "download-cancelled",
+      "Media download was cancelled.",
+      130,
+      true,
+      {
+        phase: "media-transfer"
+      }
+    );
   }
   if (deadline.isTimedOut()) {
-    return new MediaDownloadError("download-timed-out", "Media download timed out.", 2, true);
+    return new MediaDownloadError("download-timed-out", "Media download timed out.", 2, true, {
+      phase: "media-transfer"
+    });
   }
   return new MediaDownloadError(
     "media-network-failed",
     "Media response could not be downloaded completely.",
     2,
-    true
+    true,
+    { cause: sanitizeDownloadCause(cause), phase: "media-transfer" }
   );
 }
 function throwIfCancelled(signal) {
@@ -29685,23 +30424,111 @@ function readMediaFamily(value) {
   if (value?.startsWith("video/")) return "video";
   return null;
 }
-function failureResult2(command, error51, absolutePath) {
-  const failure = error51 instanceof MediaDownloadError ? error51 : new MediaDownloadError("media-download-failed", safeCanvasMessage(error51), 2, true);
+function failureResult2(command, error51, absolutePath, attemptsCompleted = 1, maximumAttempts = 1) {
+  const failure = normalizeDownloadError(error51);
   return {
     exitCode: failure.exitCode,
     output: {
       error: {
         code: failure.code,
         message: safeCanvasMessage(failure),
-        retryable: failure.retryable
+        ...failure.details.phase ? { phase: failure.details.phase } : {},
+        retryable: failure.retryable,
+        ...failure.details.cause ? { cause: failure.details.cause } : {}
       },
       format: "az8.canvas.media-download.v1",
+      localState: {
+        destinationCommitted: false,
+        partialFileRetained: false
+      },
       outputPath: absolutePath ?? path6.resolve(command.outputPath),
       projectId: command.projectId,
+      attempts: { completed: attemptsCompleted, maximum: maximumAttempts },
+      remoteState: "unverified",
       source: command.source
     }
   };
 }
+async function resolveMediaForAttempt(config2, command, dependencies) {
+  const client = dependencies.mediaDownloadClientFactory?.(config2, command.projectId) ?? new CanvasClient(config2, command.projectId);
+  try {
+    try {
+      await client.connect(normalizeCanvasClientName(command.clientName));
+    } catch (error51) {
+      throw new MediaDownloadError(
+        "canvas-connection-failed",
+        "Unable to establish a ready Project Canvas context.",
+        2,
+        true,
+        { cause: sanitizeDownloadCause(error51), phase: "canvas-connect" }
+      );
+    }
+    throwIfCancelled(dependencies.signal);
+    return await resolveMediaSource(client, command, dependencies.randomUUID);
+  } finally {
+    client.close();
+  }
+}
+function normalizeDownloadError(error51) {
+  return error51 instanceof MediaDownloadError ? error51 : new MediaDownloadError("media-download-failed", safeCanvasMessage(error51), 2, true, {
+    cause: sanitizeDownloadCause(error51),
+    phase: "unknown"
+  });
+}
+function remainingDownloadMs(deadlineAt) {
+  if (deadlineAt === null) return void 0;
+  const remaining = deadlineAt - Date.now();
+  if (remaining < 1) {
+    throw new MediaDownloadError("download-timed-out", "Media download timed out.", 2, true, {
+      phase: "retry-wait"
+    });
+  }
+  return remaining;
+}
+async function waitForDownloadRetry(delayMs, deadlineAt, dependencies) {
+  const remaining = remainingDownloadMs(deadlineAt);
+  if (remaining !== void 0 && remaining <= delayMs) {
+    throw new MediaDownloadError("download-timed-out", "Media download timed out.", 2, true, {
+      phase: "retry-wait"
+    });
+  }
+  await (dependencies.sleep ?? abortableSleep)(delayMs, dependencies.signal);
+  throwIfCancelled(dependencies.signal);
+}
+async function abortableSleep(delayMs, signal) {
+  if (signal?.aborted) return;
+  await new Promise((resolve) => {
+    const timeout = setTimeout(done, delayMs);
+    const onAbort = () => done();
+    function done() {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function sanitizeDownloadCause(error51) {
+  if (!error51 || typeof error51 !== "object") return void 0;
+  const record2 = error51;
+  const cause = record2.cause && typeof record2.cause === "object" ? record2.cause : record2;
+  const message = cause instanceof Error ? cause.message : typeof cause.message === "string" ? cause.message : error51 instanceof Error ? error51.message : void 0;
+  const code = typeof cause.code === "string" || typeof cause.code === "number" ? String(cause.code) : void 0;
+  const closeCode = typeof cause.closeCode === "number" ? cause.closeCode : typeof cause.websocketCloseCode === "number" ? cause.websocketCloseCode : void 0;
+  const closeReason = typeof cause.closeReason === "string" ? cause.closeReason : typeof cause.websocketCloseReason === "string" ? cause.websocketCloseReason : void 0;
+  const sanitizedMessage = message ? sanitizeTransportDetail(message) : void 0;
+  const sanitizedReason = closeReason ? sanitizeTransportDetail(closeReason) : void 0;
+  if (!code && !closeCode && !sanitizedMessage && !sanitizedReason) return void 0;
+  return {
+    ...code ? { code } : {},
+    ...sanitizedMessage ? { message: sanitizedMessage } : {},
+    ...closeCode ? { websocketCloseCode: closeCode } : {},
+    ...sanitizedReason ? { websocketCloseReason: sanitizedReason } : {}
+  };
+}
+function sanitizeTransportDetail(value) {
+  return value.replace(/token=[^\s;&]+/gi, "token=[REDACTED]").replace(/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, "[REDACTED]").replace(/(?:https?|wss?):\/\/[^\s]+/gi, "[REDACTED_URL]");
+}
 function readFsCode2(error51) {
   return typeof error51 === "object" && error51 !== null && "code" in error51 ? String(error51.code) : void 0;
 }
@@ -44620,7 +45447,7 @@ function registerCanvasCommands(program2, dependencies, setResult) {
 // package.json
 var package_default = {
   name: "@everfir/az8-cli",
-  version: "0.3.0-preview.1",
+  version: "0.3.0-preview.3",
   description: "Semantic Project Canvas client for AZ8 Studio agents.",
   license: "UNLICENSED",
   type: "module",
@@ -44983,7 +45810,8 @@ var AgentSessionManager = class {
       descriptor2.socketPath,
       request,
       options.timeoutMs ?? 5e3,
-      options.signal
+      options.signal,
+      options.onProgress
     ).catch((error51) => {
       if (isRemoteFailure(error51)) throw error51;
       throw managerError(
@@ -45351,7 +46179,11 @@ function registerSessionCommands(program2, dependencies, setResult) {
           requestId,
           ...options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}
         },
-        { sessionId: options.session, timeoutMs: (options.timeoutMs ?? 15e3) + 5e3 }
+        {
+          onProgress: (progress) => dependencies.onProgress?.({ ...progress, requestId }),
+          sessionId: options.session,
+          timeoutMs: (options.timeoutMs ?? 15e3) + 5e3
+        }
       );
       const receipt = readOperationReceipt(value);
       const exitCode = receipt.status === "succeeded" ? 0 : receipt.error?.outcome === "indeterminate" ? 2 : 1;
@@ -45555,6 +46387,12 @@ process.once("SIGINT", abortOnSignal);
 process.once("SIGTERM", abortOnSignal);
 try {
   const result3 = await runAz8Cli(process.argv.slice(2), {
+    onProgress(progress) {
+      process.stderr.write(
+        `${JSON.stringify({ format: "az8.operation-progress.v1", ...progress })}
+`
+      );
+    },
     persistentCanvas: runPersistentCanvas,
     signal: abortController.signal
   });