@everfir/az8-cli 0.3.0-preview.2 → 0.3.0

package/dist/main.js

@@ -2387,7 +2387,7 @@ var require_websocket = __commonJS({
     var http = __require("http");
     var net2 = __require("net");
     var tls = __require("tls");
-    var { randomBytes, createHash: createHash4 } = __require("crypto");
+    var { randomBytes, createHash: createHash5 } = __require("crypto");
     var { Duplex, Readable } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
@@ -3047,7 +3047,7 @@ var require_websocket = __commonJS({
           abortHandshake(websocket, socket, "Invalid Upgrade header");
           return;
         }
-        const digest = createHash4("sha1").update(key + GUID).digest("base64");
+        const digest = createHash5("sha1").update(key + GUID).digest("base64");
         if (res.headers["sec-websocket-accept"] !== digest) {
           abortHandshake(websocket, socket, "Invalid Sec-WebSocket-Accept header");
           return;
@@ -3414,7 +3414,7 @@ var require_websocket_server = __commonJS({
     var EventEmitter3 = __require("events");
     var http = __require("http");
     var { Duplex } = __require("stream");
-    var { createHash: createHash4 } = __require("crypto");
+    var { createHash: createHash5 } = __require("crypto");
     var extension2 = require_extension();
     var PerMessageDeflate2 = require_permessage_deflate();
     var subprotocol2 = require_subprotocol();
@@ -3715,7 +3715,7 @@ var require_websocket_server = __commonJS({
           );
         }
         if (this._state > RUNNING) return abortHandshake(socket, 503);
-        const digest = createHash4("sha1").update(key + GUID).digest("base64");
+        const digest = createHash5("sha1").update(key + GUID).digest("base64");
         const headers = [
           "HTTP/1.1 101 Switching Protocols",
           "Upgrade: websocket",
@@ -4822,6 +4822,58 @@ function normalize(value) {
   return (value ?? "").trim().toLowerCase().replaceAll(/[\s_]+/g, "-");
 }
 
+// ../../packages/project-canvas-runtime/dist/generation/workflow-access.js
+function resolveWorkflowDefinitionAccess(definition, accessTier) {
+  if (accessTier === "paid") {
+    return { accessReason: "paid-account", availableForAccount: true };
+  }
+  if (normalize2(getInternalTag(definition, "available")) === "free") {
+    return { accessReason: "free-tier-eligible", availableForAccount: true };
+  }
+  return { accessReason: "requires-paid-account", availableForAccount: false };
+}
+function isWorkflowDefinitionAvailable(definition, accessTier) {
+  return resolveWorkflowDefinitionAccess(definition, accessTier).availableForAccount;
+}
+function normalize2(value) {
+  return (value ?? "").trim().toLowerCase().replaceAll(/[\s_]+/g, "-");
+}
+
+// ../../packages/project-canvas-runtime/dist/generation/workflow-default.js
+function selectDefaultWorkflowDefinition(input) {
+  const compatible = input.definitions.filter((definition) => isDefaultCompatible(definition, input.contentType));
+  const preferred = input.preference && compatible.find((definition) => definition.id === input.preference?.definitionId);
+  if (preferred) {
+    return { definition: preferred, preference: input.preference, source: "preference" };
+  }
+  const fallback = compatible[0] ?? null;
+  return {
+    definition: fallback,
+    preference: null,
+    source: fallback ? "fallback" : "none"
+  };
+}
+function isDefaultCompatible(definition, contentType) {
+  const metadata = resolveWorkflowDefinitionMetadata(definition);
+  if (metadata.target !== contentType)
+    return false;
+  if (!definition.outputSchema.some((output) => output.dataType === contentType))
+    return false;
+  if (getInternalTag(definition, "function") && !getInternalTag(definition, "capability")) {
+    return false;
+  }
+  return definition.inputSchema.some((slot) => !isConfigSlot(slot));
+}
+
+// ../../packages/project-canvas-runtime/dist/generation/workflow-target.js
+function resolveWorkflowTargetFromSnapshot(snapshot, workflowRunId) {
+  const targetIds = new Set(snapshot.viewNodes.flatMap((viewNode) => readGenerationHistory(viewNode.history).some((entry) => entry.runtime.instanceIds.includes(workflowRunId)) ? [viewNode.id] : []));
+  if (targetIds.size === 1) {
+    return { status: "resolved", viewNodeId: [...targetIds][0] };
+  }
+  return { status: targetIds.size > 1 ? "ambiguous" : "unresolved" };
+}
+
 // ../../node_modules/.pnpm/lib0@0.2.117/node_modules/lib0/math.js
 var floor = Math.floor;
 var abs = Math.abs;
@@ -8238,10 +8290,10 @@ var YEvent = class {
   }
 };
 var getPathTo = (parent, child) => {
-  const path9 = [];
+  const path10 = [];
   while (child._item !== null && child !== parent) {
     if (child._item.parentSub !== null) {
-      path9.unshift(child._item.parentSub);
+      path10.unshift(child._item.parentSub);
     } else {
       let i = 0;
       let c = (
@@ -8254,12 +8306,12 @@ var getPathTo = (parent, child) => {
         }
         c = c.right;
       }
-      path9.unshift(i);
+      path10.unshift(i);
     }
     child = /** @type {AbstractType<any>} */
     child._item.parent;
   }
-  return path9;
+  return path10;
 };
 var warnPrematureAccess = () => {
   warn("Invalid access: Add Yjs type to a document before reading data.");
@@ -14095,7 +14147,7 @@ var CANVAS_OPERATION_REGISTRY = [
     },
     required: ["contentType"]
   }),
-  write2("createGenerationTarget", "Create a blank audio, image, text, or video target", "undoable", {
+  write2("createGenerationTarget", "Create an audio, image, text, or video target with an eligible default Draft when available", "undoable", {
     properties: {
       contentType: { enum: ["audio", "image", "text", "video"], type: "string" },
       name: stringSchema(),
@@ -14159,7 +14211,7 @@ var CANVAS_OPERATION_REGISTRY = [
     },
     required: ["idempotencyKey", "source"]
   }),
-  write2("editGenerationDraft", "Edit semantic prompt, config, or Workflow Definition", "silent", {
+  write2("editGenerationDraft", "Edit prompt, config, or Workflow Definition, resolving an eligible default for a null Draft", "silent", {
     properties: {
       config: { additionalProperties: { type: ["boolean", "number", "string"] }, type: "object" },
       definitionId: stringSchema(),
@@ -14177,7 +14229,28 @@ var CANVAS_OPERATION_REGISTRY = [
   }),
   write2("insertPromptReference", "Bind one visible image, text, or video View Node and place its platform At token in the Prompt", "silent", {
     properties: {
-      placement: { enum: ["start", "end"], type: "string" },
+      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()
     },
@@ -14997,7 +15070,156 @@ function isConfigValueValid(value, property, normalizedEnum = normalizeConfigEnu
   return true;
 }
 
+// ../../packages/project-canvas-runtime/dist/generation/planning-contract.js
+function generationPlanningIssue(code, message, slotName, field) {
+  return {
+    code,
+    message,
+    severity: "error",
+    ...slotName ? { slotName } : {},
+    ...field ? { field } : {}
+  };
+}
+
+// ../../packages/project-canvas-runtime/dist/generation/planning-config.js
+function createGenerationConfigDefaults(definition, preferred) {
+  const slots = generationConfigSlots(definition);
+  if (slots.length === 0)
+    return null;
+  if (slots.length !== 1)
+    return null;
+  const slot = slots[0];
+  const properties = slot.jsonSchema?.properties ?? {};
+  const slotDefaults = readConfigDefaults(slot.defaultValue);
+  return Object.fromEntries(Object.entries(properties).map(([name, property]) => {
+    const preferredValue = preferred?.[name];
+    if (preferredValue !== void 0 && isConfigValueValid(preferredValue, property)) {
+      return [name, preferredValue];
+    }
+    const slotDefault = normalizeSchemaConfigValue(slotDefaults[name], property.type);
+    return [
+      name,
+      slotDefault !== void 0 && isConfigValueValid(slotDefault, property) ? slotDefault : configFallback(property, normalizeConfigEnum(property))
+    ];
+  }));
+}
+async function createGenerationConfigPlan(definition, requested, runtime) {
+  const slots = generationConfigSlots(definition);
+  if (slots.length === 0) {
+    return {
+      fields: [],
+      issues: requested ? [generationPlanningIssue("config-not-supported", "This Workflow Definition does not accept configuration.")] : [],
+      values: null
+    };
+  }
+  if (slots.length !== 1) {
+    return {
+      fields: [],
+      issues: [
+        generationPlanningIssue("multiple-config-slots-unsupported", "Generation Planning currently requires exactly one configuration slot.")
+      ],
+      values: null
+    };
+  }
+  const slot = slots[0];
+  const properties = slot.jsonSchema?.properties ?? {};
+  const slotDefaults = readConfigDefaults(slot.defaultValue);
+  const values = {};
+  const issues = [];
+  for (const name of Object.keys(requested ?? {})) {
+    if (!properties[name]) {
+      issues.push(generationPlanningIssue("config-field-unknown", `Unknown configuration field: ${name}.`, slot.name, name));
+    }
+  }
+  const fields = await Promise.all(Object.entries(properties).map(async ([name, property]) => {
+    const normalizedEnum = normalizeConfigEnum(property);
+    if (normalizedEnum?.invalidValues.length) {
+      issues.push(generationPlanningIssue("config-enum-invalid", `Configuration ${name} contains enum values that do not match ${property.type}.`, slot.name, name));
+    }
+    const requestedValue = Object.hasOwn(requested ?? {}, name) ? requested?.[name] : normalizeSchemaConfigValue(slotDefaults[name], property.type);
+    const fallback = configFallback(property, normalizedEnum);
+    if (requestedValue !== void 0 && !isConfigValueValid(requestedValue, property)) {
+      issues.push(generationPlanningIssue("config-value-invalid", `Configuration ${name} is outside its allowed values.`, slot.name, name));
+    }
+    const value = requestedValue !== void 0 && isConfigValueValid(requestedValue, property) ? requestedValue : fallback;
+    values[name] = value;
+    const dynamicOptions = await readDynamicOptions(runtime, name, property, value, issues, slot.name);
+    return {
+      description: property.description ?? "",
+      name,
+      required: slot.jsonSchema?.required?.includes(name) ?? false,
+      type: property.type,
+      value,
+      ...property.maximum === void 0 ? {} : { maximum: property.maximum },
+      ...property.minimum === void 0 ? {} : { minimum: property.minimum },
+      ...dynamicOptions ?? normalizedEnum?.options ? { options: dynamicOptions ?? normalizedEnum?.options } : {}
+    };
+  }));
+  for (const name of slot.jsonSchema?.required ?? []) {
+    if (values[name] === "") {
+      issues.push(generationPlanningIssue("config-field-required", `Configuration ${name} requires a value.`, slot.name, name));
+    }
+  }
+  return { fields, issues, values };
+}
+function readConfigDefaults(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return {};
+  return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "boolean" || typeof entry[1] === "string" || typeof entry[1] === "number" && Number.isFinite(entry[1])));
+}
+async function readDynamicOptions(runtime, name, property, current, issues, slotName) {
+  const source = property.dynamicEnum;
+  if (property.type !== "string" || !source?.modelKey || !runtime.getDynamicEnumValues)
+    return null;
+  try {
+    const remote = await runtime.getDynamicEnumValues({
+      modelKey: source.modelKey,
+      paramName: name,
+      provider: source.provider
+    });
+    const values = typeof current === "string" && current.trim() ? [current] : [];
+    for (const item of remote)
+      if (!values.includes(item))
+        values.push(item);
+    return values;
+  } catch {
+    issues.push({
+      code: "dynamic-options-unavailable",
+      field: name,
+      message: `Dynamic options for configuration ${name} are temporarily unavailable.`,
+      severity: "warning",
+      slotName
+    });
+    return null;
+  }
+}
+function configFallback(property, normalizedEnum) {
+  const normalizedDefault = normalizeSchemaConfigValue(property.default, property.type);
+  if (normalizedDefault !== void 0 && isConfigValueValid(normalizedDefault, property)) {
+    return normalizedDefault;
+  }
+  const first = normalizedEnum?.options[0];
+  if (first !== void 0)
+    return first;
+  if (property.type === "boolean")
+    return false;
+  if (property.type === "number") {
+    return property.minimum ?? (property.maximum && property.maximum < 0 ? property.maximum : 0);
+  }
+  return "";
+}
+function generationConfigSlots(definition) {
+  return definition.inputSchema.filter((slot) => slot.dataType === "json" && (slot.required || isConfigSlot(slot)));
+}
+
 // ../../packages/project-canvas-runtime/dist/generation/draft-edit.js
+function createInitialGenerationDraft(definition, preferredConfig, now) {
+  const config2 = createGenerationConfigDefaults(definition, preferredConfig);
+  return editGenerationDraft(null, definition, {
+    definitionId: definition.id,
+    ...config2 ? { config: config2 } : {}
+  }, now);
+}
 function editGenerationDraft(current, definition, input, now) {
   const changedDefinition = current?.definitionId !== definition.id;
   const draft = !current || changedDefinition ? {
@@ -15068,7 +15290,7 @@ function insertPromptReferenceIntoDraft(draft, definition, reference, sourceData
   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 : prompt.trim() ? `${prompt}${prompt.endsWith("\n") ? "" : "\n"}${token}` : token;
+${prompt}` : token : placement === "end" ? prompt.trim() ? `${prompt}${prompt.endsWith("\n") ? "" : "\n"}${token}` : token : insertAtPromptAnchor(prompt, token, placement);
   return {
     ...structuredClone(withoutExistingToken),
     inputs: {
@@ -15129,23 +15351,72 @@ 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) {
+  const promptSlot = findPromptSlot(definition);
+  const config2 = createGenerationConfigDefaults(definition);
+  const configSlots = definition.inputSchema.filter((slot) => slot.dataType === "json");
+  const configSlot = configSlots.length === 1 ? configSlots[0] : void 0;
   return Object.fromEntries(definition.inputSchema.map((slot) => {
+    if (slot === promptSlot) {
+      return [slot.name, [literal({ id: definition.id }, slot.name, "text", "")]];
+    }
+    if (slot === configSlot && config2) {
+      return [
+        slot.name,
+        [literal({ id: definition.id }, slot.name, "json", JSON.stringify(config2))]
+      ];
+    }
     if (slot.defaultValue === void 0)
       return [slot.name, []];
     const content = slot.dataType === "json" ? JSON.stringify(slot.defaultValue) : String(slot.defaultValue);
@@ -15172,11 +15443,14 @@ function requireSingleSlot(definition, dataType, purpose) {
   return slots[0];
 }
 function requirePromptSlot(definition) {
-  const slot = definition.inputSchema.find((candidate) => candidate.name === "prompt" && candidate.dataType === "text") ?? definition.inputSchema.find((candidate) => candidate.required && candidate.dataType === "text") ?? definition.inputSchema.find((candidate) => candidate.dataType === "text");
+  const slot = findPromptSlot(definition);
   if (!slot)
     throw new Error("Workflow Definition must expose a prompt slot.");
   return slot;
 }
+function findPromptSlot(definition) {
+  return definition.inputSchema.find((candidate) => candidate.name === "prompt" && candidate.dataType === "text") ?? definition.inputSchema.find((candidate) => candidate.required && candidate.dataType === "text") ?? definition.inputSchema.find((candidate) => candidate.dataType === "text");
+}
 function validateConfig(slot, config2) {
   const schema = slot.jsonSchema;
   if (!schema)
@@ -15248,124 +15522,6 @@ function requirePrimaryOutput(definition, contentType) {
   return output;
 }
 
-// ../../packages/project-canvas-runtime/dist/generation/planning-contract.js
-function generationPlanningIssue(code, message, slotName, field) {
-  return {
-    code,
-    message,
-    severity: "error",
-    ...slotName ? { slotName } : {},
-    ...field ? { field } : {}
-  };
-}
-
-// ../../packages/project-canvas-runtime/dist/generation/planning-config.js
-async function createGenerationConfigPlan(definition, requested, runtime) {
-  const slots = definition.inputSchema.filter((slot2) => slot2.dataType === "json" && (slot2.required || isConfigSlot(slot2)));
-  if (slots.length === 0) {
-    return {
-      fields: [],
-      issues: requested ? [generationPlanningIssue("config-not-supported", "This Workflow Definition does not accept configuration.")] : [],
-      values: null
-    };
-  }
-  if (slots.length !== 1) {
-    return {
-      fields: [],
-      issues: [
-        generationPlanningIssue("multiple-config-slots-unsupported", "Generation Planning currently requires exactly one configuration slot.")
-      ],
-      values: null
-    };
-  }
-  const slot = slots[0];
-  const properties = slot.jsonSchema?.properties ?? {};
-  const slotDefaults = readConfigDefaults(slot.defaultValue);
-  const values = {};
-  const issues = [];
-  for (const name of Object.keys(requested ?? {})) {
-    if (!properties[name]) {
-      issues.push(generationPlanningIssue("config-field-unknown", `Unknown configuration field: ${name}.`, slot.name, name));
-    }
-  }
-  const fields = await Promise.all(Object.entries(properties).map(async ([name, property]) => {
-    const normalizedEnum = normalizeConfigEnum(property);
-    if (normalizedEnum?.invalidValues.length) {
-      issues.push(generationPlanningIssue("config-enum-invalid", `Configuration ${name} contains enum values that do not match ${property.type}.`, slot.name, name));
-    }
-    const requestedValue = Object.hasOwn(requested ?? {}, name) ? requested?.[name] : normalizeSchemaConfigValue(slotDefaults[name], property.type);
-    const fallback = configFallback(property, normalizedEnum);
-    if (requestedValue !== void 0 && !isConfigValueValid(requestedValue, property)) {
-      issues.push(generationPlanningIssue("config-value-invalid", `Configuration ${name} is outside its allowed values.`, slot.name, name));
-    }
-    const value = requestedValue !== void 0 && isConfigValueValid(requestedValue, property) ? requestedValue : fallback;
-    values[name] = value;
-    const dynamicOptions = await readDynamicOptions(runtime, name, property, value, issues, slot.name);
-    return {
-      description: property.description ?? "",
-      name,
-      required: slot.jsonSchema?.required?.includes(name) ?? false,
-      type: property.type,
-      value,
-      ...property.maximum === void 0 ? {} : { maximum: property.maximum },
-      ...property.minimum === void 0 ? {} : { minimum: property.minimum },
-      ...dynamicOptions ?? normalizedEnum?.options ? { options: dynamicOptions ?? normalizedEnum?.options } : {}
-    };
-  }));
-  for (const name of slot.jsonSchema?.required ?? []) {
-    if (values[name] === "") {
-      issues.push(generationPlanningIssue("config-field-required", `Configuration ${name} requires a value.`, slot.name, name));
-    }
-  }
-  return { fields, issues, values };
-}
-function readConfigDefaults(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value))
-    return {};
-  return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "boolean" || typeof entry[1] === "string" || typeof entry[1] === "number" && Number.isFinite(entry[1])));
-}
-async function readDynamicOptions(runtime, name, property, current, issues, slotName) {
-  const source = property.dynamicEnum;
-  if (property.type !== "string" || !source?.modelKey || !runtime.getDynamicEnumValues)
-    return null;
-  try {
-    const remote = await runtime.getDynamicEnumValues({
-      modelKey: source.modelKey,
-      paramName: name,
-      provider: source.provider
-    });
-    const values = typeof current === "string" && current.trim() ? [current] : [];
-    for (const item of remote)
-      if (!values.includes(item))
-        values.push(item);
-    return values;
-  } catch {
-    issues.push({
-      code: "dynamic-options-unavailable",
-      field: name,
-      message: `Dynamic options for configuration ${name} are temporarily unavailable.`,
-      severity: "warning",
-      slotName
-    });
-    return null;
-  }
-}
-function configFallback(property, normalizedEnum) {
-  const normalizedDefault = normalizeSchemaConfigValue(property.default, property.type);
-  if (normalizedDefault !== void 0 && isConfigValueValid(normalizedDefault, property)) {
-    return normalizedDefault;
-  }
-  const first = normalizedEnum?.options[0];
-  if (first !== void 0)
-    return first;
-  if (property.type === "boolean")
-    return false;
-  if (property.type === "number") {
-    return property.minimum ?? (property.maximum && property.maximum < 0 ? property.maximum : 0);
-  }
-  return "";
-}
-
 // ../../packages/project-canvas-runtime/dist/generation/planning-execution.js
 function createGenerationExecutionOperations(input) {
   const operations = [];
@@ -15374,10 +15530,10 @@ function createGenerationExecutionOperations(input) {
     definitionId: input.definition.id,
     viewNodeId: input.targetViewNodeId
   };
-  if (resolvePromptSlot(input.definition) && input.prompt !== readGenerationDraftPrompt(input.currentDraft)) {
+  if (resolvePromptSlot(input.definition) && (definitionChanges || input.prompt !== readGenerationDraftPrompt(input.currentDraft))) {
     editInput.prompt = input.prompt;
   }
-  if (!sameConfig(input.config, readGenerationDraftConfig(input.currentDraft)) && input.config) {
+  if (input.config && (definitionChanges || !sameConfig(input.config, readGenerationDraftConfig(input.currentDraft)))) {
     editInput.config = input.config;
   }
   if (definitionChanges || Object.keys(editInput).length > 2) {
@@ -16056,9 +16212,12 @@ var CoreNodeCreativeLoop = class {
     if (name === "createGenerationTarget")
       return this.createGenerationTarget(input, timeoutMs);
     if (name === "planGeneration") {
+      if (input.definitionId !== void 0) {
+        await this.requireSelectableDefinition(requireString3(input.definitionId, "definitionId"));
+      }
       return {
         result: await planGeneration(input, {
-          definitions: [...this.definitions.values()],
+          definitions: this.selectableDefinitions(),
           foundationData: this.systems.foundationData,
           getSnapshot: () => this.context.getSnapshot(),
           projectContentProjection: this.projection,
@@ -16086,15 +16245,23 @@ var CoreNodeCreativeLoop = class {
     throw new Error(`Operation ${name} is outside the Core Node creative loop.`);
   }
   getDefinitions(detail, definitionId) {
-    const definitions = [...this.definitions.values()].filter((definition) => !definitionId || definition.id === definitionId);
+    const definitions = [...this.definitions.values()].filter((definition) => {
+      if (definitionId)
+        return definition.id === definitionId;
+      return isWorkflowDefinitionAvailable(definition, this.systems.workflowAccessTier);
+    });
     return {
-      definitions: definitions.map((definition) => detail ? structuredClone(definition) : {
-        description: definition.description,
-        id: definition.id,
-        name: definition.name,
-        outputs: definition.outputSchema.map((output) => output.dataType),
-        tags: definition.tags,
-        version: definition.version
+      definitions: definitions.map((definition) => {
+        const access = resolveWorkflowDefinitionAccess(definition, this.systems.workflowAccessTier);
+        return detail ? { ...structuredClone(definition), ...access } : {
+          ...access,
+          description: definition.description,
+          id: definition.id,
+          name: definition.name,
+          outputs: definition.outputSchema.map((output) => output.dataType),
+          tags: definition.tags,
+          version: definition.version
+        };
       })
     };
   }
@@ -16105,6 +16272,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())
@@ -16203,10 +16382,14 @@ var CoreNodeCreativeLoop = class {
     assertOnlyKeys3(input, ["contentType", "name", "position"]);
     const contentType = requireString3(input.contentType, "contentType");
     requireSupportedContentType(contentType);
+    const targetContentType = contentType;
+    const selection = await this.resolveDefaultDefinition(targetContentType);
+    const draft = selection.definition ? createInitialGenerationDraft(selection.definition, selection.preference?.config, this.context.now()) : null;
     const viewNode = this.createResourceViewNode(contentType, input.position, optionalString2(input.name), {
       creationIntent: "blank",
       ...contentType === "text" ? { mode: "content" } : {}
     }, "generated");
+    viewNode.draft = draft ? toDocumentJson(draft) : null;
     await this.context.commit({
       after: [viewNode],
       before: [],
@@ -16214,24 +16397,39 @@ var CoreNodeCreativeLoop = class {
       label: "Create generation target",
       timeoutMs
     });
-    return attention(viewNode.id, { viewNodeId: viewNode.id });
+    if (draft)
+      await this.rememberWorkflowPreference(targetContentType, draft);
+    return attention(viewNode.id, {
+      ...draft ? { definitionId: draft.definitionId, draftId: draft.id } : {},
+      draftInitialized: Boolean(draft),
+      selectionSource: selection.source,
+      viewNodeId: viewNode.id
+    });
   }
   async editDraft(input, timeoutMs) {
     assertOnlyKeys3(input, ["config", "definitionId", "prompt", "viewNodeId"]);
     const current = this.requireTarget(requireString3(input.viewNodeId, "viewNodeId"));
     const existing = readGenerationDraft(current.draft);
-    const definitionId = optionalString2(input.definitionId) ?? existing?.definitionId;
-    if (!definitionId)
-      throw new Error("definitionId is required when creating a Draft.");
-    const definition = await this.requireDefinition(definitionId);
+    const contentType = current.contentType;
+    const explicitDefinitionId = optionalString2(input.definitionId);
+    const resolved = existing ? {
+      definition: await this.requireSelectableDefinition(explicitDefinitionId ?? existing.definitionId),
+      preference: null,
+      source: explicitDefinitionId ? "explicit" : "existing"
+    } : explicitDefinitionId ? await this.resolveExplicitDefinition(contentType, explicitDefinitionId) : await this.resolveDefaultDefinition(contentType);
+    const definition = resolved.definition;
+    if (!definition) {
+      throw Object.assign(new Error(`No compatible Workflow Definition is available for ${contentType}.`), { code: "no-compatible-workflow" });
+    }
     requirePrimaryOutput(definition, current.contentType);
     if (input.prompt === void 0 && input.config === void 0 && input.definitionId === void 0) {
       throw new Error("Draft edit requires definitionId, prompt, or config.");
     }
     const config2 = input.config === void 0 ? void 0 : parseConfig2(input.config);
-    const nextDraft = editGenerationDraft(existing, definition, {
+    const baseDraft = existing ?? createInitialGenerationDraft(definition, resolved.preference?.config, this.context.now());
+    const nextDraft = editGenerationDraft(baseDraft, definition, {
       ...config2 ? { config: config2 } : {},
-      ...input.definitionId === void 0 ? {} : { definitionId },
+      ...input.definitionId === void 0 ? {} : { definitionId: definition.id },
       ...input.prompt === void 0 ? {} : { prompt: requirePlainString2(input.prompt, "prompt") }
     }, this.context.now());
     const after = {
@@ -16246,13 +16444,19 @@ var CoreNodeCreativeLoop = class {
       label: "Edit generation Draft",
       timeoutMs
     });
-    return attention(current.id, { draftId: nextDraft.id, viewNodeId: current.id });
+    await this.rememberWorkflowPreference(contentType, nextDraft);
+    return attention(current.id, {
+      definitionId: nextDraft.definitionId,
+      draftId: nextDraft.id,
+      selectionSource: resolved.source,
+      viewNodeId: current.id
+    });
   }
   async addVisualReference(input, timeoutMs) {
     assertOnlyKeys3(input, ["referenceViewNodeId", "viewNodeId"]);
     const target = this.requireTarget(requireString3(input.viewNodeId, "viewNodeId"));
     const draft = requireDraft(target);
-    const definition = await this.requireDefinition(draft.definitionId);
+    const definition = await this.requireSelectableDefinition(draft.definitionId);
     const referenceViewNodeId = requireString3(input.referenceViewNodeId, "referenceViewNodeId");
     const sourceDataType = await this.resolveReferenceDataType(referenceViewNodeId);
     const referenceId = `input_ref_${crypto.randomUUID().replaceAll("-", "")}`;
@@ -16264,14 +16468,12 @@ var CoreNodeCreativeLoop = class {
     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 definition = await this.requireSelectableDefinition(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 = input.placement === void 0 ? "end" : input.placement === "start" || input.placement === "end" ? input.placement : null;
-    if (!placement)
-      throw new Error("placement must be start or end.");
+    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 });
@@ -16292,7 +16494,7 @@ var CoreNodeCreativeLoop = class {
       assertOnlyKeys3(input, ["viewNodeId"]);
       const target = this.requireTarget(requireString3(input.viewNodeId, "viewNodeId"));
       const draft = requireDraft(target);
-      const definition = await this.requireDefinition(draft.definitionId);
+      const definition = await this.requireSelectableDefinition(draft.definitionId);
       const output = requirePrimaryOutput(definition, target.contentType);
       const prepared = await prepareGenerationInput({
         definition,
@@ -16708,6 +16910,40 @@ var CoreNodeCreativeLoop = class {
     this.coreNodes.set(id2, node);
     return structuredClone(node);
   }
+  async resolveDefaultDefinition(contentType) {
+    const preference = await this.readWorkflowPreference(contentType);
+    return selectDefaultWorkflowDefinition({
+      contentType,
+      definitions: this.selectableDefinitions(),
+      preference
+    });
+  }
+  async resolveExplicitDefinition(contentType, definitionId) {
+    const definition = await this.requireSelectableDefinition(definitionId);
+    requirePrimaryOutput(definition, contentType);
+    const preference = await this.readWorkflowPreference(contentType);
+    return {
+      definition,
+      preference: preference?.definitionId === definition.id ? preference : null,
+      source: "explicit"
+    };
+  }
+  async readWorkflowPreference(contentType) {
+    try {
+      return await this.systems.workflowPreferences?.read(contentType) ?? null;
+    } catch {
+      return null;
+    }
+  }
+  async rememberWorkflowPreference(contentType, draft) {
+    try {
+      await this.systems.workflowPreferences?.write(contentType, {
+        config: readGenerationDraftConfig(draft) ?? {},
+        definitionId: draft.definitionId
+      });
+    } catch {
+    }
+  }
   async requireDefinition(id2) {
     const cached2 = this.definitions.get(id2);
     if (cached2)
@@ -16718,6 +16954,16 @@ var CoreNodeCreativeLoop = class {
     this.definitions.set(id2, definition);
     return definition;
   }
+  async requireSelectableDefinition(id2) {
+    const definition = await this.requireDefinition(id2);
+    if (!isWorkflowDefinitionAvailable(definition, this.systems.workflowAccessTier)) {
+      throw Object.assign(new Error(`Workflow Definition ${id2} is not available to the authenticated account.`), { code: "workflow-not-available-for-account" });
+    }
+    return definition;
+  }
+  selectableDefinitions() {
+    return [...this.definitions.values()].filter((definition) => isWorkflowDefinitionAvailable(definition, this.systems.workflowAccessTier));
+  }
   async resolveReferenceDataType(referenceViewNodeId) {
     const referenceViewNode = this.requireViewNode(referenceViewNodeId);
     if (referenceViewNode.type !== "resource") {
@@ -16921,6 +17167,38 @@ function requireString3(value, field) {
     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.`);
@@ -17278,8 +17556,8 @@ function parsePosition3(value) {
   return { x: position.x, y: position.y };
 }
 function deriveName(url2, contentType) {
-  const path9 = new URL(url2).pathname;
-  const filename = decodeURIComponent(path9.split("/").filter(Boolean).at(-1) ?? "");
+  const path10 = new URL(url2).pathname;
+  const filename = decodeURIComponent(path10.split("/").filter(Boolean).at(-1) ?? "");
   const withoutExtension = filename.replace(/\.[a-z0-9]+$/i, "").trim();
   return withoutExtension || `Imported ${contentType}`;
 }
@@ -17384,9 +17662,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);
@@ -17420,9 +17701,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: {
@@ -17456,6 +17738,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 {
@@ -17559,6 +17842,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;
@@ -18328,6 +18619,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({
@@ -18339,6 +18632,9 @@ var SemanticCanvasRuntime = class {
         revision: this.projectionRevision
       });
       this.scheduleProjectContentRefresh();
+      if (addedPendingWorkflowInstanceIds.length > 0) {
+        this.creativeLoop?.observePendingWorkflowRuns(addedPendingWorkflowInstanceIds, 15e3);
+      }
     });
   }
   get revision() {
@@ -18421,7 +18717,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)
@@ -18432,7 +18728,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)) {
@@ -18766,6 +19062,8 @@ function createCreativeLoop(options, projectContentProjection, context) {
     foundationData: options.foundationData,
     projectContent: options.projectContent,
     projectContentProjection,
+    workflowAccessTier: options.workflowAccessTier ?? "paid",
+    workflowPreferences: options.workflowPreferences,
     workflowRuntime: options.workflowRuntime
   };
   return new CoreNodeCreativeLoop(context, systems);
@@ -18845,6 +19143,114 @@ function normalizeCreationProvenanceSuffix(value) {
   return normalized;
 }
 
+// src/cli/workflow-preference-store.ts
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+var FORMAT = "az8.workflow-preference.v1";
+function createNodeWorkflowPreferenceStore(options) {
+  const accountId = options.accountId.trim();
+  if (!accountId) throw new Error("Workflow preference scope requires an account id.");
+  const env = options.env ?? process.env;
+  const stateRoot = path.resolve(
+    options.stateRoot ?? env.AZ8_CLI_STATE_DIR ?? path.join(env.XDG_STATE_HOME ?? path.join(homedir(), ".local", "state"), "az8-cli")
+  );
+  const directory = path.join(stateRoot, "workflow-preferences");
+  return {
+    async read(contentType) {
+      await ensurePrivateDirectory(directory);
+      const filePath = preferencePath(directory, options.environment, accountId, contentType);
+      try {
+        await assertPrivateRegularFile(filePath);
+        return parseStoredPreference(
+          JSON.parse(await readFile(filePath, "utf8")),
+          options.environment,
+          accountId,
+          contentType
+        );
+      } catch (error51) {
+        if (error51.code === "ENOENT") return null;
+        return null;
+      }
+    },
+    async write(contentType, preference) {
+      const normalized = normalizePreference(preference);
+      await ensurePrivateDirectory(directory);
+      const value = {
+        accountId,
+        contentType,
+        environment: options.environment,
+        format: FORMAT,
+        preference: normalized
+      };
+      await writeJsonAtomic(
+        preferencePath(directory, options.environment, accountId, contentType),
+        value
+      );
+    }
+  };
+}
+function parseStoredPreference(value, environment, accountId, contentType) {
+  if (!isRecord2(value) || value.format !== FORMAT || value.environment !== environment || value.accountId !== accountId || value.contentType !== contentType) {
+    return null;
+  }
+  try {
+    return normalizePreference(value.preference);
+  } catch {
+    return null;
+  }
+}
+function normalizePreference(value) {
+  if (!isRecord2(value) || typeof value.definitionId !== "string" || !value.definitionId.trim()) {
+    throw new Error("Workflow preference requires a Definition id.");
+  }
+  if (!isRecord2(value.config)) throw new Error("Workflow preference config must be an object.");
+  const config2 = Object.fromEntries(
+    Object.entries(value.config).filter(
+      (entry) => typeof entry[1] === "boolean" || typeof entry[1] === "string" || typeof entry[1] === "number" && Number.isFinite(entry[1])
+    )
+  );
+  return { config: config2, definitionId: value.definitionId.trim() };
+}
+function preferencePath(directory, environment, accountId, contentType) {
+  const digest = createHash("sha256").update(`${environment}\0${accountId}\0${contentType}`).digest("hex");
+  return path.join(directory, `${digest}.json`);
+}
+async function ensurePrivateDirectory(directory) {
+  await mkdir(directory, { mode: 448, recursive: true });
+  const metadata = await lstat(directory);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+    throw new Error("Workflow preference state path is not a private directory.");
+  }
+  if (typeof process.getuid === "function" && metadata.uid !== process.getuid()) {
+    throw new Error("Workflow preference state directory has a different owner.");
+  }
+  await chmod(directory, 448);
+}
+async function assertPrivateRegularFile(filePath) {
+  const metadata = await lstat(filePath);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new Error("Workflow preference state is not a regular file.");
+  }
+  if (typeof process.getuid === "function" && metadata.uid !== process.getuid()) {
+    throw new Error("Workflow preference state has a different owner.");
+  }
+  if ((metadata.mode & 63) !== 0) {
+    throw new Error("Workflow preference state is not owner-private.");
+  }
+}
+async function writeJsonAtomic(filePath, value) {
+  const temporary = `${filePath}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}
+`, { mode: 384 });
+  await rename(temporary, filePath);
+  await chmod(filePath, 384);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/integrations/backend.ts
 var BackendRequestError = class extends Error {
   code;
@@ -18873,7 +19279,7 @@ var Az8BackendClient = class {
     this.config = config2;
   }
   config;
-  async request(path9, options = {}) {
+  async request(path10, options = {}) {
     const method = options.method ?? "GET";
     const token = await this.config.credentials.getToken();
     const attempts = options.write ? 1 : 2;
@@ -18881,7 +19287,7 @@ var Az8BackendClient = class {
     for (let attempt = 1; attempt <= attempts; attempt += 1) {
       let response;
       try {
-        response = await this.fetchWithDeadline(path9, token, method, options);
+        response = await this.fetchWithDeadline(path10, token, method, options);
       } catch (error51) {
         if (options.write) throw new IndeterminateBackendWriteError(error51);
         lastError = error51;
@@ -18893,11 +19299,11 @@ var Az8BackendClient = class {
     }
     throw lastError;
   }
-  async fetchWithDeadline(path9, token, method, options) {
+  async fetchWithDeadline(path10, token, method, options) {
     const abortController2 = new AbortController();
     const timeout = setTimeout(() => abortController2.abort(), options.timeoutMs ?? 15e3);
     try {
-      return await this.config.fetch(`${this.config.backendUrl}/${path9.replace(/^\/+/, "")}`, {
+      return await this.config.fetch(`${this.config.backendUrl}/${path10.replace(/^\/+/, "")}`, {
         method,
         headers: {
           Cookie: `token=${token}`,
@@ -18942,15 +19348,22 @@ function toAuthenticatedAccount(profile) {
   const accountId = profile.accountId.trim();
   if (!accountId)
     throw new Error("Authenticated account profile is missing account id.");
+  const accessTier = isFreeAccount(profile) ? "free" : "paid";
   const nickname = profile.nickname?.trim();
   if (nickname)
-    return { accountId, displayName: nickname };
+    return { accessTier, accountId, displayName: nickname };
   const emailName = profile.email.split("@")[0]?.trim();
   return {
+    accessTier,
     accountId,
     displayName: emailName || `User ${accountId}`
   };
 }
+function isFreeAccount(profile) {
+  if (profile.identities)
+    return !profile.identities.includes("valid_user");
+  return (profile.subscriptionType?.trim().toLowerCase() || "free") === "free";
+}
 
 // src/integrations/account-profile.ts
 function createAz8AccountProfileClient(config2) {
@@ -18985,7 +19398,13 @@ function createAz8AccountProfileRepository(config2) {
       return {
         accountId: String(payload.data.account_id),
         email: payload.data.email,
-        ...payload.data.nickname === void 0 ? {} : { nickname: payload.data.nickname }
+        ...Array.isArray(payload.data.identities) ? {
+          identities: payload.data.identities.filter(
+            (value) => typeof value === "string"
+          )
+        } : {},
+        ...payload.data.nickname === void 0 ? {} : { nickname: payload.data.nickname },
+        ...payload.data.subscription_type === void 0 ? {} : { subscriptionType: payload.data.subscription_type }
       };
     }
   };
@@ -19635,10 +20054,10 @@ async function parseStatusEvent(event, onStatus) {
 }
 
 // src/media/upload.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import { constants } from "node:fs";
-import { lstat, open } from "node:fs/promises";
-import path from "node:path";
+import { lstat as lstat2, open } from "node:fs/promises";
+import path2 from "node:path";
 import { Transform } from "node:stream";
 
 // ../../node_modules/.pnpm/strtok3@10.3.5/node_modules/strtok3/lib/stream/Errors.js
@@ -23510,10 +23929,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);
@@ -23524,10 +23945,10 @@ function createNodeCanvasMediaUploadSystem(config2, cwd = process.cwd()) {
 }
 async function openUploadSource(sourceReference, cwd) {
   if (!sourceReference.trim()) throw new Error("Media upload source must not be blank.");
-  const absolutePath = path.resolve(cwd, sourceReference);
+  const absolutePath = path2.resolve(cwd, sourceReference);
   let sourceStat;
   try {
-    sourceStat = await lstat(absolutePath);
+    sourceStat = await lstat2(absolutePath);
   } catch {
     throw new Error("Media upload source does not exist or cannot be inspected.");
   }
@@ -23547,12 +23968,12 @@ 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.");
   }
-  const hash2 = createHash("sha256");
+  const hash2 = createHash2("sha256");
   const header = Buffer.allocUnsafe(Math.min(FILE_TYPE_HEADER_BYTES, before.size));
   const buffer = Buffer.allocUnsafe(Math.min(HASH_BUFFER_BYTES, before.size));
   let bytes = 0;
@@ -23566,6 +23987,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) {
@@ -23579,7 +24001,7 @@ async function inspectUploadSource(handle, absolutePath) {
   return {
     bytes,
     extension: detected.ext,
-    fileName: path.basename(absolutePath),
+    fileName: path2.basename(absolutePath),
     lastModified: Math.max(0, Math.round(after.mtimeMs)),
     mediaType,
     mimeType: detected.mime,
@@ -23602,6 +24024,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",
@@ -23610,12 +24036,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;
@@ -23634,13 +24068,17 @@ async function putPreparedFile(config2, handle, absolutePath, descriptor2, uploa
     () => controller.abort(new Error("Media upload timed out.")),
     timeoutMs ?? 3e5
   );
-  const hash2 = createHash("sha256");
+  const hash2 = createHash2("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({
@@ -23676,6 +24114,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.`);
@@ -23744,8 +24211,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 ?? [];
@@ -23755,6 +24233,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",
@@ -23775,6 +24256,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();
@@ -23813,7 +24297,7 @@ function matches(interest, fact) {
   return !filter.states || filter.states.includes(fact.state);
 }
 function patchFilter(current, patch) {
-  if (!isRecord2(patch)) {
+  if (!isRecord3(patch)) {
     throw interestError("interest-filter-invalid", "Interest filter patch must be an object.");
   }
   const next = structuredClone(current);
@@ -23828,7 +24312,7 @@ function validateFilter(kind, filter) {
   validateFilterEntries(kind, Object.entries(filter));
 }
 function validateFilterPatch(kind, filter) {
-  if (!isRecord2(filter)) {
+  if (!isRecord3(filter)) {
     throw interestError("interest-filter-invalid", "Interest filter patch must be an object.");
   }
   validateFilterEntries(kind, Object.entries(filter));
@@ -23922,7 +24406,7 @@ function assertAllowed(values, allowed, label) {
 function isInterestKind(value) {
   return value === "canvas" || value === "session" || value === "workflow";
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function interestError(code, message) {
@@ -23930,11 +24414,11 @@ function interestError(code, message) {
 }
 
 // src/canvas/watch/project-observation.ts
-function projectCanvasObservation(observation, observedAt) {
+function projectCanvasObservation(observation, observedAt, workflowTarget) {
   const viewNodeFacts = (observation.viewNodeChanges ?? []).map(
     (change) => projectViewNodeChange(change, observation.kind, observedAt)
   );
-  return observation.workflowRun ? [...viewNodeFacts, projectWorkflowRun(observation.workflowRun, observedAt)] : viewNodeFacts;
+  return observation.workflowRun ? [...viewNodeFacts, projectWorkflowRun(observation.workflowRun, observedAt, workflowTarget)] : viewNodeFacts;
 }
 function projectSessionState(input) {
   return {
@@ -23969,7 +24453,7 @@ function projectViewNodeChange(change, source, observedAt) {
     ...typeof viewNode.type === "string" ? { viewNodeType: viewNode.type } : {}
   };
 }
-function projectWorkflowRun(run, observedAt) {
+function projectWorkflowRun(run, observedAt, target) {
   const terminal = isTerminalWorkflowRunStatus(run.status);
   return {
     changeKind: terminal ? `workflow.${run.status}` : "workflow.progress",
@@ -23980,6 +24464,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 } : {},
@@ -23987,8 +24472,10 @@ function projectWorkflowRun(run, observedAt) {
         }
       } : {},
       ...run.progress === void 0 ? {} : { progress: run.progress },
+      ...target?.status === "resolved" ? { viewNodeId: target.viewNodeId } : terminal ? { targetResolution: target?.status ?? "unresolved" } : {},
       ...run.outputs.length > 0 ? {
         outputs: run.outputs.map((output) => ({
+          coreNodeId: output.coreNodeId,
           role: output.role,
           slotName: output.slotName,
           ...output.viewNodeId ? { viewNodeId: output.viewNodeId } : {}
@@ -24002,7 +24489,7 @@ function projectWorkflowRun(run, observedAt) {
 function summarizeViewNode(change) {
   const viewNode = change.after ?? change.before;
   if (!viewNode) return {};
-  const data = isRecord3(viewNode.data) ? viewNode.data : {};
+  const data = isRecord4(viewNode.data) ? viewNode.data : {};
   const summary = {
     ...typeof viewNode.contentType === "string" ? { contentType: viewNode.contentType } : {},
     ...typeof data.label === "string" ? { name: data.label } : {},
@@ -24013,10 +24500,10 @@ function summarizeViewNode(change) {
     if (typeof data.color === "string") summary.color = data.color;
     if (typeof data.creator_name === "string") summary.creatorName = data.creator_name;
   }
-  if (change.changedFields.includes("position") && isRecord3(viewNode.position)) {
+  if (change.changedFields.includes("position") && isRecord4(viewNode.position)) {
     summary.position = structuredClone(viewNode.position);
   }
-  if (change.changedFields.includes("size") && isRecord3(viewNode.size)) {
+  if (change.changedFields.includes("size") && isRecord4(viewNode.size)) {
     summary.size = structuredClone(viewNode.size);
   }
   if (change.changedFields.includes("parent")) summary.parentId = viewNode.parentId ?? null;
@@ -24034,7 +24521,7 @@ function fieldGroup(field) {
   if (field === "parent" || field === "stacking") return "hierarchy";
   return field;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function safeWorkflowMessage(value) {
@@ -24043,7 +24530,7 @@ function safeWorkflowMessage(value) {
 
 // src/canvas/watch/watch.ts
 var AgentCollaborationWatch = class {
-  interests = new CollaborationInterestRegistry();
+  interests;
   maxChangesPerDelivery;
   maxPendingChanges;
   maxRecentResults;
@@ -24054,6 +24541,7 @@ var AgentCollaborationWatch = class {
   activeWait = null;
   continuityLost = false;
   constructor(options = {}) {
+    this.interests = new CollaborationInterestRegistry(options.includeSystemWorkflowTerminal);
     this.maxChangesPerDelivery = positive(
       options.maxChangesPerDelivery ?? 64,
       "maxChangesPerDelivery"
@@ -24289,7 +24777,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,
@@ -24308,6 +24796,7 @@ var CanvasSession = class {
   unsubscribeRuntime = null;
   observationListeners = /* @__PURE__ */ new Set();
   knownWorkflowRunIds = /* @__PURE__ */ new Set();
+  knownWorkflowTargets = /* @__PURE__ */ new Map();
   projectionRevision = 0;
   actorId = null;
   collaborationContext = null;
@@ -24372,17 +24861,29 @@ var CanvasSession = class {
         projectContents: contentSync.contents,
         projectId: authenticated.id,
         role: authenticated.role,
+        workflowAccessTier: actor.accessTier,
         workflowDefinitions,
+        workflowPreferences: this.dependencies.workflowPreferences?.(actor),
         workflowRuntime
       });
       this.runtime = runtime;
       for (const workflowRunId of runtime.getSnapshot().pendingWorkflowInstanceIds) {
         this.knownWorkflowRunIds.add(workflowRunId);
+        this.retainWorkflowTarget(workflowRunId);
       }
       this.projectionRevision = runtime.revision;
       this.unsubscribeRuntime = runtime.subscribe((observation) => {
         this.projectionRevision = observation.revision;
-        this.watch.recordMany(projectCanvasObservation(observation, Date.now()));
+        if (observation.workflowRun) {
+          this.knownWorkflowRunIds.add(observation.workflowRun.id);
+        }
+        this.watch.recordMany(
+          projectCanvasObservation(
+            observation,
+            Date.now(),
+            observation.workflowRun ? this.resolveWorkflowTarget(observation.workflowRun.id) : void 0
+          )
+        );
         const legacyObservation = {
           ...observation.changedViewNodeIds ? { changedViewNodeIds: observation.changedViewNodeIds } : {},
           kind: observation.kind,
@@ -24400,14 +24901,29 @@ var CanvasSession = class {
       throw error51;
     }
   }
-  async execute(name, input, timeoutMs) {
+  async execute(name, input, timeoutMs, options = {}) {
     const runtime = this.requireRuntime();
     if (typeof input.workflowRunId === "string" && input.workflowRunId) {
       this.knownWorkflowRunIds.add(input.workflowRunId);
     }
-    const result3 = await runtime.execute(name, input, timeoutMs);
+    let result3;
+    try {
+      result3 = await runtime.execute(name, input, timeoutMs, options);
+    } catch (error51) {
+      const indeterminate = readCanvasOperationIndeterminateResult(error51);
+      if (typeof indeterminate?.workflowRunId === "string" && indeterminate.workflowRunId && typeof indeterminate.viewNodeId === "string" && indeterminate.viewNodeId) {
+        this.knownWorkflowRunIds.add(indeterminate.workflowRunId);
+        this.knownWorkflowTargets.set(indeterminate.workflowRunId, indeterminate.viewNodeId);
+      }
+      throw error51;
+    }
     if (typeof result3.result.workflowRunId === "string" && result3.result.workflowRunId) {
       this.knownWorkflowRunIds.add(result3.result.workflowRunId);
+      if (typeof result3.result.viewNodeId === "string" && result3.result.viewNodeId) {
+        this.knownWorkflowTargets.set(result3.result.workflowRunId, result3.result.viewNodeId);
+      } else {
+        this.retainWorkflowTarget(result3.result.workflowRunId);
+      }
     }
     this.projectionRevision = result3.revision;
     if (result3.attention) this.publishAttention(result3.attention);
@@ -24431,7 +24947,8 @@ var CanvasSession = class {
         if (!isWorkflowRun(workflowRun)) continue;
         for (const fact of projectCanvasObservation(
           { kind: "workflow", revision: result3.revision, workflowRun },
-          Date.now()
+          Date.now(),
+          this.resolveWorkflowTarget(workflowRun.id)
         )) {
           this.watch.recordAuthoritativeWorkflow(fact);
         }
@@ -24530,6 +25047,28 @@ var CanvasSession = class {
     this.document = null;
     this.health.connectionId = null;
   }
+  resolveWorkflowTarget(workflowRunId) {
+    const retained = this.knownWorkflowTargets.get(workflowRunId);
+    if (!this.runtime) {
+      return retained ? { status: "resolved", viewNodeId: retained } : { status: "unresolved" };
+    }
+    const current = resolveWorkflowTargetFromSnapshot(this.runtime.getSnapshot(), workflowRunId);
+    if (current.status === "ambiguous") return current;
+    if (current.status === "resolved") {
+      if (retained && retained !== current.viewNodeId) return { status: "ambiguous" };
+      this.knownWorkflowTargets.set(workflowRunId, current.viewNodeId);
+      return current;
+    }
+    return retained ? { status: "resolved", viewNodeId: retained } : current;
+  }
+  retainWorkflowTarget(workflowRunId) {
+    if (!this.runtime) return { status: "unresolved" };
+    const resolution = resolveWorkflowTargetFromSnapshot(this.runtime.getSnapshot(), workflowRunId);
+    if (resolution.status === "resolved") {
+      this.knownWorkflowTargets.set(workflowRunId, resolution.viewNodeId);
+    }
+    return resolution;
+  }
   transition(state, onState) {
     const previousState = this.health.state;
     this.health.state = state;
@@ -24588,7 +25127,12 @@ var CanvasClient = class {
   session;
   receipts = [];
   constructor(config2, projectId, session) {
-    this.session = session ?? new CanvasSession(config2, projectId);
+    this.session = session ?? new CanvasSession(config2, projectId, void 0, {
+      workflowPreferences: (actor) => createNodeWorkflowPreferenceStore({
+        accountId: actor.accountId,
+        environment: config2.environment
+      })
+    });
   }
   async connect(displayName, onState) {
     await this.session.connect(displayName, onState);
@@ -24654,7 +25198,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,
@@ -24747,8 +25293,8 @@ function readTimedOut(value) {
 }
 
 // src/cli/config.ts
-import { readFile } from "node:fs/promises";
-import path2 from "node:path";
+import { readFile as readFile2 } from "node:fs/promises";
+import path3 from "node:path";
 var DEFAULT_ENV_FILE = ".env.local";
 var DEFAULT_ENVIRONMENT = "production";
 var ENVIRONMENT_ORIGINS = {
@@ -24758,7 +25304,7 @@ var ENVIRONMENT_ORIGINS = {
 async function resolveCliConfig(options, dependencies) {
   const cwd = dependencies.cwd ?? process.cwd();
   const envFile = options.envFile;
-  const fileEnvironment = envFile ? await readEnvironmentFile(path2.resolve(cwd, envFile)) : await readDefaultEnvironmentFile(cwd);
+  const fileEnvironment = envFile ? await readEnvironmentFile(path3.resolve(cwd, envFile)) : await readDefaultEnvironmentFile(cwd);
   const environmentVariables = {
     ...fileEnvironment,
     ...dependencies.env ?? process.env
@@ -24780,6 +25326,7 @@ async function resolveCliConfig(options, dependencies) {
         return token;
       }
     },
+    environment,
     fetch: dependencies.fetch ?? globalThis.fetch,
     serviceUrl: normalizeUrl(
       options.serviceUrl ?? environmentVariables.AZ8_SERVICE_URL ?? `${origin}/api`
@@ -24793,7 +25340,7 @@ function readEnvironment(value) {
 }
 async function readEnvironmentFile(filePath) {
   try {
-    const contents = await readFile(filePath, "utf8");
+    const contents = await readFile2(filePath, "utf8");
     return Object.fromEntries(
       contents.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#")).flatMap((line) => {
         const separator = line.indexOf("=");
@@ -24809,11 +25356,11 @@ async function readEnvironmentFile(filePath) {
   }
 }
 async function readDefaultEnvironmentFile(cwd) {
-  let directory = path2.resolve(cwd);
+  let directory = path3.resolve(cwd);
   while (true) {
-    const environment = await readEnvironmentFile(path2.join(directory, DEFAULT_ENV_FILE));
+    const environment = await readEnvironmentFile(path3.join(directory, DEFAULT_ENV_FILE));
     if (Object.keys(environment).length > 0) return environment;
-    const parent = path2.dirname(directory);
+    const parent = path3.dirname(directory);
     if (parent === directory) return {};
     directory = parent;
   }
@@ -24823,11 +25370,11 @@ function normalizeUrl(value) {
 }
 
 // src/agent-session/rpc.ts
-import { chmod, unlink } from "node:fs/promises";
+import { chmod as chmod2, 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 = "";
@@ -24857,14 +25404,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));
@@ -24903,7 +25459,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(
@@ -24923,7 +25482,7 @@ async function listenAgentSessionRpc(socketPath, handler) {
       resolve();
     });
   });
-  await chmod(socketPath, 384);
+  await chmod2(socketPath, 384);
   return {
     async close() {
       const closed = new Promise(
@@ -24935,6 +25494,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)}
@@ -24961,20 +25527,20 @@ async function unlinkIfPresent(filePath) {
 }
 
 // src/agent-session/state-store.ts
-import { createHash as createHash2, randomUUID } from "node:crypto";
+import { createHash as createHash3, randomUUID as randomUUID2 } from "node:crypto";
 import {
-  chmod as chmod2,
-  lstat as lstat2,
-  mkdir,
+  chmod as chmod3,
+  lstat as lstat3,
+  mkdir as mkdir2,
   readdir,
-  readFile as readFile2,
+  readFile as readFile3,
   realpath,
-  rename,
+  rename as rename2,
   unlink as unlink2,
-  writeFile
+  writeFile as writeFile2
 } from "node:fs/promises";
-import { homedir } from "node:os";
-import path3 from "node:path";
+import { homedir as homedir2 } from "node:os";
+import path4 from "node:path";
 
 // src/agent-session/types.ts
 var AGENT_SESSION_FORMAT = "az8.agent-session.v1";
@@ -24987,44 +25553,44 @@ var AgentSessionStateStore = class {
   stateRoot;
   env;
   constructor(options = {}) {
-    this.cwd = path3.resolve(options.cwd ?? process.cwd());
+    this.cwd = path4.resolve(options.cwd ?? process.cwd());
     this.env = options.env ?? process.env;
-    this.stateRoot = path3.resolve(
-      options.stateRoot ?? this.env.AZ8_CLI_STATE_DIR ?? path3.join(this.env.XDG_STATE_HOME ?? path3.join(homedir(), ".local", "state"), "az8-cli")
+    this.stateRoot = path4.resolve(
+      options.stateRoot ?? this.env.AZ8_CLI_STATE_DIR ?? path4.join(this.env.XDG_STATE_HOME ?? path4.join(homedir2(), ".local", "state"), "az8-cli")
     );
     const uid = typeof process.getuid === "function" ? process.getuid() : 0;
-    const defaultRuntimeRoot = process.platform === "linux" && this.env.XDG_RUNTIME_DIR ? path3.join(this.env.XDG_RUNTIME_DIR, "az8-cli") : path3.join("/tmp", `az8-cli-${uid}`);
-    this.runtimeRoot = path3.resolve(options.runtimeRoot ?? defaultRuntimeRoot);
+    const defaultRuntimeRoot = process.platform === "linux" && this.env.XDG_RUNTIME_DIR ? path4.join(this.env.XDG_RUNTIME_DIR, "az8-cli") : path4.join("/tmp", `az8-cli-${uid}`);
+    this.runtimeRoot = path4.resolve(options.runtimeRoot ?? defaultRuntimeRoot);
   }
   createSessionId() {
-    return `session_${randomUUID()}`;
+    return `session_${randomUUID2()}`;
   }
   async initialize() {
     await Promise.all([
-      ensurePrivateDirectory(this.stateRoot),
-      ensurePrivateDirectory(this.runtimeRoot),
-      ensurePrivateDirectory(this.descriptorsDirectory()),
-      ensurePrivateDirectory(this.contextsDirectory()),
-      ensurePrivateDirectory(this.launchesDirectory())
+      ensurePrivateDirectory2(this.stateRoot),
+      ensurePrivateDirectory2(this.runtimeRoot),
+      ensurePrivateDirectory2(this.descriptorsDirectory()),
+      ensurePrivateDirectory2(this.contextsDirectory()),
+      ensurePrivateDirectory2(this.launchesDirectory())
     ]);
   }
   descriptorPath(sessionId) {
-    return path3.join(this.descriptorsDirectory(), `${requireSessionId(sessionId)}.json`);
+    return path4.join(this.descriptorsDirectory(), `${requireSessionId(sessionId)}.json`);
   }
   socketPath(sessionId) {
-    const digest = createHash2("sha256").update(requireSessionId(sessionId)).digest("hex").slice(0, 24);
-    return path3.join(this.runtimeRoot, `${digest}.sock`);
+    const digest = createHash3("sha256").update(requireSessionId(sessionId)).digest("hex").slice(0, 24);
+    return path4.join(this.runtimeRoot, `${digest}.sock`);
   }
   async writeDescriptor(descriptor2) {
     assertDescriptor(descriptor2);
     await this.initialize();
-    await writeJsonAtomic(this.descriptorPath(descriptor2.sessionId), descriptor2);
+    await writeJsonAtomic2(this.descriptorPath(descriptor2.sessionId), descriptor2);
   }
   async readDescriptor(sessionId) {
     await this.initialize();
     const filePath = this.descriptorPath(sessionId);
-    await assertPrivateRegularFile(filePath);
-    const value = JSON.parse(await readFile2(filePath, "utf8"));
+    await assertPrivateRegularFile2(filePath);
+    const value = JSON.parse(await readFile3(filePath, "utf8"));
     assertDescriptor(value);
     return value;
   }
@@ -25046,25 +25612,25 @@ var AgentSessionStateStore = class {
   }
   async writeLaunchSpec(spec) {
     await this.initialize();
-    const filePath = path3.join(this.launchesDirectory(), `${requireSessionId(spec.sessionId)}.json`);
-    await writeJsonAtomic(filePath, spec);
+    const filePath = path4.join(this.launchesDirectory(), `${requireSessionId(spec.sessionId)}.json`);
+    await writeJsonAtomic2(filePath, spec);
     return filePath;
   }
   async deleteLaunchSpec(sessionId) {
     await unlinkIfPresent2(
-      path3.join(this.launchesDirectory(), `${requireSessionId(sessionId)}.json`)
+      path4.join(this.launchesDirectory(), `${requireSessionId(sessionId)}.json`)
     );
   }
   async selectCurrent(sessionId) {
     await this.readDescriptor(sessionId);
     const context = await this.contextIdentity();
-    await writeJsonAtomic(this.contextPath(context), { context, sessionId });
+    await writeJsonAtomic2(this.contextPath(context), { context, sessionId });
   }
   async readCurrent() {
     await this.initialize();
     const context = await this.contextIdentity();
     try {
-      const value = JSON.parse(await readFile2(this.contextPath(context), "utf8"));
+      const value = JSON.parse(await readFile3(this.contextPath(context), "utf8"));
       if (value.context !== context || typeof value.sessionId !== "string") return void 0;
       return requireSessionId(value.sessionId);
     } catch (error51) {
@@ -25088,13 +25654,13 @@ var AgentSessionStateStore = class {
     return requireSessionId(selected);
   }
   descriptorsDirectory() {
-    return path3.join(this.stateRoot, "sessions");
+    return path4.join(this.stateRoot, "sessions");
   }
   contextsDirectory() {
-    return path3.join(this.stateRoot, "contexts");
+    return path4.join(this.stateRoot, "contexts");
   }
   launchesDirectory() {
-    return path3.join(this.stateRoot, "launches");
+    return path4.join(this.stateRoot, "launches");
   }
   async contextIdentity() {
     const override = this.env.AZ8_CONTEXT?.trim();
@@ -25106,16 +25672,16 @@ var AgentSessionStateStore = class {
     }
   }
   contextPath(context) {
-    const digest = createHash2("sha256").update(context).digest("hex");
-    return path3.join(this.contextsDirectory(), `${digest}.json`);
+    const digest = createHash3("sha256").update(context).digest("hex");
+    return path4.join(this.contextsDirectory(), `${digest}.json`);
   }
 };
 async function readAndDeleteLaunchSpec(filePath) {
-  if (path3.basename(path3.dirname(filePath)) !== "launches") {
+  if (path4.basename(path4.dirname(filePath)) !== "launches") {
     throw sessionStateError("invalid-session-launch", "Session launch path is invalid.");
   }
-  await assertPrivateRegularFile(filePath);
-  const value = JSON.parse(await readFile2(filePath, "utf8"));
+  await assertPrivateRegularFile2(filePath);
+  const value = JSON.parse(await readFile3(filePath, "utf8"));
   assertLaunchSpec(value, filePath);
   await unlinkIfPresent2(filePath);
   return value;
@@ -25137,30 +25703,30 @@ function assertLaunchSpec(value, launchPath) {
     throw sessionStateError("invalid-session-launch", "Session launch descriptor is invalid.");
   }
   const sessionId = requireSessionId(value.sessionId);
-  const stateRoot = path3.resolve(value.stateRoot);
-  const expectedLaunch = path3.join(stateRoot, "launches", `${sessionId}.json`);
-  if (path3.resolve(launchPath) !== expectedLaunch) {
+  const stateRoot = path4.resolve(value.stateRoot);
+  const expectedLaunch = path4.join(stateRoot, "launches", `${sessionId}.json`);
+  if (path4.resolve(launchPath) !== expectedLaunch) {
     throw sessionStateError(
       "invalid-session-launch",
       "Session launch identity does not match its path."
     );
   }
-  const expectedDescriptor = path3.join(stateRoot, "sessions", `${sessionId}.json`);
-  if (path3.resolve(value.descriptorPath) !== expectedDescriptor) {
+  const expectedDescriptor = path4.join(stateRoot, "sessions", `${sessionId}.json`);
+  if (path4.resolve(value.descriptorPath) !== expectedDescriptor) {
     throw sessionStateError("invalid-session-launch", "Session descriptor path is invalid.");
   }
-  const socketDigest = createHash2("sha256").update(sessionId).digest("hex").slice(0, 24);
-  const expectedSocket = path3.join(
-    path3.resolve(value.runtimeRoot),
+  const socketDigest = createHash3("sha256").update(sessionId).digest("hex").slice(0, 24);
+  const expectedSocket = path4.join(
+    path4.resolve(value.runtimeRoot),
     `${socketDigest}.sock`
   );
-  if (path3.resolve(value.socketPath) !== expectedSocket) {
+  if (path4.resolve(value.socketPath) !== expectedSocket) {
     throw sessionStateError("invalid-session-launch", "Session socket path is invalid.");
   }
 }
-async function ensurePrivateDirectory(directory) {
-  await mkdir(directory, { mode: 448, recursive: true });
-  const metadata = await lstat2(directory);
+async function ensurePrivateDirectory2(directory) {
+  await mkdir2(directory, { mode: 448, recursive: true });
+  const metadata = await lstat3(directory);
   if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
     throw sessionStateError(
       "unsafe-session-state",
@@ -25173,10 +25739,10 @@ async function ensurePrivateDirectory(directory) {
       "Session state directory has a different owner."
     );
   }
-  await chmod2(directory, 448);
+  await chmod3(directory, 448);
 }
-async function assertPrivateRegularFile(filePath) {
-  const metadata = await lstat2(filePath);
+async function assertPrivateRegularFile2(filePath) {
+  const metadata = await lstat3(filePath);
   if (!metadata.isFile() || metadata.isSymbolicLink()) {
     throw sessionStateError("unsafe-session-state", "Session state file is not a regular file.");
   }
@@ -25187,12 +25753,12 @@ async function assertPrivateRegularFile(filePath) {
     throw sessionStateError("unsafe-session-state", "Session state file is not owner-private.");
   }
 }
-async function writeJsonAtomic(filePath, value) {
-  const temporary = `${filePath}.${randomUUID()}.tmp`;
-  await writeFile(temporary, `${JSON.stringify(value, null, 2)}
+async function writeJsonAtomic2(filePath, value) {
+  const temporary = `${filePath}.${randomUUID2()}.tmp`;
+  await writeFile2(temporary, `${JSON.stringify(value, null, 2)}
 `, { mode: 384 });
-  await rename(temporary, filePath);
-  await chmod2(filePath, 384);
+  await rename2(temporary, filePath);
+  await chmod3(filePath, 384);
 }
 async function unlinkIfPresent2(filePath) {
   try {
@@ -25339,6 +25905,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 } : {}
           });
@@ -25347,6 +25914,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 } : {}
           })
@@ -25383,7 +25951,13 @@ async function createCanvasClient(spec, dependencies) {
     ...dependencies,
     cwd: spec.cwd
   });
-  const session = new CanvasSession(config2, spec.projectId);
+  const session = new CanvasSession(config2, spec.projectId, void 0, {
+    workflowPreferences: (actor) => createNodeWorkflowPreferenceStore({
+      accountId: actor.accountId,
+      environment: config2.environment,
+      stateRoot: spec.stateRoot
+    })
+  });
   const client = new CanvasClient(config2, spec.projectId, session);
   await client.connect(spec.clientName);
   return {
@@ -25437,13 +26011,13 @@ function assertRequest(request) {
       code: "invalid-watch-timeout"
     });
   }
-  if (request.kind === "interests.patch" && !isRecord4(request.input)) invalidPayload();
+  if (request.kind === "interests.patch" && !isRecord5(request.input)) invalidPayload();
   if (request.kind === "query") {
-    if (!isRecord4(request.input) || typeof request.input.target !== "string") invalidPayload();
+    if (!isRecord5(request.input) || typeof request.input.target !== "string") invalidPayload();
     parseCanvasQueryTarget(request.input.target);
   }
   if (request.kind === "operation") {
-    if (!isRecord4(request.input) || typeof request.name !== "string" || typeof request.requestId !== "string" || request.requestId.length === 0 || request.timeoutMs !== void 0 && (!Number.isInteger(request.timeoutMs) || request.timeoutMs < 1)) {
+    if (!isRecord5(request.input) || typeof request.name !== "string" || typeof request.requestId !== "string" || request.requestId.length === 0 || request.timeoutMs !== void 0 && (!Number.isInteger(request.timeoutMs) || request.timeoutMs < 1)) {
       invalidPayload();
     }
   }
@@ -25459,7 +26033,7 @@ function invalidPayload() {
     code: "invalid-session-request"
   });
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function readErrorCode2(error51) {
@@ -25795,6 +26369,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 } : {}
     });
@@ -26191,7 +26770,7 @@ function humanReadableArgName(arg) {
 // ../../node_modules/.pnpm/commander@15.0.0/node_modules/commander/lib/command.js
 import { EventEmitter as EventEmitter2 } from "node:events";
 import childProcess from "node:child_process";
-import path4 from "node:path";
+import path5 from "node:path";
 import fs from "node:fs";
 import process2 from "node:process";
 import { stripVTControlCharacters as stripVTControlCharacters2 } from "node:util";
@@ -28177,9 +28756,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
     args2 = args2.slice();
     const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
     function findFile(baseDir, baseName) {
-      const localBin = path4.resolve(baseDir, baseName);
+      const localBin = path5.resolve(baseDir, baseName);
       if (fs.existsSync(localBin)) return localBin;
-      if (sourceExt.includes(path4.extname(baseName))) return void 0;
+      if (sourceExt.includes(path5.extname(baseName))) return void 0;
       const foundExt = sourceExt.find(
         (ext) => fs.existsSync(`${localBin}${ext}`)
       );
@@ -28197,17 +28776,17 @@ Expecting one of '${allowedValues.join("', '")}'`);
       } catch {
         resolvedScriptPath = this._scriptPath;
       }
-      executableDir = path4.resolve(
-        path4.dirname(resolvedScriptPath),
+      executableDir = path5.resolve(
+        path5.dirname(resolvedScriptPath),
         executableDir
       );
     }
     if (executableDir) {
       let localFile = findFile(executableDir, executableFile);
       if (!localFile && !subcommand._executableFile && this._scriptPath) {
-        const legacyName = path4.basename(
+        const legacyName = path5.basename(
           this._scriptPath,
-          path4.extname(this._scriptPath)
+          path5.extname(this._scriptPath)
         );
         if (legacyName !== this._name) {
           localFile = findFile(
@@ -28218,7 +28797,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       }
       executableFile = localFile || executableFile;
     }
-    const launchWithNode = sourceExt.includes(path4.extname(executableFile));
+    const launchWithNode = sourceExt.includes(path5.extname(executableFile));
     let proc;
     if (process2.platform !== "win32") {
       if (launchWithNode) {
@@ -29135,7 +29714,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @return {Command}
    */
   nameFromFilename(filename) {
-    this._name = path4.basename(filename, path4.extname(filename));
+    this._name = path5.basename(filename, path5.extname(filename));
     return this;
   }
   /**
@@ -29149,9 +29728,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {string} [path]
    * @return {(string|null|Command)}
    */
-  executableDir(path9) {
-    if (path9 === void 0) return this._executableDir;
-    this._executableDir = path9;
+  executableDir(path10) {
+    if (path10 === void 0) return this._executableDir;
+    this._executableDir = path10;
     return this;
   }
   /**
@@ -29407,8 +29986,8 @@ function useColor() {
 var program = new Command();
 
 // src/canvas/one-shot.ts
-import { readFile as readFile3 } from "node:fs/promises";
-import path5 from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import path6 from "node:path";
 var MAX_INPUT_BYTES = 1024 * 1024;
 var PROCESS_SCOPED_OPERATIONS = /* @__PURE__ */ new Set(["redo", "undo"]);
 var PROCESS_SCOPED_QUERIES = /* @__PURE__ */ new Set(["receipt.detail", "receipts.summary"]);
@@ -29434,6 +30013,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);
@@ -29457,9 +30039,9 @@ async function readCanvasOneShotInputOptions(options, dependencies = {}) {
   let source = "{}";
   if (inline !== void 0) source = inline;
   if (file2 !== void 0) {
-    const filePath = path5.resolve(dependencies.cwd ?? process.cwd(), file2);
+    const filePath = path6.resolve(dependencies.cwd ?? process.cwd(), file2);
     try {
-      source = dependencies.readFile ? await dependencies.readFile(filePath) : await readFile3(filePath, "utf8");
+      source = dependencies.readFile ? await dependencies.readFile(filePath) : await readFile4(filePath, "utf8");
     } catch {
       throw canvasClientFailure(
         "invalid-operation-input",
@@ -29580,9 +30162,9 @@ function formatZodError(error51) {
 }
 
 // src/media/download.ts
-import { createHash as createHash3 } from "node:crypto";
-import { link, lstat as lstat3, open as open2, rename as rename2, stat, unlink as unlink3 } from "node:fs/promises";
-import path6 from "node:path";
+import { createHash as createHash4 } from "node:crypto";
+import { link, lstat as lstat4, open as open2, rename as rename3, stat, unlink as unlink3 } from "node:fs/promises";
+import path7 from "node:path";
 
 // ../../packages/foundation-data/dist/media.js
 var CoreNodeMediaResolutionError = class extends Error {
@@ -29619,21 +30201,24 @@ 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);
+  const requestedAbsolutePath = path7.resolve(dependencies.cwd ?? process.cwd(), command.outputPath);
   let outputTarget;
   try {
     outputTarget = await prepareOutputTarget(
@@ -29645,48 +30230,86 @@ 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)}
 `;
 }
-async function resolveMediaSource(client, command, randomUUID4) {
+async function resolveMediaSource(client, command, randomUUID5) {
   let coreNodeId;
   if (command.source.kind === "view-node") {
     try {
@@ -29696,7 +30319,8 @@ async function resolveMediaSource(client, command, randomUUID4) {
         "view-node-media-unavailable",
         safeCanvasMessage(error51),
         1,
-        false
+        false,
+        { cause: sanitizeDownloadCause(error51), phase: "source-resolution" }
       );
     }
   } else {
@@ -29705,7 +30329,7 @@ async function resolveMediaSource(client, command, randomUUID4) {
   const outcome = await client.executeOperation({
     input: { coreNodeId },
     name: "getCoreNode",
-    requestId: `media-download-resolve-${randomUUID4?.() ?? crypto.randomUUID()}`,
+    requestId: `media-download-resolve-${randomUUID5?.() ?? crypto.randomUUID()}`,
     timeoutMs: command.timeoutMs ?? DEFAULT_RESOLUTION_TIMEOUT_MS
   });
   if (outcome.receipt.status !== "succeeded") {
@@ -29714,7 +30338,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);
@@ -29733,7 +30358,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;
@@ -29742,7 +30368,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;
@@ -29753,11 +30380,12 @@ 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);
-  const parentPath = path6.dirname(absolutePath);
+  const absolutePath = path7.resolve(cwd, requestedPath);
+  const parentPath = path7.dirname(absolutePath);
   let parent;
   try {
     parent = await stat(parentPath);
@@ -29766,7 +30394,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()) {
@@ -29774,19 +30403,21 @@ 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;
   try {
-    existing = await lstat3(absolutePath);
+    existing = await lstat4(absolutePath);
   } catch (error51) {
     if (readFsCode2(error51) !== "ENOENT") {
       throw new MediaDownloadError(
         "output-target-unavailable",
         "Download output target cannot be inspected.",
         1,
-        false
+        false,
+        { phase: "output-setup" }
       );
     }
   }
@@ -29795,7 +30426,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())) {
@@ -29803,7 +30435,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 };
@@ -29814,9 +30447,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();
@@ -29825,7 +30458,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"));
@@ -29835,8 +30469,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") {
@@ -29844,8 +30479,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);
@@ -29878,7 +30514,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;
@@ -29889,7 +30526,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);
@@ -29911,12 +30549,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();
@@ -29935,9 +30574,9 @@ async function detectFileTypeFromFileHeader(filePath) {
 }
 async function openTemporaryFile(outputTarget, identity) {
   const safeIdentity = identity.replace(/[^a-z0-9-]/gi, "").slice(0, 64) || "download";
-  const basename = path6.basename(outputTarget.absolutePath);
+  const basename = path7.basename(outputTarget.absolutePath);
   for (let attempt = 0; attempt < 3; attempt += 1) {
-    const temporaryPath = path6.join(
+    const temporaryPath = path7.join(
       outputTarget.parentPath,
       `.${basename}.az8-${safeIdentity}-${attempt}.part`
     );
@@ -29967,11 +30606,12 @@ 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();
-  const hash2 = createHash3("sha256");
+  const hash2 = createHash4("sha256");
   let bytes = 0;
   try {
     while (true) {
@@ -29985,16 +30625,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();
   }
@@ -30003,7 +30644,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") };
@@ -30017,7 +30659,8 @@ async function writeAll(handle, value) {
         "output-write-stalled",
         "Temporary download file stopped accepting data.",
         1,
-        false
+        false,
+        { phase: "output-write" }
       );
     }
     offset += bytesWritten;
@@ -30029,8 +30672,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;
@@ -30039,15 +30683,16 @@ 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" }
     );
   }
 }
 async function commitTemporaryFile(temporaryPath, outputTarget, overwrite) {
   try {
     if (overwrite) {
-      await rename2(temporaryPath, outputTarget.absolutePath);
+      await rename3(temporaryPath, outputTarget.absolutePath);
       return;
     }
     await link(temporaryPath, outputTarget.absolutePath);
@@ -30058,14 +30703,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" }
     );
   }
 }
@@ -30089,18 +30736,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) {
@@ -30129,23 +30787,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",
-      outputPath: absolutePath ?? path6.resolve(command.outputPath),
+      localState: {
+        destinationCommitted: false,
+        partialFileRetained: false
+      },
+      outputPath: absolutePath ?? path7.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;
 }
@@ -30222,8 +30968,8 @@ function canvasOneShotSetupError(kind, projectId, capability, error51) {
 }
 
 // src/commands/canvas.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
-import path7 from "node:path";
+import { randomUUID as randomUUID3 } from "node:crypto";
+import path8 from "node:path";
 
 // src/integrations/snapshot-reader.ts
 function createAz8StudioSnapshotReader(config2) {
@@ -31044,10 +31790,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path9) {
-  if (!path9)
+function getElementAtPath(obj, path10) {
+  if (!path10)
     return obj;
-  return path9.reduce((acc, key) => acc?.[key], obj);
+  return path10.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys2 = Object.keys(promisesObj);
@@ -31456,11 +32202,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path9, issues) {
+function prefixIssues(path10, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path9);
+    iss.path.unshift(path10);
     return iss;
   });
 }
@@ -31607,16 +32353,16 @@ function flattenError(error51, mapper = (issue2) => issue2.message) {
 }
 function formatError(error51, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error52, path9 = []) => {
+  const processError = (error52, path10 = []) => {
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path9, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path10, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path9, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path9, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
       } else {
-        const fullpath = [...path9, ...issue2.path];
+        const fullpath = [...path10, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -31643,17 +32389,17 @@ function formatError(error51, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error51, mapper = (issue2) => issue2.message) {
   const result3 = { errors: [] };
-  const processError = (error52, path9 = []) => {
+  const processError = (error52, path10 = []) => {
     var _a3, _b;
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path9, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path10, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path9, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path9, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
       } else {
-        const fullpath = [...path9, ...issue2.path];
+        const fullpath = [...path10, ...issue2.path];
         if (fullpath.length === 0) {
           result3.errors.push(mapper(issue2));
           continue;
@@ -31685,8 +32431,8 @@ function treeifyError(error51, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path9 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path9) {
+  const path10 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path10) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -44378,13 +45124,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path9 = ref.slice(1).split("/").filter(Boolean);
-  if (path9.length === 0) {
+  const path10 = ref.slice(1).split("/").filter(Boolean);
+  if (path10.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path9[0] === defsKey) {
-    const key = path9[1];
+  if (path10[0] === defsKey) {
+    const key = path10[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -44954,7 +45700,7 @@ function registerCanvasCommands(program2, dependencies, setResult) {
         return "invalid-option";
       });
       const config2 = await resolveCliConfig(readConfigOptions(command), dependencies);
-      const requestId = options.requestId ?? dependencies.randomUUID?.() ?? randomUUID2();
+      const requestId = options.requestId ?? dependencies.randomUUID?.() ?? randomUUID3();
       const result3 = await runCanvasOneShot(
         config2,
         {
@@ -44963,7 +45709,7 @@ function registerCanvasCommands(program2, dependencies, setResult) {
             idempotencyKey: options.idempotencyKey,
             ...options.name ? { name: options.name } : {},
             ...options.positionX !== void 0 && options.positionY !== void 0 ? { position: { x: options.positionX, y: options.positionY } } : {},
-            source: path7.resolve(dependencies.cwd ?? process.cwd(), options.file)
+            source: path8.resolve(dependencies.cwd ?? process.cwd(), options.file)
           },
           kind: "operation",
           name: "uploadMedia",
@@ -45039,7 +45785,7 @@ function registerCanvasCommands(program2, dependencies, setResult) {
           (issue2) => issue2.path[0] === "input" ? "invalid-input-source" : "invalid-option"
         );
         const config2 = await resolveCliConfig(readConfigOptions(command), dependencies);
-        const requestId = options.requestId ?? dependencies.randomUUID?.() ?? randomUUID2();
+        const requestId = options.requestId ?? dependencies.randomUUID?.() ?? randomUUID3();
         const result3 = await runCanvasOneShot(
           config2,
           {
@@ -45064,7 +45810,7 @@ function registerCanvasCommands(program2, dependencies, setResult) {
 // package.json
 var package_default = {
   name: "@everfir/az8-cli",
-  version: "0.3.0-preview.2",
+  version: "0.3.0",
   description: "Semantic Project Canvas client for AZ8 Studio agents.",
   license: "UNLICENSED",
   type: "module",
@@ -45080,7 +45826,7 @@ var package_default = {
   main: "./dist/main.js",
   publishConfig: {
     access: "public",
-    tag: "preview"
+    tag: "latest"
   },
   scripts: {
     build: `pnpm build:dependencies && rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node22.12 --banner:js='import { createRequire } from "node:module"; const require = createRequire(import.meta.url);' --outfile=dist/main.js`,
@@ -45131,7 +45877,7 @@ function readAz8CliVersion() {
 }
 
 // src/guide/agent-guide.ts
-import { readFile as readFile4 } from "node:fs/promises";
+import { readFile as readFile5 } from "node:fs/promises";
 var AGENT_GUIDE_URLS = [
   new URL("../skills/az8-cli/SKILL.md", import.meta.url),
   new URL("../../skills/az8-cli/SKILL.md", import.meta.url)
@@ -45164,7 +45910,7 @@ async function renderAgentGuide(options) {
 async function readPackagedGuide() {
   for (const candidate of AGENT_GUIDE_URLS) {
     try {
-      return await readFile4(candidate, "utf8");
+      return await readFile5(candidate, "utf8");
     } catch (error51) {
       if (error51.code !== "ENOENT") throw error51;
     }
@@ -45276,11 +46022,11 @@ async function withProjectClient(command, dependencies, setResult, action) {
 }
 
 // src/commands/session.ts
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 
 // src/agent-session/manager.ts
 import { spawn } from "node:child_process";
-import path8 from "node:path";
+import path9 from "node:path";
 var AgentSessionManager = class {
   constructor(options = {}) {
     this.options = options;
@@ -45308,7 +46054,7 @@ var AgentSessionManager = class {
     const descriptorPath = this.store.descriptorPath(sessionId);
     const config2 = {
       ...input.config,
-      ...input.config.envFile ? { envFile: path8.resolve(this.store.cwd, input.config.envFile) } : {}
+      ...input.config.envFile ? { envFile: path9.resolve(this.store.cwd, input.config.envFile) } : {}
     };
     const descriptor2 = {
       clientName,
@@ -45427,7 +46173,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(
@@ -45786,7 +46533,7 @@ function registerSessionCommands(program2, dependencies, setResult) {
         ...recordOptions(rawOptions),
         session: readSessionOption(command)
       });
-      const requestId = options.requestId ?? dependencies.randomUUID?.() ?? randomUUID3();
+      const requestId = options.requestId ?? dependencies.randomUUID?.() ?? randomUUID4();
       const { descriptor: descriptor2, value } = await manager.call(
         {
           input: await readCanvasOneShotInputOptions(options, dependencies),
@@ -45795,7 +46542,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;
@@ -45862,7 +46613,7 @@ function publicDescriptor(descriptor2) {
   };
 }
 function requireWatchDelivery(value) {
-  if (!("result" in value) || !isRecord5(value.result)) {
+  if (!("result" in value) || !isRecord6(value.result)) {
     throw new Error("Agent Session returned an invalid Watch delivery.");
   }
   return value;
@@ -45877,7 +46628,7 @@ function readCanvasSummary(value) {
   return "canvas" in value ? value.canvas : value;
 }
 function readOperationReceipt(value) {
-  if (!("receipt" in value) || !isRecord5(value.receipt)) {
+  if (!("receipt" in value) || !isRecord6(value.receipt)) {
     throw new Error("Agent Session returned an invalid Operation Receipt.");
   }
   return value.receipt;
@@ -45900,11 +46651,11 @@ function sessionError(error51) {
 `
   };
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function recordOptions(value) {
-  return isRecord5(value) ? value : {};
+  return isRecord6(value) ? value : {};
 }
 
 // src/cli/program.ts
@@ -45999,6 +46750,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
   });