blun-king-cli 9.1.567 → 9.1.569

package/agent-spine-plugin/src/lib/gateway-execution.js

@@ -0,0 +1,350 @@
+import {
+  EXECUTION_ATTEMPT_SCHEMA, EXECUTION_OUTCOME_SCHEMA, ID_RE, METRIC_OPERATORS,
+  STRATEGY_TRANSFER_PROOF_SCHEMA, exactId, sha256, timestamp
+} from "./gateway-common.js";
+
+function executionDecisionMaterial(execution) {
+  return {
+    requiredCapabilities: execution.requiredCapabilities, strategies: execution.strategies,
+    verification: execution.verification, selectedStrategyId: execution.selectedStrategyId,
+    ...(execution.explorationMaxAttempts === undefined ? {} : {
+      explorationMaxAttempts: execution.explorationMaxAttempts,
+      explorationOrder: execution.explorationOrder
+    }),
+    ...(execution.transferKey === undefined ? {} : {
+      transferKey: execution.transferKey, transferMaxAgeDays: execution.transferMaxAgeDays,
+      transferProof: execution.transferProof
+    }),
+    authority: "context-only-decision"
+  };
+}
+
+function sufficientExecutionStrategies(execution) {
+  const required = new Set(execution.requiredCapabilities);
+  return execution.strategies.filter((strategy) => strategy.capabilities.every((capability) => ID_RE.test(capability))
+    && [...required].every((capability) => strategy.capabilities.includes(capability)))
+    .sort((left, right) => left.risk - right.risk || left.cost - right.cost
+      || left.strategyId.localeCompare(right.strategyId));
+}
+
+function selectedExecutionStrategy(execution) {
+  const sufficient = sufficientExecutionStrategies(execution);
+  const minimumRisk = sufficient[0]?.risk;
+  const transferred = execution.transferProof && sufficient.find((strategy) =>
+    strategy.strategyId === execution.transferProof.strategyId && strategy.risk === minimumRisk);
+  return transferred || sufficient[0] || null;
+}
+
+function expectedExplorationOrder(execution) {
+  const sufficient = sufficientExecutionStrategies(execution);
+  const selected = selectedExecutionStrategy(execution);
+  if (!selected) return [];
+  return [selected, ...sufficient.filter((strategy) => strategy.risk === selected.risk
+    && strategy.strategyId !== selected.strategyId)].map((strategy) => strategy.strategyId);
+}
+
+function strategyTransferProofMaterial(proof) {
+  return {
+    transferKey: proof.transferKey, strategyId: proof.strategyId, maxAgeDays: proof.maxAgeDays,
+    evidence: proof.evidence, authority: "context-only-transfer"
+  };
+}
+
+function validStrategyTransferProof(proof) {
+  if (!(proof && proof.schema === STRATEGY_TRANSFER_PROOF_SCHEMA
+    && ID_RE.test(proof.proofId || "") && ID_RE.test(proof.transferKey || "")
+    && ID_RE.test(proof.strategyId || "") && Number.isInteger(proof.maxAgeDays)
+    && proof.maxAgeDays >= 1 && proof.maxAgeDays <= 90 && Array.isArray(proof.evidence)
+    && proof.evidence.length >= 2 && proof.evidence.length <= 8
+    && new Set(proof.evidence.map((item) => item.sourceGoalId)).size === proof.evidence.length
+    && new Set(proof.evidence.map((item) => item.sourceDigest)).size === proof.evidence.length
+    && proof.evidence.every((item) => item && ID_RE.test(item.sourceGoalId || "")
+      && ID_RE.test(item.sourceStepId || "") && ID_RE.test(item.outcomeId || "")
+      && /^[a-f0-9]{64}$/.test(item.outcomeDigest || "")
+      && /^[a-f0-9]{64}$/.test(item.sourceDigest || "")
+      && Number.isFinite(new Date(item.completedAt).getTime()))
+    && /^[a-f0-9]{64}$/.test(proof.proofDigest || "")
+    && proof.authority === "context-only-transfer")) return false;
+  const digest = sha256(JSON.stringify(strategyTransferProofMaterial(proof)));
+  return proof.proofDigest === digest && proof.proofId === "strategy-transfer:" + digest.slice(0, 32);
+}
+
+function sameStrategy(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function sameVerification(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function collectStrategyTransferEvidence(goals, execution, strategy, scope) {
+  if (!execution.transferKey) return { evidence: [], regressed: false };
+  const before = new Date(scope.before);
+  const cutoff = new Date(before.getTime() - execution.transferMaxAgeDays * 86400000);
+  const evidence = []; let regressed = false;
+  for (const goal of goals) {
+    if (goal.goalId === scope.goalId || goal.projectId !== scope.projectId || goal.groupId !== scope.groupId || !goal.plan) continue;
+    for (const step of goal.plan.steps) {
+      const prior = step.execution;
+      const completedAt = step.completedAt && new Date(step.completedAt);
+      const updatedAt = new Date(step.updatedAt);
+      if (!prior || prior.transferKey !== execution.transferKey
+        || !sameVerification(prior.verification, execution.verification)
+        || !sameStrategy(prior.strategies.find((item) => item.strategyId === strategy.strategyId), strategy)
+        || updatedAt > before) continue;
+      for (const outcome of step.executionOutcomes || []) {
+        if (outcome.strategyId !== strategy.strategyId) continue;
+        const observedAt = new Date(outcome.observedAt);
+        if (observedAt < cutoff || observedAt > before || observedAt < new Date(goal.createdAt)) continue;
+        if (!outcome.passed || outcome.blockingDefect) { regressed = true; continue; }
+        if (step.status !== "completed" || !completedAt || completedAt < cutoff || completedAt > before
+          || observedAt > completedAt) continue;
+        evidence.push({ sourceGoalId: goal.goalId, sourceStepId: step.stepId, outcomeId: outcome.outcomeId,
+          outcomeDigest: outcome.digest, sourceDigest: outcome.sourceDigest, completedAt: step.completedAt });
+      }
+    }
+  }
+  const unique = [];
+  for (const item of evidence.sort((left, right) => left.completedAt.localeCompare(right.completedAt)
+    || left.outcomeId.localeCompare(right.outcomeId))) {
+    if (!unique.some((entry) => entry.sourceGoalId === item.sourceGoalId || entry.sourceDigest === item.sourceDigest)) unique.push(item);
+  }
+  return { evidence: unique.slice(-8), regressed };
+}
+
+function createStrategyTransferProof(goals, execution, scope) {
+  if (!execution.transferKey) return null;
+  const required = new Set(execution.requiredCapabilities);
+  const sufficient = execution.strategies.filter((strategy) =>
+    [...required].every((capability) => strategy.capabilities.includes(capability)));
+  const minimumRisk = Math.min(...sufficient.map((strategy) => strategy.risk));
+  const proven = sufficient.filter((strategy) => strategy.risk === minimumRisk).map((strategy) => ({
+    strategy, ...collectStrategyTransferEvidence(goals, execution, strategy, scope)
+  })).filter((item) => !item.regressed && item.evidence.length >= 2)
+    .sort((left, right) => right.evidence.length - left.evidence.length
+      || left.strategy.cost - right.strategy.cost || left.strategy.strategyId.localeCompare(right.strategy.strategyId));
+  if (!proven.length) return null;
+  const proof = { schema: STRATEGY_TRANSFER_PROOF_SCHEMA, proofId: null,
+    transferKey: execution.transferKey, strategyId: proven[0].strategy.strategyId,
+    maxAgeDays: execution.transferMaxAgeDays, evidence: proven[0].evidence,
+    proofDigest: null, authority: "context-only-transfer" };
+  proof.proofDigest = sha256(JSON.stringify(strategyTransferProofMaterial(proof)));
+  proof.proofId = "strategy-transfer:" + proof.proofDigest.slice(0, 32);
+  return proof;
+}
+
+export function validGoalTransferProofs(goal, goals) {
+  if (!goal.plan) return true;
+  return goal.plan.steps.every((step) => {
+    if (!step.execution?.transferProof) return true;
+    const expected = createStrategyTransferProof(goals, step.execution, {
+      goalId: goal.goalId, projectId: goal.projectId, groupId: goal.groupId, before: goal.createdAt
+    });
+    return JSON.stringify(expected) === JSON.stringify(step.execution.transferProof);
+  });
+}
+
+export function validExecutionDecision(execution) {
+  if (!(execution && execution.authority === "context-only-decision"
+    && Array.isArray(execution.requiredCapabilities) && execution.requiredCapabilities.length > 0
+    && execution.requiredCapabilities.length <= 16
+    && new Set(execution.requiredCapabilities).size === execution.requiredCapabilities.length
+    && execution.requiredCapabilities.every((capability) => ID_RE.test(capability || ""))
+    && Array.isArray(execution.strategies) && execution.strategies.length >= 2 && execution.strategies.length <= 8
+    && new Set(execution.strategies.map((strategy) => strategy?.strategyId)).size === execution.strategies.length
+    && execution.strategies.every((strategy) => strategy && ID_RE.test(strategy.strategyId || "")
+      && Array.isArray(strategy.capabilities) && strategy.capabilities.length > 0 && strategy.capabilities.length <= 16
+      && new Set(strategy.capabilities).size === strategy.capabilities.length
+      && strategy.capabilities.every((capability) => ID_RE.test(capability || ""))
+      && Number.isInteger(strategy.risk) && strategy.risk >= 0 && strategy.risk <= 100
+      && Number.isInteger(strategy.cost) && strategy.cost >= 0 && strategy.cost <= 100)
+    && execution.verification && ID_RE.test(execution.verification.evaluatorId || "")
+    && ID_RE.test(execution.verification.metric || "") && METRIC_OPERATORS.has(execution.verification.operator)
+    && Number.isFinite(execution.verification.threshold)
+    && Number.isInteger(execution.verification.minCases) && execution.verification.minCases >= 1
+    && execution.verification.minCases <= 100000 && ID_RE.test(execution.selectedStrategyId || "")
+    && (execution.explorationMaxAttempts === undefined || (Number.isInteger(execution.explorationMaxAttempts)
+      && execution.explorationMaxAttempts >= 2 && execution.explorationMaxAttempts <= 4
+      && Array.isArray(execution.explorationOrder)
+      && execution.explorationOrder.length === execution.explorationMaxAttempts
+      && new Set(execution.explorationOrder).size === execution.explorationOrder.length
+      && execution.explorationOrder.every((strategyId) => ID_RE.test(strategyId || ""))))
+    && (execution.transferKey === undefined || (ID_RE.test(execution.transferKey || "")
+      && Number.isInteger(execution.transferMaxAgeDays) && execution.transferMaxAgeDays >= 1
+      && execution.transferMaxAgeDays <= 90
+      && (execution.transferProof === null || (validStrategyTransferProof(execution.transferProof)
+        && execution.transferProof.transferKey === execution.transferKey
+        && execution.transferProof.maxAgeDays === execution.transferMaxAgeDays))))
+    && /^[a-f0-9]{64}$/.test(execution.decisionDigest || ""))) return false;
+  const selected = selectedExecutionStrategy(execution);
+  return selected?.strategyId === execution.selectedStrategyId
+    && (execution.explorationMaxAttempts === undefined
+      || JSON.stringify(execution.explorationOrder)
+        === JSON.stringify(expectedExplorationOrder(execution).slice(0, execution.explorationMaxAttempts)))
+    && execution.decisionDigest === sha256(JSON.stringify(executionDecisionMaterial(execution)));
+}
+
+export function createExecutionDecision(value, field, transferContext) {
+  if (value === null || value === undefined) return null;
+  const execution = {
+    requiredCapabilities: Array.isArray(value.requiredCapabilities)
+      ? value.requiredCapabilities.map((capability) => exactId(capability, `${field}.requiredCapabilities`)) : [],
+    strategies: Array.isArray(value.strategies) ? value.strategies.map((strategy, index) => ({
+      strategyId: exactId(strategy?.strategyId, `${field}.strategies[${index}].strategyId`),
+      capabilities: Array.isArray(strategy?.capabilities)
+        ? strategy.capabilities.map((capability) => exactId(capability, `${field}.strategies[${index}].capabilities`)) : [],
+      risk: Number(strategy?.risk), cost: Number(strategy?.cost)
+    })) : [],
+    verification: {
+      evaluatorId: exactId(value.verification?.evaluatorId, `${field}.verification.evaluatorId`),
+      metric: exactId(value.verification?.metric, `${field}.verification.metric`),
+      operator: value.verification?.operator,
+      threshold: Number(value.verification?.threshold), minCases: Number(value.verification?.minCases)
+    },
+    selectedStrategyId: null, decisionDigest: null, authority: "context-only-decision"
+  };
+  if (value.transfer !== undefined && value.transfer !== null) {
+    execution.transferKey = exactId(value.transfer?.transferKey, `${field}.transfer.transferKey`);
+    execution.transferMaxAgeDays = Number(value.transfer?.maxAgeDays);
+    execution.transferProof = null;
+    execution.transferProof = createStrategyTransferProof(transferContext.goals, execution, transferContext.scope);
+  }
+  execution.selectedStrategyId = selectedExecutionStrategy(execution)?.strategyId || null;
+  if (value.exploration !== undefined && value.exploration !== null) {
+    execution.explorationMaxAttempts = Number(value.exploration?.maxAttempts);
+    execution.explorationOrder = expectedExplorationOrder(execution).slice(0, execution.explorationMaxAttempts);
+  }
+  execution.decisionDigest = sha256(JSON.stringify(executionDecisionMaterial(execution)));
+  if (!validExecutionDecision(execution)) {
+    throw new Error(`${field} requires 2-8 bounded strategies and one objective verification gate`);
+  }
+  return execution;
+}
+
+function executionOutcomeMaterial(outcome) {
+  return {
+    queueId: outcome.queueId, decisionDigest: outcome.decisionDigest, strategyId: outcome.strategyId,
+    ...(outcome.attempt === undefined ? {} : {
+      attempt: outcome.attempt, previousOutcomeDigest: outcome.previousOutcomeDigest
+    }),
+    capabilitiesUsed: outcome.capabilitiesUsed, evaluatorId: outcome.evaluatorId, metric: outcome.metric,
+    value: outcome.value, cases: outcome.cases, blockingDefect: outcome.blockingDefect,
+    sourceDigest: outcome.sourceDigest, observedAt: outcome.observedAt, passed: outcome.passed,
+    authority: "objective-evidence-only"
+  };
+}
+
+export function currentExecutionAttempt(execution, outcomes = []) {
+  if (execution.explorationMaxAttempts === undefined) return null;
+  if (outcomes.length >= execution.explorationMaxAttempts || outcomes.some((outcome) => outcome.passed || outcome.blockingDefect)) {
+    return null;
+  }
+  return {
+    schema: EXECUTION_ATTEMPT_SCHEMA,
+    attempt: outcomes.length + 1, maxAttempts: execution.explorationMaxAttempts,
+    strategyId: execution.explorationOrder[outcomes.length],
+    previousOutcomeDigest: outcomes.at(-1)?.digest || null,
+    decisionDigest: execution.decisionDigest, authority: "context-only-attempt"
+  };
+}
+
+export function executionAttemptForStep(step) {
+  if (!step?.execution || !Array.isArray(step.executionOutcomes)) return null;
+  return currentExecutionAttempt(step.execution, step.executionOutcomes);
+}
+
+function metricPassed(operator, value, threshold) {
+  if (operator === "gte") return value >= threshold;
+  if (operator === "lte") return value <= threshold;
+  return value === threshold;
+}
+
+function validExecutionOutcome(outcome, execution, expectedStrategyId = execution.selectedStrategyId,
+  expectedAttempt = null, previousOutcomeDigest = null) {
+  if (!(outcome && outcome.schema === EXECUTION_OUTCOME_SCHEMA && ID_RE.test(outcome.outcomeId || "")
+    && ID_RE.test(outcome.queueId || "") && outcome.decisionDigest === execution.decisionDigest
+    && outcome.strategyId === expectedStrategyId
+    && (execution.explorationMaxAttempts === undefined
+      ? outcome.attempt === undefined && outcome.previousOutcomeDigest === undefined
+      : outcome.attempt === expectedAttempt && outcome.previousOutcomeDigest === previousOutcomeDigest)
+    && Array.isArray(outcome.capabilitiesUsed)
+    && outcome.capabilitiesUsed.length <= 16 && new Set(outcome.capabilitiesUsed).size === outcome.capabilitiesUsed.length
+    && outcome.capabilitiesUsed.every((capability) => ID_RE.test(capability || ""))
+    && outcome.evaluatorId === execution.verification.evaluatorId && outcome.metric === execution.verification.metric
+    && Number.isFinite(outcome.value) && Number.isInteger(outcome.cases) && outcome.cases >= 0
+    && typeof outcome.blockingDefect === "boolean" && /^[a-f0-9]{64}$/.test(outcome.sourceDigest || "")
+    && Number.isFinite(new Date(outcome.observedAt).getTime()) && typeof outcome.passed === "boolean"
+    && /^[a-f0-9]{64}$/.test(outcome.digest || "") && outcome.authority === "objective-evidence-only")) return false;
+  const strategy = execution.strategies.find((item) => item.strategyId === expectedStrategyId);
+  const used = new Set(outcome.capabilitiesUsed);
+  const expectedPass = execution.requiredCapabilities.every((capability) => used.has(capability))
+    && outcome.capabilitiesUsed.every((capability) => strategy.capabilities.includes(capability))
+    && outcome.cases >= execution.verification.minCases && !outcome.blockingDefect
+    && metricPassed(execution.verification.operator, outcome.value, execution.verification.threshold);
+  const digest = sha256(JSON.stringify(executionOutcomeMaterial(outcome)));
+  return outcome.passed === expectedPass && outcome.digest === digest
+    && outcome.outcomeId === "execution-outcome:" + digest.slice(0, 32);
+}
+
+export function validExecutionOutcomeSequence(execution, outcomes) {
+  if (execution.explorationMaxAttempts === undefined) {
+    return outcomes.every((outcome) => validExecutionOutcome(outcome, execution));
+  }
+  if (outcomes.length > execution.explorationMaxAttempts
+    || new Set(outcomes.map((outcome) => outcome.sourceDigest)).size !== outcomes.length) return false;
+  let previous = null;
+  for (let index = 0; index < outcomes.length; index += 1) {
+    const outcome = outcomes[index];
+    if (!validExecutionOutcome(outcome, execution, execution.explorationOrder[index], index + 1, previous)) return false;
+    if (index < outcomes.length - 1 && (outcome.passed || outcome.blockingDefect)) return false;
+    previous = outcome.digest;
+  }
+  return true;
+}
+
+export function reviewExecutionResult(execution, priorOutcomes, queueId, report, now) {
+  const attempt = currentExecutionAttempt(execution, priorOutcomes);
+  const expectedStrategyId = attempt?.strategyId || execution.selectedStrategyId;
+  if (!report || report.strategyId !== expectedStrategyId || !Array.isArray(report.capabilitiesUsed)
+    || !report.outcome || report.outcome.evaluatorId !== execution.verification.evaluatorId
+    || report.outcome.metric !== execution.verification.metric) {
+    return { passed: false, outcome: null, reason: "Objective execution evidence is missing or invalid." };
+  }
+  let outcome;
+  try {
+    outcome = {
+      schema: EXECUTION_OUTCOME_SCHEMA, outcomeId: null, queueId,
+      decisionDigest: execution.decisionDigest, strategyId: report.strategyId,
+      ...(attempt === null ? {} : { attempt: attempt.attempt, previousOutcomeDigest: attempt.previousOutcomeDigest }),
+      capabilitiesUsed: report.capabilitiesUsed.map((capability) => exactId(capability, "execution.capabilitiesUsed")),
+      evaluatorId: report.outcome.evaluatorId, metric: report.outcome.metric,
+      value: Number(report.outcome.value), cases: Number(report.outcome.cases),
+      blockingDefect: report.outcome.blockingDefect === true, sourceDigest: String(report.outcome.sourceDigest || ""),
+      observedAt: timestamp(report.outcome.observedAt || now), passed: false, digest: null,
+      authority: "objective-evidence-only"
+    };
+    if (new Date(outcome.observedAt) > new Date(now)
+      || (attempt && priorOutcomes.some((prior) => prior.sourceDigest === outcome.sourceDigest))) {
+      return { passed: false, outcome: null, reason: "Objective execution evidence is missing or invalid." };
+    }
+    const strategy = execution.strategies.find((item) => item.strategyId === expectedStrategyId);
+    const used = new Set(outcome.capabilitiesUsed);
+    outcome.passed = execution.requiredCapabilities.every((capability) => used.has(capability))
+      && outcome.capabilitiesUsed.every((capability) => strategy.capabilities.includes(capability))
+      && outcome.cases >= execution.verification.minCases && !outcome.blockingDefect
+      && metricPassed(execution.verification.operator, outcome.value, execution.verification.threshold);
+    outcome.digest = sha256(JSON.stringify(executionOutcomeMaterial(outcome)));
+    outcome.outcomeId = "execution-outcome:" + outcome.digest.slice(0, 32);
+  } catch {
+    return { passed: false, outcome: null, reason: "Objective execution evidence is missing or invalid." };
+  }
+  if (!validExecutionOutcome(outcome, execution, expectedStrategyId, attempt?.attempt ?? null,
+    attempt?.previousOutcomeDigest ?? null)
+    || !validExecutionOutcomeSequence(execution, [...priorOutcomes, outcome])) {
+    return { passed: false, outcome: null, reason: "Objective execution evidence is missing or invalid." };
+  }
+  const nextAttempt = !outcome.passed && !outcome.blockingDefect
+    ? currentExecutionAttempt(execution, [...priorOutcomes, outcome]) : null;
+  return { passed: outcome.passed, outcome, nextAttempt,
+    reason: outcome.passed ? null : "The objective execution gate did not pass." };
+}

package/agent-spine-plugin/src/lib/gateway-host-lifecycle.js

@@ -0,0 +1,185 @@
+export const AMBIGUOUS_HOST_OUTCOME =
+  "Host execution may have produced an effect before restart; manual owner review is required.";
+
+const EXECUTION_MODES = new Set(["host-effect", "read-only"]);
+
+function validTimestamp(value) {
+  return typeof value === "string" && Number.isFinite(new Date(value).getTime());
+}
+
+export function normalizeGatewayExecutionMode(value = "host-effect") {
+  if (!EXECUTION_MODES.has(value)) {
+    throw new Error("executionMode must be host-effect or read-only");
+  }
+  return value;
+}
+
+export function newGatewayLease(workerId, current, seconds, executionMode) {
+  return { workerId, claimedAt: current, executionMode,
+    expiresAt: new Date(new Date(current).getTime() + seconds * 1000).toISOString(),
+    ...(executionMode === "host-effect" ? { effectMayStartAt: current } : {}) };
+}
+
+export function assertGatewayCompletionMode(lease, result) {
+  if (lease.executionMode === "read-only") {
+    if (result?.readOnly !== true) {
+      throw new Error("read-only gateway lease completion requires result.readOnly: true");
+    }
+    return false;
+  }
+  if (!validTimestamp(lease?.hostStartedAt)) {
+    throw new Error("gateway lease with possible host effects requires markGatewayHostStarted before completion");
+  }
+  return true;
+}
+
+export function matchesGatewayLaneLease(lane, queue) {
+  return queue?.status === "leased" && queue.lease?.workerId === lane.workerId
+    && queue.lease.claimedAt === lane.claimedAt && queue.lease.expiresAt === lane.expiresAt;
+}
+
+export function exactGatewayLeaseGeneration(claimedAt, attempt, action) {
+  if (!validTimestamp(claimedAt) || !Number.isInteger(attempt) || attempt < 1) {
+    throw new Error(`${action} requires claimedAt and attempt from the exact active queue lease`);
+  }
+  return new Date(claimedAt).toISOString();
+}
+
+export function requireExactGatewayLease(runtime, item, { workerId, claimedAt, attempt, current, action }) {
+  if (!item || item.status !== "leased" || item.attempts !== attempt
+    || item.lease?.workerId !== workerId || item.lease.claimedAt !== claimedAt
+    || new Date(item.lease.expiresAt) <= new Date(current)) {
+    throw new Error(`${action} requires the exact active queue lease`);
+  }
+  const lane = runtime.lanes.find((entry) => entry.queueId === item.queueId && entry.workerId === workerId
+    && entry.claimedAt === claimedAt && entry.expiresAt === item.lease.expiresAt && entry.status === "leased");
+  if (!lane) throw new Error("agent lane lease is missing");
+  return lane;
+}
+
+export function validGatewayLeaseExecution(lease) {
+  if (lease?.executionMode === undefined) {
+    return lease?.effectMayStartAt === undefined
+      && (lease.hostStartedAt === undefined || validTimestamp(lease.hostStartedAt));
+  }
+  if (lease.executionMode === "host-effect") {
+    return validTimestamp(lease.effectMayStartAt)
+      && (lease.hostStartedAt === undefined || validTimestamp(lease.hostStartedAt));
+  }
+  return lease.executionMode === "read-only" && lease.effectMayStartAt === undefined
+    && lease.hostStartedAt === undefined;
+}
+
+export function leaseMayHaveHostEffect(lease) {
+  return lease?.executionMode !== "read-only";
+}
+
+export function hasAmbiguousHostOutcome(runtime) {
+  return runtime.receipts.some((receipt) => receipt.kind === "host-outcome-ambiguous");
+}
+
+export function gatewayHostHealthFindings(runtime) {
+  if (runtime.health.host !== "failed") return [];
+  return ["host-not-healthy", ...(hasAmbiguousHostOutcome(runtime) ? ["host-outcome-ambiguous"] : [])];
+}
+
+function markAmbiguousHostHealth(runtime, current) {
+  runtime.health.host = "failed";
+  runtime.health.worker = "degraded";
+  runtime.health.lastTickAt = current;
+}
+
+export function requireExactHostLease(runtime, item, { workerId, claimedAt, attempt, current }) {
+  const lane = requireExactGatewayLease(runtime, item,
+    { workerId, claimedAt, attempt, current, action: "host start" });
+  if (item.lease.executionMode !== "host-effect") {
+    throw new Error("host start requires a host-effect lease");
+  }
+  if (item.lease.hostStartedAt) throw new Error("the exact queue lease already started host execution");
+  return lane;
+}
+
+export function markHostStarted(runtime, item, lane, workerId, current, { preserve, appendReceipt }) {
+  preserve(runtime, "queue", item, "host-started", current);
+  item.lease.hostStartedAt = current;
+  item.updatedAt = current;
+  lane.updatedAt = current;
+  runtime.revision += 1;
+  return appendReceipt(runtime, "host-started", item.queueId, current,
+    { workerId, attempt: item.attempts });
+}
+
+function blockBoundGoal(policy, item, current) {
+  const goal = item.goalId ? policy.goals.find((entry) => entry.goalId === item.goalId) : null;
+  if (!goal || goal.status !== "active") return false;
+  const step = item.goalStepId && goal.plan
+    ? goal.plan.steps.find((entry) => entry.stepId === item.goalStepId) : null;
+  if (goal.plan && (step?.stepId !== goal.plan.currentStepId || step.status !== "active")) return false;
+  policy.history.push({ kind: "goal", at: current, value: structuredClone(goal),
+    authority: "authenticated-goal-policy" });
+  goal.status = "blocked";
+  goal.blocker = AMBIGUOUS_HOST_OUTCOME;
+  goal.heartbeatAt = current;
+  goal.updatedAt = current;
+  if (step) {
+    step.status = "blocked";
+    step.blocker = AMBIGUOUS_HOST_OUTCOME;
+    step.updatedAt = current;
+    goal.plan.revision += 1;
+  }
+  policy.revision += 1;
+  return true;
+}
+
+export function expireGatewayLane(policy, runtime, lane, current, { preserve, appendReceipt }) {
+  const item = runtime.queue.find((entry) => entry.queueId === lane.queueId && entry.status === "leased");
+  if (item?.lease && leaseMayHaveHostEffect(item.lease)) {
+    const { hostStartedAt = null, effectMayStartAt = null, executionMode = "legacy-unknown" } = item.lease;
+    preserve(runtime, "queue", item, "host-outcome-ambiguous", current);
+    item.status = "blocked";
+    item.lease = null;
+    item.lastError = AMBIGUOUS_HOST_OUTCOME;
+    item.completedAt = current;
+    item.updatedAt = current;
+    appendReceipt(runtime, "host-outcome-ambiguous", item.queueId, current,
+      { attempt: item.attempts, hostStartedAt, effectMayStartAt, executionMode });
+    lane.status = "expired";
+    lane.updatedAt = current;
+    markAmbiguousHostHealth(runtime, current);
+    return blockBoundGoal(policy, item, current);
+  }
+  if (item) {
+    preserve(runtime, "queue", item, "lease-expired", current);
+    item.status = item.attempts >= 3 ? "dead-letter" : "pending";
+    item.lease = null;
+    item.updatedAt = current;
+  }
+  lane.status = "expired";
+  lane.updatedAt = current;
+  return false;
+}
+
+export function failGatewayLane(policy, runtime, item, lane, current,
+  { error, retryAfterMs, preserve, appendReceipt }) {
+  if (leaseMayHaveHostEffect(item.lease)) {
+    expireGatewayLane(policy, runtime, lane, current, { preserve, appendReceipt });
+    runtime.revision += 1;
+    return { ambiguous: true, receipt: runtime.receipts.at(-1) };
+  }
+  preserve(runtime, "queue", item, "run-failed", current);
+  item.status = item.attempts >= 3 ? "dead-letter" : "pending";
+  item.lease = null;
+  item.lastError = error;
+  item.updatedAt = current;
+  item.availableAt = new Date(new Date(current).getTime() + retryAfterMs).toISOString();
+  if (item.status === "dead-letter") item.completedAt = current;
+  lane.status = "completed";
+  lane.updatedAt = current;
+  runtime.health.host = "failed";
+  runtime.health.worker = "degraded";
+  runtime.health.lastTickAt = current;
+  runtime.revision += 1;
+  return { ambiguous: false, receipt: appendReceipt(runtime,
+    item.status === "dead-letter" ? "run-dead-letter" : "run-retry",
+    item.queueId, current, { attempt: item.attempts }) };
+}

package/agent-spine-plugin/src/lib/gateway-inspection.js

@@ -0,0 +1,85 @@
+import { gatewayHostHealthFindings } from "./gateway-host-lifecycle.js";
+import { emptyPolicy, emptyRuntime, exactId } from "./gateway-common.js";
+import { executionAttemptForStep } from "./gateway-execution.js";
+import {
+  conflictingResources, currentPlanStep, gatewayRuntimeFindings, normalizePolicy,
+  normalizeRuntime, pathsFor, planStepAgentId, readJson, withLock
+} from "./gateway-state.js";
+
+export async function loadGatewayRuntime(root = process.cwd(), catalog = null) {
+  const paths = await pathsFor(root, catalog);
+  return withLock(paths, async () => {
+    const [policy, runtime] = await Promise.all([
+      readJson(paths.gatewayPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy),
+      readJson(paths.gatewayRuntimePath, paths.catalog.root, normalizeRuntime, emptyRuntime)
+    ]);
+    return { policy, runtime, ...paths };
+  });
+}
+
+export async function inspectGatewayRuntime(root = process.cwd(), catalog = null) {
+  const paths = await pathsFor(root, catalog); const errors = [];
+  let policy = emptyPolicy(paths.catalog.root); let runtime = emptyRuntime(paths.catalog.root);
+  try {
+    await withLock(paths, async () => {
+      try { policy = await readJson(paths.gatewayPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy); }
+      catch (error) { errors.push("policy:" + error.message); }
+      try { runtime = await readJson(paths.gatewayRuntimePath, paths.catalog.root, normalizeRuntime, emptyRuntime); }
+      catch (error) { errors.push("runtime:" + error.message); }
+    });
+  } catch (error) { errors.push("transaction:" + error.message); }
+  return { policy, runtime, errors, ...paths };
+}
+
+
+export { gatewayRuntimeFindings } from "./gateway-state.js";
+
+export function gatewayHealthFindings(policy, runtime, { now = new Date(), staleAfterMs = 180000 } = {}) {
+  if (!policy.enabled || policy.killSwitch) return [];
+  const findings = [];
+  if (runtime.health.gateway !== "running") findings.push("gateway-not-running");
+  if (runtime.health.scheduler !== "healthy") findings.push("scheduler-not-healthy");
+  if (runtime.health.queue !== "healthy") findings.push("queue-not-healthy");
+  if (!new Set(["healthy", "degraded"]).has(runtime.health.worker)) findings.push("worker-not-healthy");
+  if (!new Set(["healthy", "degraded"]).has(runtime.health.adapter)) findings.push("adapter-not-healthy");
+  findings.push(...gatewayHostHealthFindings(runtime));
+  const current = now instanceof Date ? now : new Date(now);
+  const tick = runtime.health.lastTickAt === null ? null : new Date(runtime.health.lastTickAt);
+  const reconciliation = runtime.health.lastReconciledAt === null ? null : new Date(runtime.health.lastReconciledAt);
+  if (!tick || current.getTime() - tick.getTime() > staleAfterMs) findings.push("worker-heartbeat-stale");
+  if (!reconciliation || current.getTime() - reconciliation.getTime() > staleAfterMs) findings.push("scheduler-heartbeat-stale");
+  return findings;
+}
+
+export async function gatewayContext({ root = process.cwd(), agentId = null } = {}) {
+  const { policy, runtime } = await loadGatewayRuntime(root);
+  const findings = gatewayRuntimeFindings(policy, runtime);
+  if (findings.length) throw new Error("gateway runtime failed closed: " + findings.join(", "));
+  const exactAgentId = agentId === null ? null : exactId(agentId, "agentId");
+  const goals = policy.goals.filter((item) => exactAgentId === null || item.agentId === exactAgentId
+    || item.plan?.steps.some((step) => planStepAgentId(item, step) === exactAgentId));
+  const executionAttempts = goals.map((goal) => {
+    const step = currentPlanStep(goal); const attempt = executionAttemptForStep(step);
+    return attempt && (exactAgentId === null || planStepAgentId(goal, step) === exactAgentId)
+      ? { goalId: goal.goalId, goalStepId: step.stepId, ...attempt } : null;
+  }).filter(Boolean);
+  const queue = runtime.queue.filter((item) => exactAgentId === null || item.agentId === exactAgentId);
+  const queueIds = new Set(queue.map((item) => item.queueId));
+  const leased = runtime.queue.filter((item) => item.status === "leased");
+  const resourceWaits = queue.filter((item) => item.status === "pending").map((item) => {
+    const blockers = leased.map((entry) => ({ entry, resources: conflictingResources(policy, item, entry) }))
+      .filter(({ resources }) => resources.length > 0);
+    return blockers.length ? {
+      queueId: item.queueId,
+      resources: [...new Set(blockers.flatMap(({ resources }) => resources))].sort(),
+      blockedByQueueIds: blockers.map(({ entry }) => entry.queueId).sort(),
+      authority: "execution-state-only"
+    } : null;
+  }).filter(Boolean);
+  return { schema: "agentspine.gateway-context/v1", enabled: policy.enabled, killSwitch: policy.killSwitch,
+    goals: structuredClone(goals), queue: structuredClone(queue),
+    outbox: structuredClone(runtime.outbox.filter((item) => queueIds.has(item.queueId))),
+    resourceWaits, executionAttempts,
+    health: structuredClone(runtime.health), healthFindings: gatewayHealthFindings(policy, runtime),
+    authority: "execution-state-only" };
+}