@kal-elsam/kairo-runtime 0.4.2 → 0.5.0

package/src/global/integrations/sdd-apply.js

@@ -0,0 +1,190 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { hashBuffer } from "../../hash.js";
+import { assertExplicitApplyConsent, promptApplyConfirmation, shouldPromptApplyConfirmation } from "../apply-confirmation.js";
+import { SDD_FILE_OUTCOMES, SDD_PLAN_ACTIONS } from "./sdd-evidence.js";
+import { resolveCanonicalSddSkillFile, resolveSddSkillRoot } from "./sdd-destinations.js";
+import {
+  assertSafePathChain, parentRealpath, replaceRegularFile, snapshotRegularFile
+} from "./sdd-fs-guard.js";
+import { finalizePersonaTransition } from "./sdd-persona.js";
+import { planSddConfigure } from "./sdd-plan.js";
+import { saveSddReceipt } from "./sdd-receipts.js";
+import { backupSddDestination } from "./sdd-rollback.js";
+
+const APPLYING_ACTIONS = new Set([SDD_PLAN_ACTIONS.CREATE, SDD_PLAN_ACTIONS.UPDATE]);
+
+export async function applySddConfigure({
+  requestedAgentIds = null, detectedAgentIds = [], homeDir, packageRoot, persona = "off",
+  personaAgentIds = [], trackedFiles = {}, preservePersona = false, dryRun = false, yes = false,
+  json = false, interactive = null, receiptId = null, plan = planSddConfigure,
+  confirm = promptApplyConfirmation, saveReceipt = saveSddReceipt,
+  now = () => new Date().toISOString()
+} = {}) {
+  assertExplicitApplyConsent({
+    applying: !dryRun, dryRun, json, yes, interactive, command: "components configure sdd-core"
+  });
+
+  const planned = await plan({
+    requestedAgentIds, detectedAgentIds, homeDir, packageRoot, persona, personaAgentIds,
+    trackedFiles, preservePersona, dryRun: true
+  });
+  if (dryRun) return { ...planned, applied: false, cancelled: false, receipt: null };
+
+  if (shouldPromptApplyConfirmation({ applying: true, dryRun, json, confirm: yes, interactive })) {
+    const accepted = await confirm({
+      command: "components configure sdd-core",
+      question: "Materialize SDD skills for the planned agents? [Y/n]: "
+    });
+    if (!accepted) return { ...planned, applied: false, cancelled: true, receipt: null };
+  }
+
+  const startedAt = now();
+  const resolvedReceiptId = receiptId ?? `sdd-${startedAt.replace(/[:.]/g, "-")}`;
+  const files = [];
+  const backups = [];
+  let failed = null;
+  let abortRemaining = false;
+
+  for (const action of planned.actions) {
+    const record = buildFileRecord(action);
+    if (!APPLYING_ACTIONS.has(action.action)) {
+      const outcome = action.action === SDD_PLAN_ACTIONS.CONFLICT
+        ? SDD_FILE_OUTCOMES.CONFLICT
+        : SDD_FILE_OUTCOMES.NOOP;
+      files.push({ ...record, applied: false, skipped: true, outcome, afterHash: action.diskHash });
+      continue;
+    }
+    if (abortRemaining) {
+      files.push({
+        ...record, applied: false, skipped: true, outcome: SDD_FILE_OUTCOMES.SKIPPED,
+        error: "Skipped after prior file failure; partial evidence retained."
+      });
+      continue;
+    }
+    try {
+      const managedRoot = resolveSddSkillRoot(action.agentIds[0], homeDir);
+      const outcome = await materializeOne(action, {
+        homeDir, packageRoot, managedRoot, receiptId: resolvedReceiptId
+      });
+      if (outcome.conflict) {
+        files.push({
+          ...record, action: SDD_PLAN_ACTIONS.CONFLICT, reason: outcome.conflict,
+          applied: false, skipped: true, outcome: SDD_FILE_OUTCOMES.CONFLICT
+        });
+        continue;
+      }
+      if (outcome.backup) backups.push(outcome.backup);
+      files.push({
+        ...record, applied: true, skipped: false, outcome: SDD_FILE_OUTCOMES.APPLIED,
+        afterHash: outcome.afterHash, parentRealpath: outcome.parentRealpath
+      });
+    } catch (error) {
+      failed = { skillId: action.skillId, destinationPath: action.destinationPath, error: error.message };
+      files.push({
+        ...record, applied: false, skipped: false, outcome: SDD_FILE_OUTCOMES.FAILED, error: error.message
+      });
+      abortRemaining = true;
+    }
+  }
+
+  const appliedCount = files.filter((entry) => entry.applied).length;
+  const personaTransition = finalizePersonaTransition(
+    planned.personaTransition ?? {
+      before: [], after: [], admitted: [], rejected: [], persona: "off", personaChanged: false
+    },
+    files, planned.requestedPersona ?? persona, { preservePersona }
+  );
+  const { before, after, admitted, rejected, personaChanged } = personaTransition;
+  const receipt = {
+    id: resolvedReceiptId,
+    provider: "sdd-core", componentId: "sdd-core", startedAt, finishedAt: now(),
+    persona: personaTransition.persona, personaActive: after.length > 0,
+    personaTransition: { before, after, admitted, rejected, personaChanged },
+    agentIds: planned.agentIds, files, backups, summary: planned.summary,
+    conflicts: files
+      .filter((entry) => entry.action === SDD_PLAN_ACTIONS.CONFLICT)
+      .map((entry) => ({ destinationPath: entry.destinationPath, reason: entry.reason })),
+    ok: failed == null, partial: failed != null && appliedCount > 0, failed,
+    sessionRefreshRequired: appliedCount > 0 || personaChanged, persisted: false
+  };
+
+  const saved = await saveReceipt(receipt, { homeDir });
+  return {
+    ...planned, persona: personaTransition.persona, personaActive: receipt.personaActive,
+    personaTransition, dryRun: false, executes: true, writes: appliedCount > 0,
+    applied: failed == null, cancelled: false,
+    sessionRefreshRequired: receipt.sessionRefreshRequired,
+    receipt: saved.receipt, receiptPath: saved.path
+  };
+}
+
+function buildFileRecord(action) {
+  return {
+    skillId: action.skillId,
+    relativePath: action.relativePath ?? "SKILL.md",
+    destinationPath: action.destinationPath,
+    agentIds: [...action.agentIds],
+    action: action.action,
+    reason: action.reason,
+    canonicalHash: action.canonicalHash,
+    skillHash: action.skillHash ?? null,
+    beforeHash: action.diskHash,
+    trackedHash: action.trackedHash
+  };
+}
+
+async function readCanonicalBytes(action, packageRoot) {
+  return readFile(resolveCanonicalSddSkillFile(
+    action.skillId, action.relativePath ?? "SKILL.md", packageRoot
+  ));
+}
+
+async function materializeOne(action, { homeDir, packageRoot, managedRoot, receiptId }) {
+  const chain = await assertSafePathChain(action.destinationPath, managedRoot, homeDir);
+  if (!chain.ok) return { conflict: chain.reason };
+
+  if (action.action === SDD_PLAN_ACTIONS.CREATE) {
+    if (existsSync(action.destinationPath)) {
+      return { conflict: "Destination appeared after planning; preserving byte-for-byte." };
+    }
+    const bytes = await readCanonicalBytes(action, packageRoot);
+    await mkdir(dirname(action.destinationPath), { recursive: true });
+    const after = await assertSafePathChain(action.destinationPath, managedRoot, homeDir);
+    if (!after.ok) throw new Error(after.reason);
+    const parent = await parentRealpath(action.destinationPath);
+    try {
+      await replaceRegularFile(action.destinationPath, bytes, {
+        createExclusive: true, managedRoot, expectedParentRealpath: parent, trustedAnchor: homeDir
+      });
+    } catch (error) {
+      if (/appeared before create|EEXIST/i.test(error.message)) return { conflict: error.message };
+      throw error;
+    }
+    return { afterHash: hashBuffer(bytes), parentRealpath: parent, backup: null };
+  }
+
+  if (!existsSync(action.destinationPath)) {
+    return { conflict: "Managed destination disappeared after planning; preserving byte-for-byte." };
+  }
+  const snap = await snapshotRegularFile(action.destinationPath);
+  if (snap.hash !== action.trackedHash) {
+    return { conflict: "Managed file changed after planning; preserving byte-for-byte." };
+  }
+  const parent = await parentRealpath(action.destinationPath);
+  let backup;
+  try {
+    backup = await backupSddDestination(action.destinationPath, {
+      homeDir, receiptId, managedRoot, snapshot: snap, parentRealpath: parent
+    });
+  } catch (error) {
+    if (/Backup already exists/i.test(error.message)) return { conflict: error.message };
+    throw error;
+  }
+  const bytes = await readCanonicalBytes(action, packageRoot);
+  await replaceRegularFile(action.destinationPath, bytes, {
+    expectedIno: snap.ino, expectedHash: snap.hash, managedRoot, expectedParentRealpath: parent, trustedAnchor: homeDir
+  });
+  return { afterHash: hashBuffer(bytes), parentRealpath: parent, backup };
+}

package/src/global/integrations/sdd-destinations.js

@@ -0,0 +1,95 @@
+import { join } from "node:path";
+
+export const SDD_SKILL_IDS = Object.freeze([
+  "sdd-init",
+  "sdd-explore",
+  "sdd-propose",
+  "sdd-spec",
+  "sdd-design",
+  "sdd-tasks",
+  "sdd-apply",
+  "sdd-verify",
+  "sdd-archive"
+]);
+
+export const SDD_MANAGED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude"]);
+export const SDD_SHARED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode"]);
+export const SDD_PERSONA_IDS = Object.freeze(["off", "teaching"]);
+
+export function resolveSddAgentSelection({
+  requestedIds = null,
+  detectedIds = [],
+  managedIds = SDD_MANAGED_AGENT_IDS
+} = {}) {
+  const managed = [...managedIds];
+  if (requestedIds == null) {
+    const detected = new Set(detectedIds);
+    return managed.filter((id) => detected.has(id));
+  }
+  if (requestedIds.length === 1 && requestedIds[0] === "all") return [...managed];
+  return requestedIds.map((id) => {
+    if (!managed.includes(id)) {
+      throw new Error(`Agent "${id}" is not managed for SDD skills. Use: ${managed.join(", ")}.`);
+    }
+    return id;
+  });
+}
+
+export function resolveSddSkillRoot(agentId, homeDir) {
+  if (SDD_SHARED_AGENT_IDS.includes(agentId)) {
+    return join(homeDir, ".agents", "skills");
+  }
+  if (agentId === "claude") {
+    return join(homeDir, ".claude", "skills");
+  }
+  throw new Error(`Agent "${agentId}" has no SDD skill destination.`);
+}
+
+export function resolveSddSkillPath(skillId, agentId, homeDir) {
+  return join(resolveSddSkillRoot(agentId, homeDir), skillId, "SKILL.md");
+}
+
+/** One physical destination per root, with stable consumer agentIds. */
+export function groupSddSkillDestinations(agentIds, homeDir) {
+  const selected = new Set(agentIds);
+  const groups = [];
+
+  const sharedConsumers = SDD_SHARED_AGENT_IDS.filter((id) => selected.has(id));
+  if (sharedConsumers.length > 0) {
+    groups.push({
+      kind: "shared",
+      root: join(homeDir, ".agents", "skills"),
+      agentIds: sharedConsumers
+    });
+  }
+
+  if (selected.has("claude")) {
+    groups.push({
+      kind: "claude",
+      root: join(homeDir, ".claude", "skills"),
+      agentIds: ["claude"]
+    });
+  }
+
+  return groups;
+}
+
+export function resolveCanonicalSddSkillDir(skillId, packageRoot) {
+  return join(packageRoot, "global-template", "components", "sdd-core", "skills", skillId);
+}
+
+export function resolveCanonicalSddSkillPath(skillId, packageRoot) {
+  return join(resolveCanonicalSddSkillDir(skillId, packageRoot), "SKILL.md");
+}
+
+export function resolveCanonicalSddSkillFile(skillId, relativePath, packageRoot) {
+  const parts = String(relativePath ?? "SKILL.md").split(/[/\\]/).filter(Boolean);
+  if (parts.length === 0 || parts.includes("..")) {
+    throw new Error(`Invalid skill relativePath "${relativePath}".`);
+  }
+  return join(resolveCanonicalSddSkillDir(skillId, packageRoot), ...parts);
+}
+
+export function resolveCanonicalTeachingPersonaPath(packageRoot) {
+  return join(packageRoot, "global-template", "components", "sdd-core", "personas", "teaching.md");
+}

package/src/global/integrations/sdd-evidence.js

@@ -0,0 +1,89 @@
+export const SDD_PLAN_ACTIONS = Object.freeze({
+  CREATE: "create",
+  NOOP: "noop",
+  UPDATE: "update",
+  CONFLICT: "conflict"
+});
+
+/** Per-file receipt outcomes after apply (Slice 2 evidence). */
+export const SDD_FILE_OUTCOMES = Object.freeze({
+  APPLIED: "applied",
+  NOOP: "noop",
+  CONFLICT: "conflict",
+  FAILED: "failed",
+  SKIPPED: "skipped"
+});
+
+export const SDD_HEALTH = Object.freeze({
+  CONFIGURED: "configured",
+  MISSING: "missing",
+  DRIFTED: "drifted",
+  CONFLICT: "conflict"
+});
+
+/**
+ * Classify one destination file against canonical bytes and optional tracked hash.
+ * Untracked or user-modified files are conflicts and must never be overwritten.
+ */
+export function classifySddSkillFile({
+  exists,
+  canonicalHash,
+  diskHash = null,
+  trackedHash = null
+} = {}) {
+  if (!exists) {
+    return {
+      action: SDD_PLAN_ACTIONS.CREATE,
+      reason: "Destination missing; physical copy planned."
+    };
+  }
+
+  if (trackedHash == null) {
+    return {
+      action: SDD_PLAN_ACTIONS.CONFLICT,
+      reason: "Pre-existing untracked file; preserving byte-for-byte."
+    };
+  }
+
+  if (trackedHash !== diskHash) {
+    return {
+      action: SDD_PLAN_ACTIONS.CONFLICT,
+      reason: "User-modified after materialization; preserving byte-for-byte."
+    };
+  }
+
+  if (diskHash === canonicalHash) {
+    return {
+      action: SDD_PLAN_ACTIONS.NOOP,
+      reason: "Already matches canonical skill bytes."
+    };
+  }
+
+  return {
+    action: SDD_PLAN_ACTIONS.UPDATE,
+    reason: "Managed file drifted from canonical skill bytes."
+  };
+}
+
+/** Map plan classification to verify health, separating canonical vs disk drift. */
+export function classifySddVerifyHealth({
+  exists,
+  canonicalHash,
+  diskHash = null,
+  trackedHash = null
+} = {}) {
+  if (!exists) {
+    return { status: SDD_HEALTH.MISSING, drift: null, reason: "Destination missing on disk." };
+  }
+  if (trackedHash == null) {
+    return { status: SDD_HEALTH.CONFLICT, drift: null, reason: "Pre-existing untracked file." };
+  }
+  if (trackedHash !== diskHash) {
+    return { status: SDD_HEALTH.CONFLICT, drift: "disk", reason: "Disk drifted from tracked hash." };
+  }
+  if (diskHash !== canonicalHash) {
+    return { status: SDD_HEALTH.DRIFTED, drift: "canonical", reason: "Managed bytes drifted from canonical." };
+  }
+  return { status: SDD_HEALTH.CONFIGURED, drift: null, reason: "Matches tracked and canonical bytes." };
+}
+

package/src/global/integrations/sdd-fs-guard.js

@@ -0,0 +1,183 @@
+import { randomBytes } from "node:crypto";
+import { constants as fsConstants, existsSync } from "node:fs";
+import { link, lstat, open, realpath, rename, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { hashBuffer } from "../../hash.js";
+import { isPathInside } from "../component-paths.js";
+import { SDD_SKILL_IDS, resolveSddSkillRoot } from "./sdd-destinations.js";
+
+/** Threat model: local CLI accidental TOCTOU/symlinks — not a malicious same-uid peer. */
+const PLATFORM_NOFOLLOW = fsConstants.O_NOFOLLOW ?? 0;
+export let openNoFollowFlag = PLATFORM_NOFOLLOW;
+let beforeFinalGateForTests = null, afterTombRenameForTests = null;
+export function setOpenNoFollowFlagForTests(flag) { openNoFollowFlag = flag; }
+export function setBeforeFinalGateForTests(fn) { beforeFinalGateForTests = fn; }
+export function setAfterTombRenameForTests(fn) { afterTombRenameForTests = fn; }
+export function resetOpenNoFollowFlagForTests() {
+  openNoFollowFlag = PLATFORM_NOFOLLOW; beforeFinalGateForTests = null; afterTombRenameForTests = null;
+}
+export function resolveExpectedSddDestination(file, homeDir) {
+  if (!SDD_SKILL_IDS.includes(file?.skillId)) {
+    return { ok: false, reason: `Unknown skillId "${file?.skillId}".` };
+  }
+  const agentId = file?.agentIds?.[0];
+  if (!agentId) return { ok: false, reason: "Receipt file missing agentIds." };
+  const relativePath = String(file?.relativePath ?? "SKILL.md");
+  const parts = relativePath.split(/[/\\]/).filter(Boolean);
+  if (parts.length === 0 || parts.includes("..")) {
+    return { ok: false, reason: "Receipt relativePath is invalid." };
+  }
+  const managedRoot = resolve(resolveSddSkillRoot(agentId, homeDir));
+  const expectedPath = resolve(join(managedRoot, file.skillId, ...parts));
+  const claimedPath = resolve(String(file.destinationPath ?? ""));
+  if (claimedPath !== expectedPath) {
+    return { ok: false, reason: "Receipt destinationPath does not match managed skill path." };
+  }
+  return { ok: true, path: expectedPath, managedRoot };
+}
+export function assertBackupPathContained(backupPath, backupDir) {
+  const expectedDir = resolve(backupDir);
+  const claimed = resolve(String(backupPath ?? ""));
+  if (!isPathInside(expectedDir, claimed) && claimed !== expectedDir) {
+    return { ok: false, reason: "Backup path escapes receipt backup directory." };
+  }
+  return { ok: true, path: claimed };
+}
+export async function assertSafePathChain(targetPath, managedRoot, trustedAnchor = null) {
+  const root = resolve(managedRoot);
+  const target = resolve(targetPath);
+  const anchor = resolve(trustedAnchor ?? root);
+  if (!isPathInside(root, target) && target !== root) {
+    return { ok: false, reason: "Path escapes managed root." };
+  }
+  for (let current = target; ; current = dirname(current)) {
+    if (existsSync(current) && (await lstat(current)).isSymbolicLink()) {
+      return { ok: false, reason: current === root ? "Managed root is a symlink; refusing." : `Symlink in path chain at ${current}; refusing.` };
+    }
+    if (current === anchor) break;
+    if (dirname(current) === current) return { ok: false, reason: "Path chain never reached trusted anchor." };
+  }
+  return { ok: true, path: target, managedRoot: root };
+}
+export async function parentRealpath(path) {
+  const parent = dirname(resolve(path));
+  return existsSync(parent) ? realpath(parent) : resolve(parent);
+}
+export async function refuseSymlink(path, label = "path") {
+  if (!existsSync(path)) return null;
+  if ((await lstat(path)).isSymbolicLink()) return `${label} is a symlink; refusing.`;
+  return null;
+}
+async function assertMutableTarget(path, { managedRoot = null, expectedParentRealpath = null, trustedAnchor = null } = {}) {
+  if (managedRoot) { const c = await assertSafePathChain(path, managedRoot, trustedAnchor); if (!c.ok) throw new Error(c.reason); }
+  if (expectedParentRealpath != null && (await parentRealpath(path)) !== expectedParentRealpath) {
+    throw new Error("Parent realpath changed before write; refusing.");
+  }
+}
+export async function openNoFollow(path, flags) {
+  let beforeIno = null;
+  if (existsSync(path)) {
+    const stats = await lstat(path);
+    if (stats.isSymbolicLink()) throw new Error("Path is a symlink; refusing.");
+    beforeIno = stats.ino;
+  }
+  const handle = await open(path, flags | openNoFollowFlag);
+  try {
+    const after = await lstat(path);
+    if (after.isSymbolicLink()) throw new Error("Path became a symlink during open; refusing.");
+    if (beforeIno != null && (after.ino !== beforeIno || (await handle.stat()).ino !== beforeIno)) {
+      throw new Error("Path changed during open; refusing.");
+    }
+  } catch (error) { await handle.close(); throw error; }
+  return handle;
+}
+export async function snapshotRegularFile(path) {
+  const handle = await openNoFollow(path, fsConstants.O_RDONLY);
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile()) throw new Error("Path is not a regular file.");
+    const bytes = await handle.readFile();
+    const again = await handle.stat();
+    if (!again.isFile() || again.ino !== stats.ino || again.size !== stats.size) {
+      throw new Error("File changed during read; refusing.");
+    }
+    return { bytes, hash: hashBuffer(bytes), ino: stats.ino, size: stats.size };
+  } finally {
+    await handle.close();
+  }
+}
+export async function readRegularFile(path) {
+  return (await snapshotRegularFile(path)).bytes;
+}
+export async function hashRegularFile(path) {
+  return (await snapshotRegularFile(path)).hash;
+}
+export async function replaceRegularFile(destinationPath, bytes, {
+  expectedIno = null, expectedHash = null, createExclusive = false,
+  managedRoot = null, expectedParentRealpath = null, trustedAnchor = null
+} = {}) {
+  const symlink = await refuseSymlink(destinationPath, "Destination");
+  if (symlink) throw new Error(symlink);
+  const tempPath = join(dirname(destinationPath), `.sdd-write-${randomBytes(16).toString("hex")}.tmp`);
+  const handle = await open(tempPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+  try { await handle.writeFile(bytes); await handle.sync(); }
+  finally { await handle.close(); }
+  const gate = { managedRoot, expectedParentRealpath, trustedAnchor };
+  try {
+    if (createExclusive) {
+      await assertMutableTarget(destinationPath, gate);
+      if (existsSync(destinationPath)) throw new Error("Destination appeared before create; refusing overwrite.");
+      await link(tempPath, destinationPath);
+      await rm(tempPath, { force: true });
+      return;
+    }
+    if (expectedIno != null || expectedHash != null) {
+      const current = await snapshotRegularFile(destinationPath);
+      if (expectedIno != null && current.ino !== expectedIno) throw new Error("Destination inode changed before write; refusing.");
+      if (expectedHash != null && current.hash !== expectedHash) throw new Error("Destination hash changed before write; refusing.");
+    }
+    if (beforeFinalGateForTests) await beforeFinalGateForTests(destinationPath);
+    await assertMutableTarget(destinationPath, gate);
+    await rename(tempPath, destinationPath);
+  } catch (error) {
+    await rm(tempPath, { force: true });
+    throw error;
+  }
+}
+async function restoreTombExclusive(path, tomb) {
+  try { await link(tomb, path); await rm(tomb, { force: true }); return { restored: true }; }
+  catch (error) { return { restored: false, tombPath: tomb, reason: error.message }; }
+}
+export async function deleteRegularFileIfHash(path, expectedHash, {
+  managedRoot = null, expectedParentRealpath = null, trustedAnchor = null
+} = {}) {
+  const symlink = await refuseSymlink(path, "Path");
+  if (symlink) return { ok: false, reason: symlink };
+  let snap;
+  try { snap = await snapshotRegularFile(path); }
+  catch (error) { return { ok: false, reason: error.message }; }
+  if (snap.hash !== expectedHash) {
+    return { ok: true, skipped: true, reason: "Created file edited after apply; refusing delete." };
+  }
+  const tomb = join(dirname(path), `.sdd-del-${randomBytes(16).toString("hex")}.tmp`);
+  try {
+    await assertMutableTarget(path, { managedRoot, expectedParentRealpath, trustedAnchor });
+    await rename(path, tomb);
+    if (afterTombRenameForTests) await afterTombRenameForTests(path, tomb);
+  } catch (error) { return { ok: false, reason: error.message }; }
+  try {
+    const moved = await snapshotRegularFile(tomb);
+    if (moved.ino !== snap.ino || moved.hash !== expectedHash) {
+      const recovery = await restoreTombExclusive(path, tomb);
+      return { ok: false, tombPath: recovery.restored ? null : recovery.tombPath,
+        reason: recovery.restored ? "File swapped before delete; refusing."
+          : `File swapped before delete; tomb retained at ${recovery.tombPath}` };
+    }
+    await rm(tomb, { force: true });
+    return { ok: true, skipped: false };
+  } catch (error) {
+    const recovery = await restoreTombExclusive(path, tomb);
+    return { ok: false, tombPath: recovery.restored ? null : recovery.tombPath,
+      reason: recovery.restored ? error.message : `${error.message}; tomb retained at ${recovery.tombPath}` };
+  }
+}

package/src/global/integrations/sdd-lifecycle.js

@@ -0,0 +1,84 @@
+import { ensureIntegrationProvidersRegistered } from "./index.js";
+import { requireIntegrationProvider } from "./provider-registry.js";
+import { SDD_MANAGED_AGENT_IDS } from "./sdd-destinations.js";
+import { normalizeSddState, recordSddMaterialization } from "./sdd-state.js";
+
+function skipped(reason) {
+  return {
+    status: "skipped",
+    reason,
+    partial: false,
+    conflicts: [],
+    receipt: null,
+    sessionRefreshRequired: false,
+    applied: false,
+    cancelled: false,
+    dryRun: false
+  };
+}
+
+/** Lifecycle materialization via sdd-core.apply; persona frozen; no second consent prompt. */
+export async function applySddLifecycle({
+  homeDir,
+  packageRoot,
+  agentIds = [],
+  componentIds = [],
+  dryRun = false,
+  priorSdd = null,
+  yes = true
+} = {}) {
+  if (!componentIds.includes("sdd-core")) return skipped("sdd-core not selected");
+  const managed = agentIds.filter((id) => SDD_MANAGED_AGENT_IDS.includes(id));
+  if (!managed.length) return skipped("no managed target agents");
+
+  ensureIntegrationProvidersRegistered();
+  const provider = requireIntegrationProvider("sdd-core");
+  const sdd = normalizeSddState(priorSdd);
+  const trackedFiles = Object.fromEntries(sdd.files.map((file) => [file.destinationPath, file.hash]));
+  const result = await provider.apply({
+    requestedAgentIds: managed,
+    detectedAgentIds: managed,
+    homeDir,
+    packageRoot,
+    persona: sdd.persona,
+    personaAgentIds: sdd.personaAgentIds,
+    preservePersona: true,
+    trackedFiles,
+    dryRun,
+    yes: dryRun ? false : yes,
+    json: true
+  });
+
+  const receipt = result.receipt ?? null;
+  return {
+    status: dryRun
+      ? "planned"
+      : (receipt?.partial ? "partial" : (result.applied ? "applied" : (receipt ? "failed" : "skipped"))),
+    reason: result.cancelled ? "cancelled" : undefined,
+    partial: Boolean(receipt?.partial),
+    conflicts: result.conflicts ?? receipt?.conflicts ?? [],
+    receipt,
+    sessionRefreshRequired: Boolean(result.sessionRefreshRequired),
+    summary: result.summary ?? null,
+    persona: result.persona ?? sdd.persona,
+    personaAgentIds: result.personaTransition?.after ?? sdd.personaAgentIds,
+    applied: Boolean(result.applied),
+    cancelled: Boolean(result.cancelled),
+    dryRun: Boolean(dryRun)
+  };
+}
+
+/** Persist receipt into SDD state only for ok/partial; otherwise keep prior block. */
+export function nextSddState(priorSdd, lifecycle) {
+  const prior = normalizeSddState(priorSdd);
+  if (!lifecycle?.receipt || lifecycle.dryRun) return prior;
+  if (!lifecycle.receipt.ok && !lifecycle.receipt.partial) return prior;
+  return recordSddMaterialization({ sdd: prior }, { receipt: lifecycle.receipt }).sdd;
+}
+
+export function aggregateSessionRefreshRequired(result, sdd) {
+  const managedChanged = (result.configsCreated?.length ?? 0)
+    + (result.configsUpdated?.length ?? 0)
+    + (result.configsRepaired?.length ?? 0) > 0;
+  return Boolean(sdd?.sessionRefreshRequired) || managedChanged;
+}