@kal-elsam/kairo-runtime 0.11.0 → 0.13.0

package/src/global/runtime/review/review-runner.js

@@ -60,7 +60,7 @@ function classifyAgentError(error) {
  * Never returns/persists prompt, patch, JSONL, or transcript.
  */
 export async function runReview({
-  cwd, agent, base = null, commit = null, model = null,
+  cwd, agent, base = null, commit = null, staged = false, model = null,
   includePrivate = false, privateConfirmed = false, failOn = null,
   homeDir, cliVersion = null,
   resolveSnapshot = resolveReviewSnapshot,
@@ -73,7 +73,7 @@ export async function runReview({
   const reviewId = createId();
   const startedAt = now();
   const snapshot = await resolveSnapshot({
-    cwd, base, commit, includePrivate, privateConfirmed
+    cwd, base, commit, staged, includePrivate, privateConfirmed
   });
 
   let state = REVIEW_STATES.COMPLETED;

package/src/global/runtime/review/review-types.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 
 export const REVIEW_SCOPE_MODES = Object.freeze({
-  WORKING_TREE: "working-tree", BASE: "base", COMMIT: "commit"
+  WORKING_TREE: "working-tree", BASE: "base", COMMIT: "commit", STAGED: "staged"
 });
 export const REVIEW_SEVERITIES = Object.freeze({ HIGH: "high", MEDIUM: "medium", LOW: "low" });
 export const REVIEW_STATES = Object.freeze({
@@ -18,7 +18,8 @@ export const REVIEW_SNAPSHOT_ERROR_CODES = Object.freeze({
   INVALID_SCOPE: "invalid_scope",
   INVALID_PATH: "invalid_path",
   LIMIT_EXCEEDED: "limit_exceeded",
-  PRIVATE_CONSENT_REQUIRED: "private_consent_required"
+  PRIVATE_CONSENT_REQUIRED: "private_consent_required",
+  TRUNCATED_OBJECT_ID: "truncated_object_id"
 });
 
 export class ReviewSnapshotError extends Error {
@@ -30,12 +31,14 @@ export class ReviewSnapshotError extends Error {
   }
 }
 
-export function resolveReviewScopeMode({ base = null, commit = null } = {}) {
-  if (base && commit) {
-    throw new ReviewSnapshotError("--base and --commit are mutually exclusive.", {
+export function resolveReviewScopeMode({ base = null, commit = null, staged = false } = {}) {
+  const selected = [Boolean(base), Boolean(commit), Boolean(staged)].filter(Boolean).length;
+  if (selected > 1) {
+    throw new ReviewSnapshotError("--base, --commit, and --staged are mutually exclusive.", {
       code: REVIEW_SNAPSHOT_ERROR_CODES.INVALID_SCOPE
     });
   }
+  if (staged) return REVIEW_SCOPE_MODES.STAGED;
   if (base) return REVIEW_SCOPE_MODES.BASE;
   if (commit) return REVIEW_SCOPE_MODES.COMMIT;
   return REVIEW_SCOPE_MODES.WORKING_TREE;

package/src/global/runtime/review/review-validate.js

@@ -32,7 +32,10 @@ const RECEIPT_SHAPE = Object.freeze({
     commit: "string?",
     fingerprint: "string",
     totals: { fileCount: "number", changedLines: "number", diffBytes: "number" },
-    files: [{ path: "string", sourcePath: "string?", status: "string", hash: "string", changedLines: "number" }],
+    files: [{
+      path: "string", sourcePath: "string?", status: "string", hash: "string",
+      mode: "string?", changedLines: "number"
+    }],
     excluded: [{ path: "string", reason: "string" }]
   },
   findings: [{
@@ -173,6 +176,7 @@ function assertMatchesShape(value, shape, path) {
   }
   for (const [key, childShape] of Object.entries(shape)) {
     if (!(key in body)) {
+      if (typeof childShape === "string" && isOptionalScalar(childShape)) continue;
       throw new ReviewValidationError(`Missing field "${key}" at ${path}.`, {
         code: REVIEW_VALIDATION_ERROR_CODES.INVALID_OUTPUT, details: { path, key }
       });

package/src/global/runtime/run-cli.js

@@ -42,6 +42,8 @@ export async function runGlobalRun(options, packageManifest, { startRunImpl = st
     cwd: options.cwd,
     model: options.model ?? runtime.model,
     permissions,
+    allowUnsafePermissions: Boolean(options.allowUnsafePermissions),
+    permissionSource: "cli",
     captureTranscript,
     cliVersion: packageManifest.version,
     profile: profileResolved,

package/src/global/runtime/run-manager.js

@@ -13,6 +13,7 @@ import {
 import { resolveExecutionAdapter } from "./execution-adapters/index.js";
 import { resolveProfileAgents } from "../profile.js";
 import { resolveRuntimeOptions } from "./run-profile.js";
+import { authorizeRunPermissions } from "./run-permissions.js";
 import { cleanupStaleHandoffs, deleteRunHandoff, writeRunHandoff } from "./run-handoff.js";
 import { isRunAlive } from "./run-liveness.js";
 import { readSupervisorLock, writeSupervisorLock } from "./run-supervisor-lock.js";
@@ -93,6 +94,9 @@ async function prepareRun({
   cwd,
   model = null,
   permissions = [],
+  allowUnsafePermissions = false,
+  permissionSource = "cli",
+  permissionConsentType = null,
   captureTranscript = false,
   cliVersion,
   profile = null,
@@ -113,6 +117,14 @@ async function prepareRun({
     );
   }
 
+  const authorized = authorizeRunPermissions({
+    permissions,
+    agentId,
+    allowUnsafePermissions,
+    source: permissionSource,
+    consentType: permissionConsentType
+  });
+
   if (normalizedStrategy === RUN_STRATEGIES.ORCHESTRATED) {
     await assertManagedMinionExtension(homeDir);
   }
@@ -126,7 +138,8 @@ async function prepareRun({
     model,
     task,
     cwd,
-    permissions,
+    permissions: authorized.permissions,
+    permissionAuthority: authorized.permissionAuthority,
     captureTranscript,
     cliVersion,
     profileSources: profile?.sources ?? null,
@@ -141,7 +154,7 @@ async function prepareRun({
     task,
     cwd,
     model,
-    permissions,
+    permissions: authorized.permissions,
     captureTranscript,
     cliVersion,
     profile: profile?.profile ?? null,
@@ -173,6 +186,9 @@ export async function startRun({
   cwd,
   model = null,
   permissions = [],
+  allowUnsafePermissions = false,
+  permissionSource = "cli",
+  permissionConsentType = null,
   captureTranscript = false,
   cliVersion,
   profile = null,
@@ -190,6 +206,9 @@ export async function startRun({
     cwd,
     model,
     permissions,
+    allowUnsafePermissions,
+    permissionSource,
+    permissionConsentType,
     captureTranscript,
     cliVersion,
     profile,
@@ -275,22 +294,8 @@ export async function stopRun(homeDir, runId, { signal = "SIGTERM" } = {}) {
     return state;
   }
 
-  const lock = await readSupervisorLock(homeDir, runId);
-  const child = activeProcesses.get(runId);
-
-  if (child) {
-    child.kill(signal);
-  } else {
-    const targets = [lock?.agentPid, state.pid, lock?.supervisorPid].filter(Boolean);
-    for (const pid of targets) {
-      try {
-        process.kill(pid, signal);
-      } catch {
-        // Process may already be gone.
-      }
-    }
-  }
-
+  // Persist cancel markers BEFORE kill/close so the supervisor close handler
+  // cannot lose the race and finalize as FAILED while promises stay pending.
   await writeCancelSignal(homeDir, runId, {
     requested: true,
     signal,
@@ -309,6 +314,22 @@ export async function stopRun(homeDir, runId, { signal = "SIGTERM" } = {}) {
     data: { signal }
   }));
 
+  const lock = await readSupervisorLock(homeDir, runId);
+  const child = activeProcesses.get(runId);
+
+  if (child) {
+    child.kill(signal);
+  } else {
+    const targets = [lock?.agentPid, state.pid, lock?.supervisorPid].filter(Boolean);
+    for (const pid of targets) {
+      try {
+        process.kill(pid, signal);
+      } catch {
+        // Process may already be gone.
+      }
+    }
+  }
+
   activeProcesses.delete(runId);
   return metadata;
 }

package/src/global/runtime/run-permissions.js

@@ -0,0 +1,231 @@
+export const PERMISSION_MODES = Object.freeze({
+  NORMAL: "normal",
+  SAFE: "safe",
+  UNSAFE: "unsafe"
+});
+
+export const CONSENT_TYPES = Object.freeze({
+  NONE: "none",
+  ALLOW_UNSAFE_PERMISSIONS: "allow-unsafe-permissions",
+  COCKPIT_UNSAFE_CONFIRM: "cockpit-unsafe-confirm",
+  CLI_CONFIRM_IMPORT: "cli-confirm-import",
+  COCKPIT_ALERT_RESOLVE: "cockpit-alert-resolve",
+  COCKPIT_ALERT_DISMISS: "cockpit-alert-dismiss",
+  CLI_CONFIRM_ALERT_RESOLVE: "cli-confirm-alert-resolve",
+  CLI_CONFIRM_ALERT_DISMISS: "cli-confirm-alert-dismiss"
+});
+
+/** Closed set of non-agent unsafe operations (import, controlled alerts). */
+export const UNSAFE_OPERATIONS = Object.freeze({
+  GENTLE_BUNDLE_IMPORT: "gentle-bundle-import",
+  ALERT_RESOLVE: "alert-resolve",
+  ALERT_DISMISS: "alert-dismiss"
+});
+
+/** Exact (operation, source, consent) triples — reject all other combinations. */
+export const UNSAFE_CONSENT_BINDINGS = Object.freeze([
+  [UNSAFE_OPERATIONS.GENTLE_BUNDLE_IMPORT, "cli", CONSENT_TYPES.CLI_CONFIRM_IMPORT],
+  [UNSAFE_OPERATIONS.ALERT_RESOLVE, "cli", CONSENT_TYPES.CLI_CONFIRM_ALERT_RESOLVE],
+  [UNSAFE_OPERATIONS.ALERT_RESOLVE, "cockpit", CONSENT_TYPES.COCKPIT_ALERT_RESOLVE],
+  [UNSAFE_OPERATIONS.ALERT_DISMISS, "cli", CONSENT_TYPES.CLI_CONFIRM_ALERT_DISMISS],
+  [UNSAFE_OPERATIONS.ALERT_DISMISS, "cockpit", CONSENT_TYPES.COCKPIT_ALERT_DISMISS]
+].map(([operation, source, consent]) => Object.freeze({ operation, source, consent })));
+
+const UNSAFE = new Set(["force", "yolo"]);
+const SAFE = new Set(["read-only"]);
+const UNSAFE_SOURCES = new Set(["cli", "cockpit"]);
+
+/** Canonical permission modes each adapter may accept (empty = normal always ok). */
+export const ADAPTER_PERMISSION_MODES = Object.freeze({
+  pi: Object.freeze(["read-only"]),
+  codex: Object.freeze(["yolo"]),
+  claude: Object.freeze(["force", "yolo"]),
+  cursor: Object.freeze(["force", "yolo"]),
+  opencode: Object.freeze(["force"])
+});
+
+export class PermissionAuthorityError extends Error {
+  constructor(message, { code = "permission_authority", details = null } = {}) {
+    super(message);
+    this.name = "PermissionAuthorityError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function canonicalizeToken(raw) {
+  const token = String(raw ?? "").trim().toLowerCase();
+  if (!token) return null;
+  if (token === "all" || token === "force") return "force";
+  if (token === "yolo" || token.startsWith("dangerously-")) return "yolo";
+  if (token === "read-only") return "read-only";
+  throw new PermissionAuthorityError(`Unknown permission "${raw}".`, {
+    code: "unknown_permission", details: { permission: raw }
+  });
+}
+
+/** Normalize aliases; reject unknown tokens. Dedupes preserving force/yolo/read-only order. */
+export function normalizePermissions(permissions = []) {
+  if (!Array.isArray(permissions)) {
+    throw new PermissionAuthorityError("Permissions must be an array.", {
+      code: "invalid_permissions"
+    });
+  }
+  const seen = new Set();
+  const out = [];
+  for (const entry of permissions) {
+    const token = canonicalizeToken(entry);
+    if (!token || seen.has(token)) continue;
+    seen.add(token);
+    out.push(token);
+  }
+  return out;
+}
+
+export function classifyPermissionMode(normalized = []) {
+  if (normalized.some((p) => UNSAFE.has(p))) return PERMISSION_MODES.UNSAFE;
+  if (normalized.some((p) => SAFE.has(p))) return PERMISSION_MODES.SAFE;
+  return PERMISSION_MODES.NORMAL;
+}
+
+/** Profile defaults may only be empty or safe — never force/yolo/aliases. */
+export function validateDefaultPermissions(defaultPermissions) {
+  if (defaultPermissions == null) return [];
+  const normalized = normalizePermissions(defaultPermissions);
+  if (normalized.some((p) => UNSAFE.has(p))) {
+    throw new PermissionAuthorityError(
+      "Profile defaultPermissions cannot include unsafe modes (force/yolo/all/dangerously-*). "
+      + "Pass them per run with --allow-unsafe-permissions.",
+      { code: "unsafe_default_permissions", details: { defaultPermissions: normalized } }
+    );
+  }
+  return normalized;
+}
+
+function resolveConsent({ mode, source, allowUnsafePermissions, consentType }) {
+  if (mode !== PERMISSION_MODES.UNSAFE) return CONSENT_TYPES.NONE;
+  if (consentType) return consentType;
+  if (source === "cockpit") return CONSENT_TYPES.COCKPIT_UNSAFE_CONFIRM;
+  if (allowUnsafePermissions) return CONSENT_TYPES.ALLOW_UNSAFE_PERMISSIONS;
+  return CONSENT_TYPES.NONE;
+}
+
+/**
+ * Fail-closed permission authority for startRun.
+ * Unsafe modes require explicit allowUnsafePermissions (CLI) or cockpit confirm.
+ */
+export function authorizeRunPermissions({
+  permissions = [],
+  agentId,
+  allowUnsafePermissions = false,
+  source = "cli",
+  consentType = null
+} = {}) {
+  const normalized = normalizePermissions(permissions);
+  const mode = classifyPermissionMode(normalized);
+
+  if (mode === PERMISSION_MODES.UNSAFE && !allowUnsafePermissions) {
+    throw new PermissionAuthorityError(
+      `Unsafe permissions (${normalized.join(", ")}) require --allow-unsafe-permissions `
+      + "(or an explicit Cockpit unsafe confirmation).",
+      { code: "unsafe_consent_required", details: { permissions: normalized, source } }
+    );
+  }
+
+  const supported = new Set(ADAPTER_PERMISSION_MODES[agentId] ?? []);
+  for (const token of normalized) {
+    if (!supported.has(token)) {
+      throw new PermissionAuthorityError(
+        `Permission "${token}" is not supported by adapter "${agentId}". `
+        + `Supported: ${[...supported].join(", ") || "(none)"}.`,
+        {
+          code: "unsupported_permission",
+          details: { permission: token, agentId, supported: [...supported] }
+        }
+      );
+    }
+  }
+
+  const consent = resolveConsent({ mode, source, allowUnsafePermissions, consentType });
+  return {
+    permissions: normalized,
+    permissionAuthority: {
+      mode,
+      source: source === "cockpit" ? "cockpit" : "cli",
+      consent
+    }
+  };
+}
+
+/** Map normalized permissions to common CLI flags (force/yolo). */
+export function buildPermissionsArgs(permissions = []) {
+  const normalized = normalizePermissions(permissions);
+  if (normalized.includes("force")) return ["--force"];
+  if (normalized.includes("yolo")) return ["--dangerously-skip-permissions"];
+  return [];
+}
+
+/** Fail-closed unsafe-op authority: closed bindings + frozen process-local issuance. */
+const ISSUED_UNSAFE_AUTHORITIES = new WeakMap();
+
+function resolveConsentBinding(operation, source, consentType) {
+  const match = UNSAFE_SOURCES.has(source)
+    ? UNSAFE_CONSENT_BINDINGS.find((b) => b.operation === operation && b.source === source)
+    : null;
+  if (!match || (consentType != null && consentType !== match.consent)) {
+    throw new PermissionAuthorityError(
+      `Invalid consent binding for "${operation}" / "${source}"`
+      + (consentType != null ? ` / "${consentType}"` : "") + ".",
+      { code: "invalid_unsafe_consent", details: { operation, source, consentType } }
+    );
+  }
+  return match.consent;
+}
+
+export function assertUnsafePermissionAuthority(permissionAuthority, { expectedOperation } = {}) {
+  const pa = permissionAuthority;
+  if (!pa || typeof pa !== "object" || Array.isArray(pa) || pa.mode !== PERMISSION_MODES.UNSAFE) {
+    throw new PermissionAuthorityError("Unsafe mutation requires permissionAuthority.", {
+      code: pa ? "invalid_unsafe_consent" : "permission_authority_required",
+      details: pa ? { permissionAuthority: pa } : null
+    });
+  }
+  const issued = ISSUED_UNSAFE_AUTHORITIES.get(pa);
+  if (!issued) {
+    throw new PermissionAuthorityError("permissionAuthority was not issued by authorizeUnsafeOperation.", {
+      code: "permission_authority_forged", details: { operation: pa.operation, source: pa.source }
+    });
+  }
+  if (expectedOperation && issued.operation !== expectedOperation) {
+    throw new PermissionAuthorityError(
+      `permissionAuthority.operation "${issued.operation}" does not match "${expectedOperation}".`,
+      { code: "invalid_unsafe_consent", details: { operation: issued.operation, expectedOperation } }
+    );
+  }
+  resolveConsentBinding(issued.operation, issued.source, issued.consent);
+  return issued;
+}
+
+export function authorizeUnsafeOperation({
+  operation, confirmed = false, source = "cli", consentType = null
+} = {}) {
+  if (!Object.values(UNSAFE_OPERATIONS).includes(operation)) {
+    throw new PermissionAuthorityError(`Unknown unsafe operation "${operation}".`, {
+      code: "unknown_unsafe_operation", details: { operation }
+    });
+  }
+  if (!confirmed) {
+    const code = operation === UNSAFE_OPERATIONS.GENTLE_BUNDLE_IMPORT
+      ? "import_consent_required" : "unsafe_consent_required";
+    throw new PermissionAuthorityError(
+      `Unsafe operation "${operation}" requires explicit confirmation.`,
+      { code, details: { operation, source } }
+    );
+  }
+  const consent = resolveConsentBinding(operation, source, consentType);
+  const permissionAuthority = Object.freeze({
+    mode: PERMISSION_MODES.UNSAFE, source, consent, operation
+  });
+  ISSUED_UNSAFE_AUTHORITIES.set(permissionAuthority, permissionAuthority);
+  return { operation, permissionAuthority };
+}

package/src/global/runtime/run-profile.js

@@ -1,5 +1,6 @@
 import { resolveProfileAgents } from "../profile.js";
 import { EXECUTION_ADAPTER_IDS } from "./execution-adapters/index.js";
+import { validateDefaultPermissions } from "./run-permissions.js";
 
 export function resolveRuntimeOptions(profileResolved, overrides = {}) {
   const profile = profileResolved?.profile ?? profileResolved ?? {};
@@ -56,6 +57,7 @@ export function validateRuntimeProfile(profile) {
   if (defaultPermissions != null && !Array.isArray(defaultPermissions)) {
     throw new Error("Profile defaultPermissions must be an array.");
   }
+  validateDefaultPermissions(defaultPermissions);
 
   if (
     profile.defaultRuntimeAgent != null

package/src/global/runtime/run-supervisor.js

@@ -36,6 +36,17 @@ async function shouldPreserveCancelledState(homeDir, runId) {
   return null;
 }
 
+let afterMissedCancelCheckForTests = null;
+
+/** Test seam: runs after a cancel-preserve miss, before writing FAILED/COMPLETED. */
+export function setAfterMissedCancelCheckForTests(fn) {
+  afterMissedCancelCheckForTests = fn;
+}
+
+export function resetAfterMissedCancelCheckForTests() {
+  afterMissedCancelCheckForTests = null;
+}
+
 const workerPath = fileURLToPath(new URL("./run-supervisor-worker.js", import.meta.url));
 
 export function spawnDetachedSupervisor({ homeDir, runId, spawnImpl = spawn }) {
@@ -182,34 +193,73 @@ export async function supervisePreparedRun({
   };
 
   const completion = new Promise((resolve, reject) => {
+    let settled = false;
+    const settleResolve = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const settleReject = (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+
+    const settleCancelled = async () => {
+      cancelledRuns?.delete(runId);
+      try {
+        const fresh = await readRunState(homeDir, runId);
+        if (fresh?.state === RUN_STATES.CANCELLED) {
+          settleResolve(fresh);
+          return;
+        }
+        settleResolve({ ...(fresh ?? metadata), state: RUN_STATES.CANCELLED });
+      } catch {
+        settleResolve({ ...metadata, state: RUN_STATES.CANCELLED });
+      }
+    };
+
+    const preferCancelled = async () => {
+      const preserved = await shouldPreserveCancelledState(homeDir, runId);
+      if (preserved || cancelledRuns?.has(runId)) {
+        await settleCancelled();
+        return true;
+      }
+      return false;
+    };
+
     child.on("error", async (error) => {
       if (timeoutHandle) clearTimeout(timeoutHandle);
       activeProcesses?.delete(runId);
 
-      await serializeStateWrite(async () => {
-        const preserved = await shouldPreserveCancelledState(homeDir, runId);
-        if (preserved) {
-          cancelledRuns?.delete(runId);
-          resolve(preserved.state === RUN_STATES.CANCELLED
-            ? preserved
-            : { ...preserved, state: RUN_STATES.CANCELLED });
-          return;
-        }
+      try {
+        await serializeStateWrite(async () => {
+          if (await preferCancelled()) return;
 
-        metadata = transitionRunState(metadata, RUN_STATES.FAILED, {
-          error: error.message
+          if (afterMissedCancelCheckForTests) {
+            await afterMissedCancelCheckForTests({ runId, homeDir, phase: "error" });
+          }
+          if (await preferCancelled()) return;
+
+          metadata = transitionRunState(metadata, RUN_STATES.FAILED, {
+            error: error.message
+          });
+          await writeRunState(homeDir, metadata);
+          await appendRunEvent(homeDir, createRunEvent({
+            runId,
+            type: "run.failed",
+            data: { error: error.message }
+          }), { captureTranscript: shouldPersistTranscript(captureTranscript) });
         });
-        await writeRunState(homeDir, metadata);
-        await appendRunEvent(homeDir, createRunEvent({
-          runId,
-          type: "run.failed",
-          data: { error: error.message }
-        }), { captureTranscript: shouldPersistTranscript(captureTranscript) });
-      });
-      reject(error);
+        if (!settled) settleReject(error);
+      } catch (handlerError) {
+        settleReject(handlerError);
+      }
     });
 
     child.on("close", async (exitCode) => {
+      if (settled) return;
+
       try {
         if (timeoutHandle) clearTimeout(timeoutHandle);
         activeProcesses?.delete(runId);
@@ -230,24 +280,14 @@ export async function supervisePreparedRun({
         await stateWrites;
 
         await serializeStateWrite(async () => {
-          const preserved = await shouldPreserveCancelledState(homeDir, runId);
-          if (preserved) {
-            cancelledRuns?.delete(runId);
-            resolve(preserved.state === RUN_STATES.CANCELLED
-              ? preserved
-              : { ...preserved, state: RUN_STATES.CANCELLED });
-            return;
-          }
+          if (settled) return;
+          if (await preferCancelled()) return;
 
-          if (cancelledRuns?.has(runId)) {
-            cancelledRuns.delete(runId);
-            try {
-              resolve(await readRunState(homeDir, runId));
-            } catch {
-              resolve({ ...metadata, state: RUN_STATES.CANCELLED });
-            }
-            return;
+          if (afterMissedCancelCheckForTests) {
+            await afterMissedCancelCheckForTests({ runId, homeDir, phase: "close", exitCode });
           }
+          if (settled) return;
+          if (await preferCancelled()) return;
 
           const failed = exitCode !== 0;
           const nextState = failed ? RUN_STATES.FAILED : RUN_STATES.COMPLETED;
@@ -264,10 +304,10 @@ export async function supervisePreparedRun({
           if (!failed && strategy === RUN_STRATEGIES.ORCHESTRATED) {
             await finalizeOrchState(runId, { homeDir, recovered: false });
           }
-          resolve(metadata);
+          settleResolve(metadata);
         });
       } catch (error) {
-        reject(error);
+        settleReject(error);
       }
     });
   });

package/src/global/runtime/run-types.js

@@ -81,6 +81,7 @@ export function createRunMetadata({
   task,
   cwd,
   permissions = [],
+  permissionAuthority = null,
   captureTranscript = false,
   cliVersion,
   profileSources = null,
@@ -99,6 +100,7 @@ export function createRunMetadata({
     taskLength,
     cwd,
     permissions,
+    permissionAuthority,
     captureTranscript,
     cliVersion,
     profileSources,

package/src/global/updates-cli.js

@@ -0,0 +1,41 @@
+import { loadEcosystemUpdates as defaultLoadEcosystemUpdates } from "./observability/ecosystem-updates.js";
+import { commandHeader } from "./brand/index.js";
+import { resolveHomeDir } from "./paths.js";
+
+/** Read-only ecosystem update check — never applies upgrades. */
+export async function runEcosystemUpdatesCheck(
+  options = {},
+  packageManifest = {},
+  { loadEcosystemUpdates = defaultLoadEcosystemUpdates } = {}
+) {
+  const action = options.updatesAction ?? "check";
+  if (action !== "check") {
+    throw new Error(`Unknown updates action "${action}". Use: kairo updates check`);
+  }
+
+  const report = await loadEcosystemUpdates({
+    packageName: packageManifest.name ?? "@kal-elsam/kairo-runtime",
+    installedVersion: packageManifest.version ?? "0.0.0",
+    homeDir: resolveHomeDir(options.env ?? process.env),
+    forceRefresh: options.force === true,
+    env: options.env ?? process.env
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify({ command: "updates", action: "check", ...report }, null, 2));
+    return report;
+  }
+
+  console.log(commandHeader("updates check — ecosystem (read-only)"));
+  console.log(`State: ${report.state}${report.cacheHit ? " · cache" : ""}`);
+  if (report.checkedAt) console.log(`Checked: ${report.checkedAt}`);
+  for (const id of ["kairo", "hermes", "gentle", "skills"]) {
+    const tool = report.tools?.[id] ?? {};
+    const flag = tool.updateAvailable ? "UPDATE" : "ok";
+    const err = tool.error ? ` · ${tool.error}` : "";
+    console.log(`[${flag}] ${id.padEnd(7)} installed: ${tool.installed ?? "—"}  latest: ${tool.latest ?? "—"}${err}`);
+  }
+  console.log("");
+  console.log("No updates were applied. Consent-gated apply lands in a later slice.");
+  return report;
+}