@amaster.ai/employee-runtime-connector 0.1.0-beta.11 → 0.1.0-beta.12

package/dist/amaster-runtime-daemon.mjs

@@ -2335,7 +2335,7 @@ import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync
 import { homedir, hostname } from "node:os";
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
-const CONNECTOR_VERSION = "0.1.0-beta.11";
+const CONNECTOR_VERSION = "0.1.0-beta.12";
 const MAX_INFERRED_ARTIFACT_UPLOADS = 20;
 const MAX_CHECKPOINT_BYTES = 20 * 1024 * 1024;
 const CHECKPOINT_TTL_MS = 24 * 60 * 60 * 1000;
@@ -3556,6 +3556,8 @@ function runtimeActionsInstruction(options = {}) {
     authorizationOptionIdGuidance,
     "This capability guidance is rendered from the same authorization envelope enforced by runtime preflight. Preflight remains the final authority. task_governance covers comments, parent status, backlog children, artifacts, and interactions; organization_mutation covers agent_hire/create_agent; executable_child covers todo/in_progress child creation.",
     "Choose exactly one mutation path for each requested action: direct AMaster API or the runtime action bridge. Never replay the same mutation through both paths.",
+    "Source-truth contract: every externally derived factual or numeric claim in a comment, document, or artifact must include the source title, publication or retrieval date, and URL or durable source identifier next to the claim. A generic source family such as 'industry reports' or 'public data' is not evidence. If the source cannot be accessed or identified, label the claim as unverified or an assumption, name the verification owner and next action, and do not describe the deliverable or issue as verified or complete on the strength of that claim.",
+    "Every Markdown upload must declare sourceTruth either on its top-level deliverables[] entry or on the explicit upload_artifact action. Use status verified, mixed, unverified, or not_applicable. Verified sources require marker, title, an exact YYYY-MM-DD publication/retrieval date, and url or sourceId; put the marker as [SRC-1] next to the claim and repeat the title, date, and URL/source ID in the file. A generic site homepage is not a durable source URL: use the exact report/page URL. A sourceId must be a stable namespace:value identifier without spaces, such as doi:10.1000/example or report:vendor-report-2026-01; descriptive phrases such as 'industry reports' or 'official materials' are not source IDs. Unverified claims require marker, claim, owner, and nextAction; put [ASSUMPTION-1] next to the claim and repeat those fields in the file. Use not_applicable only when the document contains no externally derived factual or numeric claim, and provide a reason. Omitting deliverables[] does not bypass this preflight.",
     "If direct AMaster API requests succeed for all requested mutations, finish with a normal summary and do not emit or mention the AMASTER_RUNTIME_ACTIONS marker.",
     "If direct AMaster API requests are unavailable from the executor sandbox, do not stop at blocked. Use the runtime action bridge for the unapplied mutations.",
     "Use runtime actions as a continuation patch, not as a full replay. If the wake reason or latest comments say a confirmation was accepted, rejected, or that no more child tasks/interactions should be created, do not recreate those earlier actions. Add the final result comment and update the parent task instead.",
@@ -3596,11 +3598,11 @@ function runtimeActionsInstruction(options = {}) {
     "The runtime action block must be strict JSON parseable by JSON.parse. Do not use ellipses, placeholders such as [...], comments, trailing commas, single quotes, markdown tables outside quoted strings, or raw double quotes inside string values. Escape quotes and newlines in string values, or generate the block with JSON.stringify / @amaster/runtime-sdk before including it in the final assistant message.",
     "Before final output, validate the runtime action block with JSON.parse. If it would fail, fix the JSON and only then include AMASTER_RUNTIME_ACTIONS in the final assistant message.",
     actionValidatorCommand
-      ? `Before final output, write only the JSON envelope to .amaster-runtime-actions.json and run this exact strict-schema validator: ${actionValidatorCommand}. Fix every reported error and rerun until it exits 0. JSON.parse alone is not sufficient. Do not include the marker in the temporary file.`
+      ? `Before final output, write only the JSON envelope to .amaster-runtime-actions.json and run this exact strict-schema validator: ${actionValidatorCommand}. Fix every reported error and rerun until it exits 0. JSON.parse alone is not sufficient. Do not include the marker in the temporary file. After it passes, copy the validated file bytes exactly into the fenced final action block; do not retype, reformat, add, or remove any brace. Any post-validation edit invalidates the validation and requires another validator run.`
       : "",
     `Allowed action types: ${allowedActionTypes}.`,
-    "For upsert_document, write or replace a Markdown document on the current AMaster task. Use {\"type\":\"upsert_document\",\"key\":\"business-brief\",\"title\":\"2026-07-16 每日经营简报\",\"body\":\"# 每日经营简报\\n...\",\"format\":\"markdown\",\"changeSummary\":\"生成每日经营简报\"}. key, body, and format are required; format must be markdown. Never target a different issue.",
-    "For every create_interaction action, set top-level kind to the interaction kind and set payload to a JSON object. Use this complete canonical request_confirmation example: {\"type\":\"create_interaction\",\"kind\":\"request_confirmation\",\"continuationPolicy\":\"wake_assignee_on_accept\",\"payload\":{\"version\":1,\"prompt\":\"Confirm this result?\",\"acceptLabel\":\"确认\",\"rejectLabel\":\"调整\",\"target\":{\"type\":\"custom\",\"key\":\"delivery-review\",\"label\":\"交付结果\",\"revisionId\":\"v1\"}}}. Never use interactionType.",
+    "For upsert_document, write or replace a Markdown document on the current AMaster task. Use {\"type\":\"upsert_document\",\"key\":\"business-brief\",\"title\":\"2026-07-16 每日经营简报\",\"body\":\"# 每日经营简报\\n...\",\"format\":\"markdown\",\"changeSummary\":\"生成每日经营简报\"}. key, body, and format are required; format must be markdown. Never target a different issue. Omit baseRevisionId unless the current task context provides the exact revision; the connector resolves the latest revision before applying any batch mutations.",
+    "For every create_interaction action, set top-level kind to the interaction kind and set payload to a JSON object. Use this complete canonical request_confirmation example: {\"type\":\"create_interaction\",\"kind\":\"request_confirmation\",\"continuationPolicy\":\"wake_assignee\",\"payload\":{\"version\":1,\"prompt\":\"Confirm this result?\",\"acceptLabel\":\"确认\",\"rejectLabel\":\"调整\",\"target\":{\"type\":\"custom\",\"key\":\"delivery-review\",\"label\":\"交付结果\",\"revisionId\":\"v1\"}}}. Use wake_assignee when rejection means revise the work; use wake_assignee_on_accept only when rejection intentionally ends the execution path. Never use interactionType.",
     "Interactions cannot be updated with PATCH after creation. For direct API calls, include continuationPolicy in the initial POST /api/issues/{issueId}/interactions request and use only the documented POST accept, reject, respond, or cancel resolution endpoint afterward.",
     "For create_interaction ask_user_questions, use continuationPolicy wake_assignee, never wake_assignee_on_accept, because answering questions does not produce accepted status. Every question requires 1-10 options; do not emit an open-text question without options. The UI provides an Other text answer alongside the declared options. Use payload {\"version\":1,\"title\":\"...\",\"questions\":[{\"id\":\"question_key\",\"prompt\":\"Question text\",\"selectionMode\":\"single\",\"required\":true,\"options\":[{\"id\":\"option_key\",\"label\":\"Option label\"}]}]}. Do not use question/options.value at the top level.",
     "For create_interaction request_confirmation, follow the complete example above and do not use options arrays.",
@@ -3916,7 +3918,7 @@ function buildCommandPrompt(command, workspace, materializedAttachments = [], op
   // Built-in executors run on the connector host, so the prompt may reference these host paths.
   // A custom wrapper may isolate model tools; until isolation is an explicit capability, this
   // validator is same-host only and must fail visibly rather than fall back to a weaker check.
-  const actionValidatorCommand = `${quoteShell(process.execPath)} ${quoteShell(resolve(process.argv[1]))} validate-actions --file .amaster-runtime-actions.json --cwd . --allowed-content-types ${quoteShell(validatorContentTypes.join(","))}`;
+  const actionValidatorCommand = `${quoteShell(process.execPath)} ${quoteShell(resolve(process.argv[1]))} validate-actions --file .amaster-runtime-actions.json --cwd . --allowed-content-types ${quoteShell(validatorContentTypes.join(","))} --require-source-truth true`;
   return [
     "## AMaster Runtime Connector Task",
     "",
@@ -3961,6 +3963,10 @@ function buildCommandPrompt(command, workspace, materializedAttachments = [], op
           `path: ${attachmentPath}`,
           attachment.contentType ? `contentType: ${attachment.contentType}` : "",
           attachment.byteSize ? `bytes: ${attachment.byteSize}` : "",
+          attachment.workProductId ? `workProductId: ${attachment.workProductId}` : "",
+          attachment.evidenceRole ? `evidenceRole: ${attachment.evidenceRole}` : "",
+          Array.isArray(attachment.scenarioKeys) ? `scenarioKeys: ${JSON.stringify(attachment.scenarioKeys)}` : "",
+          attachment.sha256 ? `sha256: ${attachment.sha256}` : "",
         ].filter(Boolean).join(" | ");
         return `- ${details}`;
       }),
@@ -5511,15 +5517,25 @@ function completedChildIssueForRuntimeAction(action, actionContext) {
   return normalizedTitle ? completedByTitle.get(normalizedTitle) ?? null : null;
 }
 
-function runtimeActionExecutionPriority(action) {
+function runtimeActionExecutionPriority(action, options = {}) {
   const fields = runtimeActionBusinessFields(asRecord(action));
   const type = readRuntimeActionType(fields);
-  return type === "update_parent" ? 10 : 0;
+  if (type !== "update_parent") return 0;
+  // A same-batch blocking child makes the parent ineligible for a later
+  // in_progress transition. Preserve the requested transition before those
+  // blocker relations exist; terminal/review dispositions still run last so
+  // they can account for every governance mutation created by the batch.
+  return readActionStatus(fields.status) === "in_progress" && options.createdReviewPath !== true ? -10 : 10;
 }
 
 function orderRuntimeActionsForGovernance(actions) {
+  const createdReviewPath = actions.some(willRuntimeActionCreateReviewPath);
   return actions
-    .map((action, index) => ({ action, index, priority: runtimeActionExecutionPriority(action) }))
+    .map((action, index) => ({
+      action,
+      index,
+      priority: runtimeActionExecutionPriority(action, { createdReviewPath }),
+    }))
     .sort((left, right) => left.priority - right.priority || left.index - right.index)
     .map((entry) => entry.action);
 }
@@ -5728,6 +5744,113 @@ function safeMaterializedAttachmentFilename(attachment, index) {
   return name && name !== "." && name !== ".." ? name : `${id}.bin`;
 }
 
+function compareAttachmentLineageCandidates(left, right) {
+  // Do not depend on API array order: prefer explicit current lineage, then primary,
+  // then the newest update, with the UUID as a stable final tie-breaker.
+  const versionDiff = Number(right.artifactVersionState === "current")
+    - Number(left.artifactVersionState === "current");
+  if (versionDiff !== 0) return versionDiff;
+  const primaryDiff = Number(right.isPrimary) - Number(left.isPrimary);
+  if (primaryDiff !== 0) return primaryDiff;
+  const updatedAtDiff = right.updatedAtMs - left.updatedAtMs;
+  if (updatedAtDiff !== 0) return updatedAtDiff;
+  return left.workProductId.localeCompare(right.workProductId);
+}
+
+async function loadIssueAttachmentLineageCandidates(config, command, runtimeAuth, issueId) {
+  let workProducts;
+  try {
+    workProducts = await runtimeApiJson(
+      runtimeAuth,
+      "GET",
+      `/api/issues/${encodeURIComponent(issueId)}/work-products`,
+    );
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    const details = asRecord(err);
+    await ingestLog(
+      config,
+      command,
+      "system",
+      "warn",
+      "Issue attachment lineage unavailable; materializing attachments without work-product metadata",
+      {
+        issueId,
+        reason: "request_failed",
+        error: truncateText(error.message, 1000),
+        httpStatus: readNumber(details.httpStatus, null),
+        httpMethod: readString(details.httpMethod),
+        httpPath: readString(details.httpPath),
+      },
+    );
+    return new Map();
+  }
+
+  if (!Array.isArray(workProducts)) {
+    await ingestLog(
+      config,
+      command,
+      "system",
+      "warn",
+      "Issue attachment lineage unavailable; materializing attachments without work-product metadata",
+      { issueId, reason: "invalid_response_shape", responseType: workProducts === null ? "null" : typeof workProducts },
+    );
+    return new Map();
+  }
+
+  const candidatesByAttachmentId = new Map();
+  for (const rawWorkProduct of workProducts) {
+    const workProduct = asRecord(rawWorkProduct);
+    // Canonical keys: attachmentId/sha256 plus artifactVersionState/evidenceRole/scenarioKeys in packages/shared/src/validators/work-product.ts.
+    const metadata = asRecord(workProduct.metadata);
+    const attachmentId = readString(metadata.attachmentId);
+    const workProductId = readString(workProduct.id);
+    const artifactVersionState = readString(metadata.artifactVersionState);
+    if (
+      !attachmentId
+      || !workProductId
+      || readString(workProduct.type) !== "artifact"
+      || readString(workProduct.status) === "archived"
+      || artifactVersionState === "superseded"
+    ) {
+      continue;
+    }
+    const updatedAt = readString(workProduct.updatedAt);
+    const updatedAtMs = updatedAt ? Date.parse(updatedAt) : 0;
+    const candidate = {
+      workProductId,
+      evidenceRole: readString(metadata.evidenceRole),
+      scenarioKeys: Array.isArray(metadata.scenarioKeys)
+        ? metadata.scenarioKeys.map(readString).filter(Boolean)
+        : null,
+      declaredSha256: readString(metadata.sha256)?.toLowerCase() ?? null,
+      artifactVersionState,
+      isPrimary: workProduct.isPrimary === true,
+      updatedAtMs: Number.isFinite(updatedAtMs) ? updatedAtMs : 0,
+    };
+    const candidates = candidatesByAttachmentId.get(attachmentId) ?? [];
+    candidates.push(candidate);
+    candidatesByAttachmentId.set(attachmentId, candidates);
+  }
+  for (const candidates of candidatesByAttachmentId.values()) {
+    candidates.sort(compareAttachmentLineageCandidates);
+  }
+  return candidatesByAttachmentId;
+}
+
+function selectAttachmentLineage(candidates, actualSha256) {
+  if (!Array.isArray(candidates) || candidates.length === 0) return null;
+  const selected = candidates.find((candidate) => candidate.declaredSha256 === actualSha256)
+    ?? candidates.find((candidate) => candidate.declaredSha256 === null)
+    ?? null;
+  if (!selected) return null;
+  return {
+    workProductId: selected.workProductId,
+    evidenceRole: selected.evidenceRole,
+    scenarioKeys: selected.scenarioKeys,
+  };
+}
+
 async function materializeIssueAttachments(config, command, workspace) {
   const runtimeAuth = commandRuntimeAuth(command);
   const issueId = commandIssueId(command);
@@ -5735,6 +5858,12 @@ async function materializeIssueAttachments(config, command, workspace) {
 
   const attachments = await runtimeApiJson(runtimeAuth, "GET", `/api/issues/${encodeURIComponent(issueId)}/attachments`);
   if (!Array.isArray(attachments) || attachments.length === 0) return [];
+  const lineageCandidatesByAttachmentId = await loadIssueAttachmentLineageCandidates(
+    config,
+    command,
+    runtimeAuth,
+    issueId,
+  );
 
   const targetDir = join(workspace.cwd, "input-attachments");
   mkdirSync(targetDir, { recursive: true });
@@ -5757,14 +5886,36 @@ async function materializeIssueAttachments(config, command, workspace) {
     const targetPath = join(targetDir, filename);
     const body = await runtimeApiBuffer(runtimeAuth, contentPath);
     writeFileSync(targetPath, body);
+    const attachmentId = readString(attachment.id);
+    const actualSha256 = createHash("sha256").update(body).digest("hex");
+    const lineageCandidates = lineageCandidatesByAttachmentId.get(attachmentId) ?? [];
+    const lineage = selectAttachmentLineage(lineageCandidates, actualSha256);
+    if (lineageCandidates.length > 0 && !lineage) {
+      await ingestLog(
+        config,
+        command,
+        "system",
+        "warn",
+        "Issue attachment lineage SHA mismatch; omitting work-product metadata",
+        {
+          issueId,
+          attachmentId,
+          actualSha256,
+          declaredSha256: lineageCandidates.map((candidate) => candidate.declaredSha256).filter(Boolean),
+          workProductIds: lineageCandidates.map((candidate) => candidate.workProductId),
+        },
+      );
+    }
     materialized.push({
-      id: readString(attachment.id),
+      id: attachmentId,
       name: readString(attachment.originalFilename) ?? filename,
       path: targetPath,
       relativePath: relative(workspace.cwd, targetPath),
       contentType: readString(attachment.contentType),
       byteSize: body.byteLength,
       contentPath,
+      sha256: actualSha256,
+      ...(lineage ?? {}),
     });
   }
 
@@ -5777,6 +5928,10 @@ async function materializeIssueAttachments(config, command, workspace) {
         path: attachment.relativePath,
         contentType: attachment.contentType ?? null,
         byteSize: attachment.byteSize,
+        workProductId: attachment.workProductId ?? null,
+        evidenceRole: attachment.evidenceRole ?? null,
+        scenarioKeys: attachment.scenarioKeys ?? null,
+        sha256: attachment.sha256 ?? null,
       })),
     });
     await ingestLog(config, command, "system", "info", `Materialized ${materialized.length} issue attachment(s) into the execution workspace`, {
@@ -7094,7 +7249,7 @@ const RUNTIME_ACTION_ALLOWED_FIELDS = new Map([
     "path", "filePath", "artifactPath", "artifact_path", "title", "summary", "contentType",
     "createWorkProduct", "provider", "status", "reviewState", "isPrimary", "healthStatus",
     "sourceWorkProductId", "sourceWorkProductIds", "supersedesWorkProductId", "evidenceRole", "scenarioKeys",
-    "idempotencyKey", "upload_artifact",
+    "idempotencyKey", "sourceTruth", "upload_artifact",
   ])],
   ["upsert_document", new Set([
     "key", "title", "body", "format", "changeSummary", "baseRevisionId", "upsert_document",
@@ -7160,7 +7315,7 @@ const RUNTIME_ACTION_ARRAY_FIELDS = new Set([
 ]);
 const RUNTIME_ACTION_OBJECT_FIELDS = new Set([
   "adapterConfig", "instructionsBundle", "runtimeConfig", "permissions", "metadata", "target",
-  "interaction",
+  "interaction", "sourceTruth",
 ]);
 
 function assertRuntimeActionFieldTypes(action, actionIndex) {
@@ -7368,6 +7523,45 @@ function assertRuntimeCreateInteractionPayload(kind, payload) {
   }
 }
 
+function assertRuntimeConfirmationTarget(target) {
+  const record = asRecord(target);
+  const type = readString(record.type);
+  assertRuntimeActionValid(
+    ["custom", "issue_document"].includes(type ?? ""),
+    `confirmation payload target type is unsupported: ${String(record.type)}; use custom or issue_document`,
+  );
+  const key = readString(record.key);
+  const label = readString(record.label);
+  const href = readString(record.href);
+  const revisionId = readString(record.revisionId);
+  const revisionNumber = record.revisionNumber;
+  assertRuntimeActionValid(key, "confirmation payload target requires key");
+  assertRuntimeActionValid(!label || label.length <= 120, "confirmation payload target label must be at most 120 characters");
+  assertRuntimeActionValid(
+    !href || href.startsWith("#") || (href.startsWith("/") && !href.startsWith("//")) || /^https?:\/\//i.test(href),
+    "confirmation payload target href must be a root-relative path, same-page fragment, or http(s) URL",
+  );
+  assertRuntimeActionValid(
+    revisionNumber === undefined || revisionNumber === null || (Number.isInteger(revisionNumber) && revisionNumber > 0),
+    "confirmation payload target revisionNumber must be a positive integer",
+  );
+  if (type === "custom") {
+    assertRuntimeActionValid(key.length <= 120, "confirmation custom target key must be at most 120 characters");
+    assertRuntimeActionValid(!revisionId || revisionId.length <= 255, "confirmation custom target revisionId must be at most 255 characters");
+    return;
+  }
+  const uuidPattern = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+  assertRuntimeActionValid(
+    key.length <= 64 && /^[a-z0-9][a-z0-9_-]*$/.test(key),
+    "confirmation issue_document target key must use lowercase letters, numbers, _ or -",
+  );
+  assertRuntimeActionValid(revisionId && uuidPattern.test(revisionId), "confirmation issue_document target revisionId must be a UUID");
+  for (const field of ["issueId", "documentId"]) {
+    const value = readString(record[field]);
+    assertRuntimeActionValid(!value || uuidPattern.test(value), `confirmation issue_document target ${field} must be a UUID`);
+  }
+}
+
 function willRuntimeActionCreateReviewPath(action) {
   const fields = runtimeActionBusinessFields(action);
   const type = readRuntimeActionType(fields);
@@ -7572,7 +7766,8 @@ function preflightRuntimeAction(action, preflightContext, actionIndex) {
   }
   if (type === "upload_artifact") {
     assertNoPlaceholderRuntimeActionText(fields, ["path", "filePath", "artifactPath", "artifact_path", "title", "summary"]);
-    assertRuntimeActionValid(readRuntimeArtifactPath(fields), "upload_artifact action requires path");
+    const artifactPath = readRuntimeArtifactPath(fields);
+    assertRuntimeActionValid(artifactPath, "upload_artifact action requires path");
     const pathFields = ["path", "filePath", "artifactPath", "artifact_path"].filter((field) => readString(fields[field]));
     assertRuntimeActionValid(pathFields.length === 1, "upload_artifact action requires exactly one path field");
     const sourceWorkProductId = readString(fields.sourceWorkProductId);
@@ -7602,7 +7797,14 @@ function preflightRuntimeAction(action, preflightContext, actionIndex) {
       assertRuntimeActionValid(fields.scenarioKeys.map(readString).filter(Boolean).length === fields.scenarioKeys.length, "upload_artifact scenarioKeys must contain non-empty strings");
     }
     assertRuntimeArtifactContentType(fields, preflightContext.allowedContentTypes);
-    resolveWorkspaceArtifactPath(fields, { cwd: preflightContext.cwd });
+    const filePath = resolveWorkspaceArtifactPath(fields, { cwd: preflightContext.cwd });
+    if (preflightContext.requireSourceTruth && extname(filePath).toLowerCase() === ".md") {
+      assertRuntimeMarkdownSourceTruth(
+        fields.sourceTruth ?? preflightContext.sourceTruthByPath.get(filePath),
+        `actions[${actionIndex}].sourceTruth`,
+        filePath,
+      );
+    }
     return;
   }
   if (type === "upsert_document") {
@@ -7648,6 +7850,13 @@ function preflightRuntimeAction(action, preflightContext, actionIndex) {
         "accepted_confirmation_decision_target_required: an accepted confirmation continuation requires payload.target.type and a non-empty payload.target.key so the server can identify the decision; use a new target revision for genuinely changed content or finish the accepted work",
       );
     }
+    if (
+      ["request_confirmation", "request_checkbox_confirmation"].includes(kind) &&
+      payload.target !== undefined &&
+      payload.target !== null
+    ) {
+      assertRuntimeConfirmationTarget(payload.target);
+    }
     preflightContext.createdReviewPathForInReview = true;
     return;
   }
@@ -7705,6 +7914,22 @@ function preflightRuntimeActionBatch(actions, options = {}) {
   const actionIndexByObject = new Map(actions.map((action, index) => [action, index]));
   assertDelegatedParentWaitDisposition(actions);
   const orderedActions = orderRuntimeActionsByClientKeyDependencies(actions);
+  const documentActionIndexByKey = new Map();
+  for (const action of orderedActions) {
+    if (readRuntimeActionType(action) !== "upsert_document") continue;
+    const key = readBoundedActionString(runtimeActionBusinessFields(action), "key", 64);
+    if (!key) continue;
+    const actionIndex = actionIndexByObject.get(action);
+    if (documentActionIndexByKey.has(key)) {
+      const err = runtimeActionValidationError(
+        `upsert_document key ${key} appears more than once in the same runtime action batch`,
+      );
+      err.runtimeActionType = "upsert_document";
+      err.runtimeActionFieldPath = `actions[${actionIndex}].key`;
+      throw err;
+    }
+    documentActionIndexByKey.set(key, actionIndex);
+  }
   assertRuntimeActionsAllowedByContinuationScope(orderedActions, options.continuationScope);
   assertNoAmbiguousApprovalGatedSideEffects(orderedActions);
   const preflightContext = {
@@ -7715,6 +7940,8 @@ function preflightRuntimeActionBatch(actions, options = {}) {
     acceptedConfirmationContinuation: options.acceptedConfirmationContinuation === true,
     allowedContentTypes: Array.isArray(options.allowedContentTypes) ? options.allowedContentTypes : [],
     cwd: readString(options.cwd),
+    requireSourceTruth: options.requireSourceTruth === true,
+    sourceTruthByPath: options.sourceTruthByPath instanceof Map ? options.sourceTruthByPath : new Map(),
     finalCommentBodies: [],
   };
   for (const action of orderedActions) {
@@ -7754,6 +7981,56 @@ function preflightRuntimeActionBatch(actions, options = {}) {
   return orderedActions;
 }
 
+async function preflightRuntimeDocumentRevisions(runtimeAuth, issueId, actions) {
+  const baseRevisionIdsByKey = new Map();
+  for (const [actionIndex, action] of actions.entries()) {
+    if (readRuntimeActionType(action) !== "upsert_document") continue;
+    const fields = runtimeActionBusinessFields(action);
+    const key = readBoundedActionString(fields, "key", 64);
+    if (!key) continue;
+    let existingDocument = null;
+    try {
+      existingDocument = asRecord(await runtimeApiJson(
+        runtimeAuth,
+        "GET",
+        `/api/issues/${encodeURIComponent(issueId)}/documents/${encodeURIComponent(key)}`,
+      ));
+    } catch (err) {
+      if (err?.httpStatus !== 404) throw err;
+    }
+
+    const explicitBaseRevisionId = readString(fields.baseRevisionId);
+    const currentRevisionId = readString(existingDocument?.latestRevisionId);
+    if (existingDocument && !currentRevisionId) {
+      const err = runtimeActionValidationError(
+        `upsert_document ${key} exists but did not expose latestRevisionId`,
+      );
+      err.runtimeActionType = "upsert_document";
+      err.runtimeActionFieldPath = `actions[${actionIndex}].baseRevisionId`;
+      throw err;
+    }
+    if (!existingDocument && explicitBaseRevisionId) {
+      const err = runtimeActionValidationError(
+        `upsert_document ${key} supplied baseRevisionId but the document does not exist`,
+      );
+      err.runtimeActionType = "upsert_document";
+      err.runtimeActionFieldPath = `actions[${actionIndex}].baseRevisionId`;
+      throw err;
+    }
+    if (currentRevisionId && explicitBaseRevisionId && explicitBaseRevisionId !== currentRevisionId) {
+      const err = new Error(
+        `upsert_document ${key} baseRevisionId is stale; current revision is ${currentRevisionId}`,
+      );
+      err.httpStatus = 409;
+      err.runtimeActionType = "upsert_document";
+      err.runtimeActionFieldPath = `actions[${actionIndex}].baseRevisionId`;
+      throw err;
+    }
+    baseRevisionIdsByKey.set(key, currentRevisionId);
+  }
+  return baseRevisionIdsByKey;
+}
+
 function runtimeActionAuthorizationClass(action) {
   // Keep these high-risk route mappings aligned with server-side checks in
   // routes/agents.ts (organization_mutation) and routes/issues.ts
@@ -8161,7 +8438,7 @@ async function applyRuntimeAction(config, command, runtimeAuth, issueId, action,
     if (Object.keys(payload).length === 0) {
       throw new Error("create_interaction action requires payload");
     }
-    const defaultContinuationPolicy = kind === "request_confirmation" ? "wake_assignee_on_accept" : "wake_assignee";
+    const defaultContinuationPolicy = "wake_assignee";
     const createBody = {
       kind,
       continuationPolicy: readString(fields.continuationPolicy) ?? defaultContinuationPolicy,
@@ -8210,7 +8487,9 @@ async function applyRuntimeAction(config, command, runtimeAuth, issueId, action,
         format: "markdown",
         body,
         changeSummary: readBoundedActionString(fields, "changeSummary", 500) ?? null,
-        baseRevisionId: readString(fields.baseRevisionId) ?? null,
+        baseRevisionId: readString(fields.baseRevisionId)
+          ?? actionContext.documentBaseRevisionIdsByKey.get(key)
+          ?? null,
       },
     ));
     return {
@@ -9100,7 +9379,138 @@ function attachRuntimeCheckpointCandidates(err, envelope, cwd) {
   }
 }
 
-function preflightRuntimeDeliverables(config, envelope, cwd, allowedContentTypes) {
+function assertRuntimeMarkdownSourceTruth(sourceTruthValue, fieldPath, filePath) {
+  const sourceTruth = asRecord(sourceTruthValue);
+  if (Object.keys(sourceTruth).length === 0) {
+    throw runtimeDeliverableError(`${fieldPath} is required for Markdown deliverables`);
+  }
+  const allowedFields = new Set(["status", "reason", "sources", "unverifiedClaims"]);
+  for (const field of Object.keys(sourceTruth)) {
+    if (!allowedFields.has(field)) {
+      throw runtimeDeliverableError(`${fieldPath}.${field} is unsupported`);
+    }
+  }
+  const status = readString(sourceTruth.status);
+  if (!["verified", "mixed", "unverified", "not_applicable"].includes(status ?? "")) {
+    throw runtimeDeliverableError(`${fieldPath}.status must be verified, mixed, unverified, or not_applicable`);
+  }
+  const sources = Array.isArray(sourceTruth.sources) ? sourceTruth.sources : [];
+  const unverifiedClaims = Array.isArray(sourceTruth.unverifiedClaims) ? sourceTruth.unverifiedClaims : [];
+  if (sourceTruth.sources !== undefined && !Array.isArray(sourceTruth.sources)) {
+    throw runtimeDeliverableError(`${fieldPath}.sources must be an array`);
+  }
+  if (sourceTruth.unverifiedClaims !== undefined && !Array.isArray(sourceTruth.unverifiedClaims)) {
+    throw runtimeDeliverableError(`${fieldPath}.unverifiedClaims must be an array`);
+  }
+  if (sources.length > 100 || unverifiedClaims.length > 100) {
+    throw runtimeDeliverableError(`${fieldPath} exceeds the limit of 100 source records per category`);
+  }
+  if (status === "verified" && (sources.length === 0 || unverifiedClaims.length > 0)) {
+    throw runtimeDeliverableError(`${fieldPath} status verified requires sources and forbids unverifiedClaims`);
+  }
+  if (status === "mixed" && (sources.length === 0 || unverifiedClaims.length === 0)) {
+    throw runtimeDeliverableError(`${fieldPath} status mixed requires both sources and unverifiedClaims`);
+  }
+  if (status === "unverified" && (sources.length > 0 || unverifiedClaims.length === 0)) {
+    throw runtimeDeliverableError(`${fieldPath} status unverified requires unverifiedClaims and forbids sources`);
+  }
+
+  const content = readFileSync(filePath, "utf8");
+  const markdownSourceMarkers = new Set(
+    [...content.matchAll(/\[(SRC-[A-Z0-9_-]+)\]/gi)].map((match) => match[1]),
+  );
+  const markdownAssumptionMarkers = new Set(
+    [...content.matchAll(/\[(ASSUMPTION-[A-Z0-9_-]+)\]/gi)].map((match) => match[1]),
+  );
+  if (status === "not_applicable") {
+    if (sources.length > 0 || unverifiedClaims.length > 0 || !readString(sourceTruth.reason)) {
+      throw runtimeDeliverableError(`${fieldPath} status not_applicable requires reason and forbids source records`);
+    }
+    const sourceMarker = markdownSourceMarkers.values().next().value;
+    if (sourceMarker) {
+      throw runtimeDeliverableError(`Markdown marker ${sourceMarker} is missing from sourceTruth.sources`);
+    }
+    const assumptionMarker = markdownAssumptionMarkers.values().next().value;
+    if (assumptionMarker) {
+      throw runtimeDeliverableError(`Markdown marker ${assumptionMarker} is missing from sourceTruth.unverifiedClaims`);
+    }
+    return;
+  }
+
+  const markers = new Set();
+  const declaredSourceMarkers = new Set();
+  const declaredAssumptionMarkers = new Set();
+  for (const [sourceIndex, rawSource] of sources.entries()) {
+    const sourcePath = `${fieldPath}.sources[${sourceIndex}]`;
+    const source = asRecord(rawSource);
+    const marker = readString(source.marker);
+    const title = readString(source.title);
+    const date = readString(source.date);
+    const url = readString(source.url);
+    const sourceId = readString(source.sourceId);
+    if (!marker || !/^SRC-[A-Z0-9_-]+$/i.test(marker)) {
+      throw runtimeDeliverableError(`${sourcePath}.marker must use SRC-*`);
+    }
+    if (markers.has(marker)) throw runtimeDeliverableError(`${sourcePath}.marker must be unique`);
+    markers.add(marker);
+    declaredSourceMarkers.add(marker);
+    if (!title) throw runtimeDeliverableError(`${sourcePath}.title is required`);
+    if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+      throw runtimeDeliverableError(`${sourcePath}.date must be a valid YYYY-MM-DD date`);
+    }
+    const parsedDate = new Date(`${date}T00:00:00.000Z`);
+    if (Number.isNaN(parsedDate.getTime()) || parsedDate.toISOString().slice(0, 10) !== date) {
+      throw runtimeDeliverableError(`${sourcePath}.date must be a valid YYYY-MM-DD date`);
+    }
+    if (!url && !sourceId) throw runtimeDeliverableError(`${sourcePath} requires url or sourceId`);
+    if (url) {
+      if (!/^https?:\/\//i.test(url)) throw runtimeDeliverableError(`${sourcePath}.url must use http or https`);
+      if (/\s/.test(url)) throw runtimeDeliverableError(`${sourcePath}.url must be one exact URL without spaces`);
+      const parsedUrl = new URL(url);
+      if (parsedUrl.pathname === "/" && !parsedUrl.search && !parsedUrl.hash && !sourceId) {
+        throw runtimeDeliverableError(`${sourcePath}.url must identify a document or page, not only a site root`);
+      }
+    }
+    if (sourceId && !/^[a-z][a-z0-9._-]*:[a-z0-9][a-z0-9._/+:-]*$/i.test(sourceId)) {
+      throw runtimeDeliverableError(`${sourcePath}.sourceId must use a stable namespace:value identifier without spaces`);
+    }
+    for (const [label, value] of [["marker", `[${marker}]`], ["title", title], ["date", date], [url ? "url" : "sourceId", url ?? sourceId]]) {
+      if (!content.includes(value)) throw runtimeDeliverableError(`${sourcePath}.${label} must appear in the Markdown deliverable`);
+    }
+  }
+  for (const [claimIndex, rawClaim] of unverifiedClaims.entries()) {
+    const claimPath = `${fieldPath}.unverifiedClaims[${claimIndex}]`;
+    const claim = asRecord(rawClaim);
+    const marker = readString(claim.marker);
+    const claimText = readString(claim.claim);
+    const owner = readString(claim.owner);
+    const nextAction = readString(claim.nextAction);
+    if (!marker || !/^ASSUMPTION-[A-Z0-9_-]+$/i.test(marker)) {
+      throw runtimeDeliverableError(`${claimPath}.marker must use ASSUMPTION-*`);
+    }
+    if (markers.has(marker)) throw runtimeDeliverableError(`${claimPath}.marker must be unique`);
+    markers.add(marker);
+    declaredAssumptionMarkers.add(marker);
+    if (!claimText) throw runtimeDeliverableError(`${claimPath}.claim is required`);
+    if (!owner) throw runtimeDeliverableError(`${claimPath}.owner is required`);
+    if (!nextAction) throw runtimeDeliverableError(`${claimPath}.nextAction is required`);
+    for (const [label, value] of [["marker", `[${marker}]`], ["claim", claimText], ["owner", owner], ["nextAction", nextAction]]) {
+      if (!content.includes(value)) throw runtimeDeliverableError(`${claimPath}.${label} must appear in the Markdown deliverable`);
+    }
+  }
+  for (const marker of markdownSourceMarkers) {
+    if (!declaredSourceMarkers.has(marker)) {
+      throw runtimeDeliverableError(`Markdown marker ${marker} is missing from sourceTruth.sources`);
+    }
+  }
+  for (const marker of markdownAssumptionMarkers) {
+    if (!declaredAssumptionMarkers.has(marker)) {
+      throw runtimeDeliverableError(`Markdown marker ${marker} is missing from sourceTruth.unverifiedClaims`);
+    }
+  }
+}
+
+function preflightRuntimeDeliverables(config, envelope, cwd, allowedContentTypes, options = {}) {
   const rawDeliverables = Array.isArray(envelope.deliverables) ? envelope.deliverables : [];
   if (rawDeliverables.length > 20) {
     throw runtimeDeliverableError("deliverables manifest exceeds the limit of 20");
@@ -9137,7 +9547,15 @@ function preflightRuntimeDeliverables(config, envelope, cwd, allowedContentTypes
           runtimeActionAllowedContentTypes: err?.runtimeActionAllowedContentTypes,
         });
       }
+      if (options.requireSourceTruth === true && extname(filePath).toLowerCase() === ".md") {
+        assertRuntimeMarkdownSourceTruth(
+          deliverable.sourceTruth,
+          `deliverables[${index}].sourceTruth`,
+          filePath,
+        );
+      }
     }
+    normalized.sourceTruth = deliverable.sourceTruth;
     deliverables.push(normalized);
     if (deliverable.verification !== undefined) verifications.push(deliverable.verification);
   }
@@ -9203,7 +9621,9 @@ async function applyRuntimeActionBridge(config, command, parsed, execution, cwd)
   const allowedContentTypes = runtimeAttachmentContentTypes(command);
   let deliverableManifest;
   try {
-    deliverableManifest = preflightRuntimeDeliverables(config, envelope, cwd, allowedContentTypes);
+    deliverableManifest = preflightRuntimeDeliverables(config, envelope, cwd, allowedContentTypes, {
+      requireSourceTruth: true,
+    });
   } catch (err) {
     attachRuntimeCheckpointCandidates(err, envelope, cwd);
     throw err;
@@ -9211,11 +9631,12 @@ async function applyRuntimeActionBridge(config, command, parsed, execution, cwd)
   const explicitUploadPaths = new Set(rawActions
     .filter((action) => readRuntimeActionType(action) === "upload_artifact")
     .map((action) => readRuntimeArtifactPath(runtimeActionBusinessFields(action)))
-    .filter(Boolean));
+    .filter(Boolean)
+    .map((artifactPath) => realOrResolvedPath(resolve(cwd, expandHomePath(artifactPath)))));
   const hasExplicitPrimaryArtifact = rawActions.some((action) =>
     readRuntimeActionType(action) === "upload_artifact" && runtimeActionBusinessFields(action).isPrimary === true);
   const generatedUploadActions = deliverableManifest.deliverables
-    .filter((deliverable) => deliverable.required && !explicitUploadPaths.has(deliverable.rawPath))
+    .filter((deliverable) => deliverable.required && !explicitUploadPaths.has(deliverable.path))
     .map((deliverable, index) => ({
       type: "upload_artifact",
       path: deliverable.rawPath,
@@ -9234,6 +9655,7 @@ async function applyRuntimeActionBridge(config, command, parsed, execution, cwd)
   let actions = orderRuntimeActionsForGovernance([...generatedUploadActions, ...rawActions]);
   const answeredQuestionContinuation = runtimeActionAnsweredQuestionContinuation(command);
   const acceptedConfirmationContinuation = runtimeActionAcceptedConfirmationContinuation(command);
+  let documentBaseRevisionIdsByKey;
   try {
     actions = preflightRuntimeActionBatch(actions, {
       answeredQuestionContinuation,
@@ -9241,8 +9663,14 @@ async function applyRuntimeActionBridge(config, command, parsed, execution, cwd)
       allowedContentTypes,
       continuationScope,
       cwd,
+      requireSourceTruth: true,
+      sourceTruthByPath: new Map(deliverableManifest.deliverables.map((deliverable) => [
+        deliverable.path,
+        deliverable.sourceTruth,
+      ])),
     });
     assertRuntimeActionsAllowedByAuthorizationEnvelope(actions, authorizationEnvelope);
+    documentBaseRevisionIdsByKey = await preflightRuntimeDocumentRevisions(runtimeAuth, issueId, actions);
   } catch (err) {
     if (err && typeof err === "object" && !err.runtimeActionLedger) {
       const fieldPath = readString(err.runtimeActionFieldPath);
@@ -9277,6 +9705,7 @@ async function applyRuntimeActionBridge(config, command, parsed, execution, cwd)
     createdReviewPathForInReview: false,
     acceptedConfirmationContinuation,
     answeredQuestionContinuation,
+    documentBaseRevisionIdsByKey,
     finalCommentBodies: [],
   };
   for (const [actionIndex, action] of actions.entries()) {
@@ -9537,6 +9966,7 @@ async function applyInferredArtifactUploads(config, command, parsed, execution,
       .filter(Boolean)
       .map((entry) => resolve(cwd, entry)),
   );
+  // Refetch after execution: runtime actions may have created work products since input attachment lineage was loaded.
   const existingWorkProducts = await listExistingIssueWorkProducts(runtimeAuth, issueId);
   const inferenceText = [
     parsed.summary,
@@ -10134,9 +10564,20 @@ function validateRuntimeActionsFile(config, flags) {
   assertRuntimeActionValid(Array.isArray(envelope.actions), "runtime action envelope actions must be an array");
   assertRuntimeActionValid(envelope.actions.length <= 20, "runtime action envelope actions exceed the limit of 20");
 
-  preflightRuntimeDeliverables(config, envelope, cwd, allowedContentTypes);
+  const requireSourceTruth = flags["require-source-truth"] === "true";
+  const deliverableManifest = preflightRuntimeDeliverables(config, envelope, cwd, allowedContentTypes, {
+    requireSourceTruth,
+  });
   const actions = orderRuntimeActionsForGovernance(envelope.actions.map(asRecord));
-  preflightRuntimeActionBatch(actions, { cwd, allowedContentTypes });
+  preflightRuntimeActionBatch(actions, {
+    cwd,
+    allowedContentTypes,
+    requireSourceTruth,
+    sourceTruthByPath: new Map(deliverableManifest.deliverables.map((deliverable) => [
+      deliverable.path,
+      deliverable.sourceTruth,
+    ])),
+  });
   process.stdout.write(`${JSON.stringify({ valid: true, actionCount: actions.length }, null, 2)}\n`);
 }
 

package/dist/amaster-runtime.mjs

@@ -5,7 +5,7 @@ import { dirname, join, resolve } from "node:path";
 import { homedir, hostname } from "node:os";
 import { fileURLToPath } from "node:url";
 
-const CONNECTOR_VERSION = "0.1.0-beta.11";
+const CONNECTOR_VERSION = "0.1.0-beta.12";
 
 const CAPABILITIES = [
   "remote_registration",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/employee-runtime-connector",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.12",
   "description": "AMaster Employee runtime connector CLI and daemon",
   "license": "MIT",
   "type": "module",