@xiongxianfei/rigorloop 0.1.5 → 0.3.0

package/dist/bin/rigorloop.js

@@ -7,16 +7,13 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { EXIT, exitCodeForResult } from "../lib/command-result.js";
+import { adapterDescriptor, supportedAdapterNames } from "../lib/adapters.js";
 import { parseLockfile, serializeLockfile, sha256NormalizedText } from "../lib/lockfile.js";
 import { buildNewChangeDraft, parseNewChangeArgs } from "../lib/new-change.js";
 import { runNewChangePlan } from "../lib/new-change-filesystem.js";
 import { validateOfficialArchiveUrl } from "../lib/official-archive-url.js";
 
-const ADAPTER = "codex";
-const AGENTS_ROOT = ".agents";
-const INSTALL_ROOT = ".agents/skills";
 const LOCKFILE_PATH = "rigorloop.lock";
-const DIRECTORY_PLAN = [AGENTS_ROOT, INSTALL_ROOT];
 
 function packageInfo() {
   const here = dirname(fileURLToPath(import.meta.url));
@@ -39,6 +36,8 @@ function parseFlags(args) {
     noColor: Boolean(process.env.NO_COLOR),
     dryRun: false,
     adapter: undefined,
+    adapterOptionUsed: false,
+    writeState: false,
     fromArchiveProvided: false,
     fromArchive: undefined,
     force: false,
@@ -58,10 +57,13 @@ function parseFlags(args) {
     } else if (arg === "--dry-run") {
       flags.dryRun = true;
     } else if (arg === "--adapter") {
+      flags.adapterOptionUsed = true;
       if (args[index + 1] && !args[index + 1].startsWith("--")) {
         flags.adapter = args[index + 1];
         index += 1;
       }
+    } else if (arg === "--write-state") {
+      flags.writeState = true;
     } else if (arg === "--from-archive") {
       flags.fromArchiveProvided = true;
       if (args[index + 1] && !args[index + 1].startsWith("--")) {
@@ -113,12 +115,13 @@ function usage() {
 Usage:
   rigorloop --help
   rigorloop version
-  rigorloop init --adapter codex [--dry-run] [--json]
+  rigorloop init codex|claude|opencode [--write-state] [--dry-run] [--json]
   rigorloop new-change <change-id> --title <title> [--dry-run] [--json]
 
 Commands:
   version                 Print package name and version.
-  init --adapter codex    Initialize the first-slice Codex adapter plan.
+  init codex|claude|opencode
+                          Initialize verified target support.
   new-change              Plan a change metadata scaffold.
 `;
 }
@@ -127,43 +130,183 @@ function releaseForPackage(version) {
   return `v${version}`;
 }
 
-function sourceForFlags(flags, info) {
+function sourceForFlags(flags, info, descriptor) {
   if (flags.fromArchiveProvided) {
     return {
       type: "local-archive",
-      archive: flags.fromArchive,
+      archive: basename(flags.fromArchive),
+      inputPath: flags.fromArchive,
     };
   }
 
   return {
     type: "release-archive",
     release: releaseForPackage(info.version),
-    archive: `rigorloop-adapter-codex-${releaseForPackage(info.version)}.zip`,
+    archive: descriptor.archiveName(releaseForPackage(info.version)),
   };
 }
 
-function manifestContent(info, source) {
+function manifestTargetBlock(source, descriptor, artifact) {
   const sourceLines =
     source.type === "local-archive"
       ? [`      type: local-archive`, `      archive: "${source.archive}"`]
       : [`      type: release-archive`, `      release: "${source.release}"`];
+  const installRoots = rootsForArtifact(descriptor, artifact);
+  const rootLines =
+    descriptor.name !== "opencode" && Object.keys(installRoots).length === 1
+      ? [`    install_root: "${Object.values(installRoots)[0]}"`]
+      : [
+          `    install_roots:`,
+          ...Object.entries(installRoots).map(([role, root]) => `      ${role}: "${root}"`),
+        ];
 
-  return `schema_version: 1
+  return `  - target: ${descriptor.name}
+${rootLines.join("\n")}
+    source:
+${sourceLines.join("\n")}`;
+}
+
+function parseManifestAdapterBlocks(content) {
+  const isLegacySchema = content.includes("schema_version: 1") && content.includes("adapters:");
+  const isTargetSchema = content.includes("schema_version: 2") && content.includes("targets:");
+  if (!isLegacySchema && !isTargetSchema) {
+    return { error: { code: "invalid-config", message: "Existing rigorloop.yaml is not compatible with the init contract." } };
+  }
+  const lines = content.replace(/\r\n?/g, "\n").split("\n");
+  const listKey = isTargetSchema ? "targets:" : "adapters:";
+  const entryPrefix = isTargetSchema ? "  - target: " : "  - name: ";
+  const adapterStart = lines.findIndex((line) => line === listKey);
+  const blocks = [];
+  let current = [];
+  for (const line of lines.slice(adapterStart + 1)) {
+    if (line.startsWith(entryPrefix)) {
+      if (current.length) {
+        blocks.push(current);
+      }
+      current = [line];
+    } else if (current.length) {
+      current.push(line);
+    } else if (line.trim() !== "") {
+      return { error: { code: "invalid-config", message: "Existing rigorloop.yaml has malformed adapter entries." } };
+    }
+  }
+  if (current.length) {
+    blocks.push(current);
+  }
+  const adapters = [];
+  for (const block of blocks) {
+    const name = block[0].slice(entryPrefix.length).trim();
+    const descriptor = adapterDescriptor(name);
+    if (!descriptor) {
+      return { error: { code: "invalid-config", message: `Existing rigorloop.yaml includes unsupported adapter ${name}.` } };
+    }
+    const blockText = isTargetSchema ? block.join("\n").replace(/\n+$/, "") : block.join("\n").replace(/\n+$/, "").replace(/^  - name:/, "  - target:");
+    adapters.push({ name, block: blockText, roots: manifestBlockRoots(blockText) });
+  }
+  return { adapters };
+}
+
+function manifestBlockRoots(block) {
+  const roots = [];
+  let inInstallRoots = false;
+  for (const line of block.split("\n")) {
+    const singleRootMatch = line.match(/^    install_root:\s+"([^"]+)"\s*$/);
+    if (singleRootMatch) {
+      roots.push(singleRootMatch[1]);
+      inInstallRoots = false;
+      continue;
+    }
+    if (line === "    install_roots:") {
+      inInstallRoots = true;
+      continue;
+    }
+    if (/^    [A-Za-z_][A-Za-z0-9_-]*:/.test(line)) {
+      inInstallRoots = false;
+    }
+    const rootMatch = inInstallRoots ? line.match(/^      [A-Za-z_][A-Za-z0-9_-]*:\s+"([^"]+)"\s*$/) : undefined;
+    if (rootMatch) {
+      roots.push(rootMatch[1]);
+    }
+  }
+  return roots;
+}
+
+function manifestContent(info, source, descriptor, existingContent) {
+  const selectedBlock = manifestTargetBlock(source, descriptor, source.artifact);
+  const parsed = existingContent ? parseManifestAdapterBlocks(existingContent) : undefined;
+  const preserved =
+    parsed && !parsed.error
+      ? parsed.adapters
+          .filter((entry) => entry.name !== descriptor.name)
+          .map((entry) => entry.block.replace(/^  - name:/, "  - target:"))
+      : [];
+  return `schema_version: 2
 rigorloop:
   package: "${info.name}"
   package_version: "${info.version}"
-adapters:
-  - name: codex
-    install_root: "${INSTALL_ROOT}"
-    source:
-${sourceLines.join("\n")}
+targets:
+${[...preserved, selectedBlock].join("\n")}
 `;
 }
 
-function plannedLockfile(info, source, manifest) {
+function rootsForArtifact(descriptor, artifact) {
+  if (artifact?.install_roots) {
+    return artifact.install_roots;
+  }
+  if (artifact?.install_root) {
+    return { skills: artifact.install_root };
+  }
+  return descriptor.installRoots;
+}
+
+function rootHashesForArtifact(descriptor, artifact) {
+  if (artifact?.root_hashes) {
+    return artifact.root_hashes;
+  }
+  return Object.fromEntries(
+    Object.keys(rootsForArtifact(descriptor, artifact)).map((role) => [
+      role,
+      {
+        tree_sha256: artifact?.tree_sha256 ?? "<planned-after-install>",
+        file_count: artifact?.file_count ?? "<planned-after-install>",
+      },
+    ]),
+  );
+}
+
+function usesMultiRootLockfile(descriptor, artifact) {
+  return descriptor.name === "opencode" || Object.keys(rootsForArtifact(descriptor, artifact)).length > 1;
+}
+
+function lockfileEntryForAdapter(info, source, artifact, descriptor, rootHashes = rootHashesForArtifact(descriptor, artifact)) {
+  const entry = {
+    target: descriptor.name,
+    release: releaseForPackage(info.version),
+    source: source.type,
+    archive: source.archive,
+    archive_sha256: artifact?.sha256 ?? "<planned>",
+    tree_hash_algorithm: "rigorloop-tree-hash-v1",
+  };
+  if (usesMultiRootLockfile(descriptor, artifact)) {
+    return {
+      ...entry,
+      installed_roots: rootsForArtifact(descriptor, artifact),
+      root_hashes: rootHashes,
+    };
+  }
+  const [role] = Object.keys(rootsForArtifact(descriptor, artifact));
+  return {
+    ...entry,
+    installed_root: rootsForArtifact(descriptor, artifact)[role],
+    tree_sha256: rootHashes[role].tree_sha256,
+    file_count: rootHashes[role].file_count,
+  };
+}
+
+function plannedLockfile(info, source, manifest, descriptor) {
   const artifact = source.artifact;
   return {
-    schema_version: 1,
+    schema_version: 3,
     rigorloop: {
       package: info.name,
       version: info.version,
@@ -173,26 +316,39 @@ function plannedLockfile(info, source, manifest) {
       sha256: sha256NormalizedText(manifest),
     },
     generated: {
-      adapters: [
-        {
-          adapter: ADAPTER,
-          release: releaseForPackage(info.version),
-          source: source.type,
-          archive: source.type === "local-archive" ? basename(source.archive) : source.archive,
-          archive_sha256: artifact?.sha256 ?? "<planned>",
-          installed_root: INSTALL_ROOT,
-          tree_hash_algorithm: "rigorloop-tree-hash-v1",
-          tree_sha256: artifact?.tree_sha256 ?? "<planned-after-install>",
-          file_count: "<planned-after-install>",
-        },
-      ],
+      targets: [lockfileEntryForAdapter(info, source, artifact, descriptor)],
     },
   };
 }
 
-function lockfileForVerifiedInstall(info, source, manifest, artifact, treeHash, fileCount) {
+function existingLockfileEntries(selectedAdapter) {
+  const lockfileAbsolutePath = resolve(process.cwd(), LOCKFILE_PATH);
+  if (!existsSync(lockfileAbsolutePath)) {
+    return [];
+  }
+  const parsed = parseLockfile(readFileSync(lockfileAbsolutePath, "utf8"));
+  if (!parsed.ok) {
+    return [];
+  }
+  const entries = parsed.lockfile.generated.targets ?? parsed.lockfile.generated.adapters;
+  return entries
+    .filter((entry) => (entry.target ?? entry.adapter) !== selectedAdapter)
+    .map((entry) => {
+      if (entry.target) {
+        return entry;
+      }
+      const { adapter, ...rest } = entry;
+      return { target: adapter, ...rest };
+    });
+}
+
+function lockfileForVerifiedInstall(info, source, manifest, artifact, rootHashes, descriptor) {
+  const adapters = [
+    ...existingLockfileEntries(descriptor.name),
+    lockfileEntryForAdapter(info, source, artifact, descriptor, rootHashes),
+  ];
   return {
-    schema_version: 1,
+    schema_version: 3,
     rigorloop: {
       package: info.name,
       version: info.version,
@@ -202,28 +358,19 @@ function lockfileForVerifiedInstall(info, source, manifest, artifact, treeHash,
       sha256: sha256NormalizedText(manifest),
     },
     generated: {
-      adapters: [
-        {
-          adapter: ADAPTER,
-          release: releaseForPackage(info.version),
-          source: source.type,
-          archive: source.type === "local-archive" ? basename(source.archive) : source.archive,
-          archive_sha256: artifact.sha256,
-          installed_root: INSTALL_ROOT,
-          tree_hash_algorithm: "rigorloop-tree-hash-v1",
-          tree_sha256: treeHash,
-          file_count: fileCount,
-        },
-      ],
+      targets: adapters,
     },
   };
 }
 
-function compatibleManifest(content) {
+function compatibleManifest(content, descriptor, artifact) {
+  if (descriptor.name === "opencode" && !rootsForArtifact(descriptor, artifact).commands && content.includes(".opencode/commands")) {
+    return false;
+  }
   return (
     content.includes("schema_version: 1") &&
-    content.includes("name: codex") &&
-    content.includes(`install_root: "${INSTALL_ROOT}"`)
+    content.includes(`name: ${descriptor.name}`) &&
+    content.includes(`"${Object.values(rootsForArtifact(descriptor, artifact))[0]}"`)
   );
 }
 
@@ -234,8 +381,11 @@ function pathState(path) {
   return statSync(path).isDirectory() ? "directory" : "file";
 }
 
-function directoryKind(path) {
-  return path === AGENTS_ROOT ? "codex-agent-root" : "codex-install-root";
+function directoryKind(path, descriptor, artifact) {
+  if (Object.values(rootsForArtifact(descriptor, artifact)).includes(path)) {
+    return `${descriptor.name}-install-root`;
+  }
+  return `${descriptor.name}-adapter-root`;
 }
 
 function sha256(bytes) {
@@ -338,11 +488,77 @@ function loadJsonFile(path) {
 async function fetchBytes(url) {
   const response = await fetch(url);
   if (!response.ok) {
-    throw new Error(`HTTP ${response.status}`);
+    throw Object.assign(new Error(`HTTP ${response.status}`), { downloadFailureClass: "http-status" });
   }
   return Buffer.from(await response.arrayBuffer());
 }
 
+const PROXY_ENV_VAR_ALLOWLIST = ["HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy"];
+const DOWNLOAD_FAILURE_CLASSES = new Set(["dns", "tls", "timeout", "http-status", "proxy", "network", "unknown"]);
+
+function detectedProxyEnvVars(env = process.env) {
+  return PROXY_ENV_VAR_ALLOWLIST.filter((name) => Object.prototype.hasOwnProperty.call(env, name) && env[name]);
+}
+
+function nodeEnvProxyStatus(env = process.env, execArgv = process.execArgv) {
+  const nodeOptions = String(env.NODE_OPTIONS ?? "");
+  const useEnvProxy = String(env.NODE_USE_ENV_PROXY ?? "").toLowerCase();
+  // CR-M4-R1-F1: Node can enable fetch env-proxy via env vars or the runtime flag.
+  if (nodeOptions.includes("--use-env-proxy") || execArgv.includes("--use-env-proxy") || ["1", "true", "yes"].includes(useEnvProxy)) {
+    return "enabled";
+  }
+  if (detectedProxyEnvVars(env).length > 0) {
+    return "disabled";
+  }
+  return "unknown";
+}
+
+function downloadFailureClass(error) {
+  if (DOWNLOAD_FAILURE_CLASSES.has(error?.downloadFailureClass)) {
+    return error.downloadFailureClass;
+  }
+  const code = String(error?.code ?? error?.cause?.code ?? "").toUpperCase();
+  const message = String(error?.message ?? "").toLowerCase();
+  if (["ENOTFOUND", "EAI_AGAIN"].includes(code)) {
+    return "dns";
+  }
+  if (code.includes("CERT") || code.includes("TLS") || message.includes("certificate") || message.includes("tls")) {
+    return "tls";
+  }
+  if (code.includes("TIMEOUT") || code === "ABORT_ERR" || message.includes("timeout") || message.includes("timed out")) {
+    return "timeout";
+  }
+  if (code.includes("PROXY") || message.includes("proxy")) {
+    return "proxy";
+  }
+  if (["ECONNRESET", "ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH"].includes(code) || message.includes("fetch failed")) {
+    return "network";
+  }
+  return "unknown";
+}
+
+function downloadFailureDiagnostics(error, artifact, descriptor, metadata) {
+  return {
+    adapter: descriptor.name,
+    release: metadata.release.version,
+    archive_url: artifact.url,
+    download_failure_class: downloadFailureClass(error),
+    node_env_proxy_status: nodeEnvProxyStatus(),
+    proxy_env_vars_detected: detectedProxyEnvVars(),
+  };
+}
+
+function downloadFailureBlocker(error, artifact, descriptor, metadata) {
+  const diagnostics = downloadFailureDiagnostics(error, artifact, descriptor, metadata);
+  return {
+    code: "release-download-failed",
+    message: `Network download failed for adapter ${descriptor.name} release ${metadata.release.version} (failure class ${diagnostics.download_failure_class}).`,
+    path: artifact.url,
+    next_action: `Download ${artifact.url} and rerun with --from-archive ./${artifact.archive}.`,
+    diagnostics,
+  };
+}
+
 function parseVerifiedMetadataBytes(bytes, expectedSha256) {
   const actualSha256 = sha256(bytes);
   if (actualSha256 !== expectedSha256) {
@@ -382,7 +598,15 @@ function isSha256(value) {
   return typeof value === "string" && /^[0-9a-f]{64}$/i.test(value);
 }
 
-function validateMetadata(metadata, info) {
+function releaseListedForSkillsOnlyCompatibility(marker, release) {
+  if (!marker) {
+    return false;
+  }
+  const releases = Array.isArray(marker) ? marker : marker.releases;
+  return Array.isArray(releases) && releases.includes(release);
+}
+
+function validateMetadata(metadata, info, descriptor) {
   const release = releaseForPackage(info.version);
   if (!metadata || metadata.schema_version !== 1) {
     return { error: { code: "metadata-invalid", message: "Adapter metadata schema_version must be 1." } };
@@ -407,26 +631,76 @@ function validateMetadata(metadata, info) {
   if (!isNonEmptyString(metadata.validation?.command)) {
     return { error: { code: "metadata-invalid", message: "Adapter metadata validation command is missing." } };
   }
-  const artifact = metadata.artifacts?.find((entry) => entry.adapter === ADAPTER);
+  const artifact = metadata.artifacts?.find((entry) => entry.adapter === descriptor.name);
   if (!artifact) {
-    return { blocker: metadataBlocker("adapter-unknown", "Adapter metadata does not include Codex.") };
+    return { blocker: metadataBlocker("metadata-unavailable", `Adapter metadata does not include ${descriptor.displayName}.`) };
   }
-  if (
-    !isNonEmptyString(artifact.archive) ||
-    !isNonEmptyString(artifact.url) ||
-    !isSha256(artifact.sha256) ||
-    !Number.isInteger(artifact.size_bytes) ||
-    artifact.size_bytes < 0 ||
-    !isSha256(artifact.tree_sha256)
-  ) {
-    return { error: { code: "metadata-invalid", message: "Codex adapter artifact metadata is incomplete." } };
-  }
-  if ((artifact.install_root ?? "").replace(/\/$/, "") !== INSTALL_ROOT) {
-    return { error: { code: "metadata-invalid", message: "Codex adapter install root is not .agents/skills." } };
+  if (!isNonEmptyString(artifact.archive) || !isNonEmptyString(artifact.url) || !isSha256(artifact.sha256) || !Number.isInteger(artifact.size_bytes) || artifact.size_bytes < 0) {
+    return { error: { code: "metadata-invalid", message: `${descriptor.displayName} adapter artifact metadata is incomplete.` } };
   }
   if (artifact.tree_hash_algorithm && artifact.tree_hash_algorithm !== "rigorloop-tree-hash-v1") {
     return { error: { code: "metadata-invalid", message: "Unsupported tree hash algorithm in adapter metadata." } };
   }
+  if (artifact.install_roots || artifact.root_hashes) {
+    if (!artifact.install_roots || !artifact.root_hashes) {
+      return { error: { code: "metadata-invalid", message: `${descriptor.displayName} multi-root metadata is incomplete.` } };
+    }
+    for (const [role, root] of Object.entries(artifact.install_roots)) {
+      if (descriptor.installRoots[role] !== root) {
+        return { error: { code: "metadata-invalid", message: `${descriptor.displayName} adapter install root for ${role} is not supported.` } };
+      }
+      const rootHash = artifact.root_hashes[role];
+      if (!rootHash || !isSha256(rootHash.tree_sha256) || !Number.isInteger(rootHash.file_count) || rootHash.file_count < 0) {
+        return { error: { code: "metadata-invalid", message: `${descriptor.displayName} root hash metadata is incomplete.` } };
+      }
+    }
+  } else {
+    if (!isSha256(artifact.tree_sha256) || !Number.isInteger(artifact.file_count) || artifact.file_count < 0) {
+      return { error: { code: "metadata-invalid", message: `${descriptor.displayName} adapter single-root metadata is incomplete.` } };
+    }
+    if ((artifact.install_root ?? "").replace(/\/$/, "") !== descriptor.primaryInstallRoot()) {
+      return { error: { code: "metadata-invalid", message: `${descriptor.displayName} adapter install root is not ${descriptor.primaryInstallRoot()}.` } };
+    }
+  }
+  if (artifact.command_aliases?.opencode) {
+    if (descriptor.name !== "opencode" || !artifact.install_roots?.commands) {
+      return { error: { code: "metadata-invalid", message: "opencode command alias metadata requires the opencode commands root." } };
+    }
+    const aliasPaths = opencodeCommandAliasPaths(artifact);
+    if (
+      !Number.isInteger(artifact.command_aliases.opencode.count) ||
+      !Array.isArray(aliasPaths) ||
+      artifact.command_aliases.opencode.count !== aliasPaths.length ||
+      aliasPaths.some((aliasPath) => !isNonEmptyString(aliasPath) || !aliasPath.startsWith(`${descriptor.installRoots.commands}/`))
+    ) {
+      return { error: { code: "metadata-invalid", message: "opencode command alias metadata is incomplete." } };
+    }
+  }
+  // CR-M3-R2-F1: opencode commands root is valid only with declared command aliases.
+  if (descriptor.name === "opencode" && artifact.install_roots?.commands && !artifact.command_aliases?.opencode) {
+    return {
+      blocker: metadataBlocker(
+        "opencode-command-aliases-missing",
+        "Opencode commands root metadata requires command_aliases.opencode.",
+        artifact.archive,
+        "Use opencode metadata that declares command aliases, or use explicitly compatible skills-only metadata without the commands root.",
+      ),
+    };
+  }
+  // CR-M3-R1-F1: skills-only opencode compatibility must be explicit in trusted metadata.
+  if (descriptor.name === "opencode" && !artifact.command_aliases?.opencode && !rootsForArtifact(descriptor, artifact).commands) {
+    const marker = artifact.skills_only_compatibility ?? metadata.compatibility?.opencode_skills_only;
+    if (!releaseListedForSkillsOnlyCompatibility(marker, release)) {
+      return {
+        blocker: metadataBlocker(
+          "opencode-skills-only-compatibility-unmarked",
+          "Opencode skills-only archive metadata is not explicitly marked compatible.",
+          artifact.archive,
+          "Use an opencode archive with command alias metadata or bundled trusted skills-only compatibility metadata.",
+        ),
+      };
+    }
+  }
   return { artifact };
 }
 
@@ -500,36 +774,66 @@ function parseZipEntries(buffer) {
   return entries;
 }
 
-function unsafePathCode(name) {
+function unsafePathCode(name, descriptor, artifact) {
   if (!name || name.startsWith("/") || name.startsWith("\\") || /^[A-Za-z]:/.test(name) || name.includes("\\")) {
     return "archive-path-traversal";
   }
   if (name.split("/").some((part) => part === ".." || part === "")) {
     return "archive-path-traversal";
   }
-  if (!name.startsWith(`${INSTALL_ROOT}/`)) {
+  const allowedRoots = Object.values(rootsForArtifact(descriptor, artifact));
+  if (!allowedRoots.some((root) => name.startsWith(`${root}/`))) {
     return "archive-install-root-invalid";
   }
   return undefined;
 }
 
 function isArchiveSupportEntry(name) {
-  return name === "AGENTS.md";
+  return name === "AGENTS.md" || name === "CLAUDE.md";
 }
 
-function fileRowsForTree(entries) {
+function fileRowsForTreeRoot(entries, installRoot) {
   return entries
-    .filter((entry) => !entry.directory)
+    .filter((entry) => !entry.directory && entry.name.startsWith(`${installRoot}/`))
     .map((entry) => {
-      const relativePath = entry.name.slice(`${INSTALL_ROOT}/`.length);
+      const relativePath = entry.name.slice(`${installRoot}/`.length);
       const bytes = relativePath.endsWith(".md") ? normalizeText(entry.bytes) : entry.bytes;
       return [relativePath, sha256(bytes)];
     })
     .sort(([left], [right]) => left.localeCompare(right));
 }
 
-function treeHashForEntries(entries) {
-  return treeHashForRows(fileRowsForTree(entries));
+function opencodeCommandAliasPaths(artifact) {
+  const aliases = artifact?.command_aliases?.opencode;
+  if (!aliases) {
+    return undefined;
+  }
+  if (Array.isArray(aliases.paths)) {
+    return aliases.paths;
+  }
+  if (aliases.aliases && typeof aliases.aliases === "object") {
+    return Object.values(aliases.aliases);
+  }
+  return [];
+}
+
+function treeHashForEntries(entries, descriptor) {
+  return treeHashForRows(fileRowsForTreeRoot(entries, descriptor.primaryInstallRoot()));
+}
+
+function rootHashesForEntries(entries, descriptor, artifact) {
+  return Object.fromEntries(
+    Object.entries(rootsForArtifact(descriptor, artifact)).map(([role, root]) => {
+      const rows = fileRowsForTreeRoot(entries, root);
+      return [
+        role,
+        {
+          tree_sha256: treeHashForRows(rows),
+          file_count: rows.length,
+        },
+      ];
+    }),
+  );
 }
 
 function treeHashForRows(rows) {
@@ -573,22 +877,26 @@ function treeHashForFilesystem(root) {
   };
 }
 
-function currentCodexLockfileEntry() {
+function currentLockfileEntries() {
   const lockfileAbsolutePath = resolve(process.cwd(), LOCKFILE_PATH);
   if (!existsSync(lockfileAbsolutePath)) {
-    return undefined;
+    return [];
   }
   const parsed = parseLockfile(readFileSync(lockfileAbsolutePath, "utf8"));
   if (!parsed.ok) {
-    return undefined;
+    return [];
   }
-  return parsed.lockfile.generated.adapters.find((entry) => entry.adapter === ADAPTER && entry.installed_root === INSTALL_ROOT);
+  return parsed.lockfile.generated.targets ?? parsed.lockfile.generated.adapters;
+}
+
+function currentLockfileEntry(descriptor) {
+  return currentLockfileEntries().find((entry) => (entry.target ?? entry.adapter) === descriptor.name);
 }
 
 function installedTreeMismatchError(actualTree, expectedTreeHash, expectedFileCount) {
   return {
     code: "installed-tree-mismatch",
-    message: "Installed Codex adapter tree does not match trusted metadata.",
+    message: "Installed adapter tree does not match trusted metadata.",
     expected_tree_sha256: expectedTreeHash,
     actual_tree_sha256: actualTree.treeHash,
     expected_file_count: expectedFileCount,
@@ -596,23 +904,29 @@ function installedTreeMismatchError(actualTree, expectedTreeHash, expectedFileCo
   };
 }
 
-function verifyInstalledTree(entries, artifact, { allowMissingOrEmpty = false } = {}) {
-  const expectedRows = fileRowsForTree(entries);
-  const expectedTreeHash = artifact.tree_sha256;
-  const expectedFileCount = expectedRows.length;
+function verifyInstalledTree(entries, artifact, descriptor, { allowMissingOrEmpty = false } = {}) {
+  const expectedRootHashes = rootHashesForEntries(entries, descriptor, artifact);
+  for (const [role, root] of Object.entries(rootsForArtifact(descriptor, artifact))) {
+    const expectedRows = fileRowsForTreeRoot(entries, root);
+    const expectedTreeHash = artifact.root_hashes?.[role]?.tree_sha256 ?? artifact.tree_sha256;
+    const expectedFileCount = artifact.root_hashes?.[role]?.file_count ?? expectedRows.length;
 
-  if (!existsSync(resolve(process.cwd(), INSTALL_ROOT))) {
-    return allowMissingOrEmpty ? { ok: true, expectedRows, expectedFileCount } : { error: installedTreeMismatchError({ treeHash: "<missing>", fileCount: 0 }, expectedTreeHash, expectedFileCount) };
-  }
+    if (!existsSync(resolve(process.cwd(), root))) {
+      if (allowMissingOrEmpty) {
+        continue;
+      }
+      return { error: installedTreeMismatchError({ treeHash: "<missing>", fileCount: 0 }, expectedTreeHash, expectedFileCount) };
+    }
 
-  const actualTree = treeHashForFilesystem(INSTALL_ROOT);
-  if (allowMissingOrEmpty && actualTree.fileCount === 0) {
-    return { ok: true, expectedRows, expectedFileCount };
-  }
-  if (!rowsEqual(actualTree.rows, expectedRows) || actualTree.treeHash !== expectedTreeHash) {
-    return { error: installedTreeMismatchError(actualTree, expectedTreeHash, expectedFileCount) };
+    const actualTree = treeHashForFilesystem(root);
+    if (allowMissingOrEmpty && actualTree.fileCount === 0) {
+      continue;
+    }
+    if (!rowsEqual(actualTree.rows, expectedRows) || actualTree.treeHash !== expectedTreeHash || actualTree.fileCount !== expectedFileCount) {
+      return { error: installedTreeMismatchError(actualTree, expectedTreeHash, expectedFileCount) };
+    }
   }
-  return { ok: true, expectedRows, expectedFileCount, treeHash: actualTree.treeHash };
+  return { ok: true, rootHashes: expectedRootHashes, expectedFileCount: expectedRootHashes.skills?.file_count ?? 0, treeHash: expectedRootHashes.skills?.tree_sha256 };
 }
 
 function generatedOutputConflictBlocker(entries) {
@@ -655,13 +969,29 @@ function lockfileDriftBlocker(lockfileEntry) {
   if (!lockfileEntry) {
     return undefined;
   }
+  if (lockfileEntry.installed_roots) {
+    for (const [role, root] of Object.entries(lockfileEntry.installed_roots)) {
+      const rootHash = lockfileEntry.root_hashes[role];
+      const blocker = lockfileDriftBlocker({
+        adapter: lockfileEntry.adapter,
+        target: lockfileEntry.target,
+        installed_root: root,
+        tree_sha256: rootHash.tree_sha256,
+        file_count: rootHash.file_count,
+      });
+      if (blocker) {
+        return blocker;
+      }
+    }
+    return undefined;
+  }
 
   const rootState = pathState(resolve(process.cwd(), lockfileEntry.installed_root));
   if (rootState === "absent") {
     return {
       code: "generated-output-missing",
       message: "Codex generated output recorded in rigorloop.lock is missing.",
-      adapter: lockfileEntry.adapter,
+      target: lockfileEntry.target ?? lockfileEntry.adapter,
       installed_root: lockfileEntry.installed_root,
       expected_tree_sha256: lockfileEntry.tree_sha256,
       actual_tree_sha256: null,
@@ -682,7 +1012,7 @@ function lockfileDriftBlocker(lockfileEntry) {
     return {
       code: "generated-output-drift",
       message: "Codex generated output differs from rigorloop.lock.",
-      adapter: lockfileEntry.adapter,
+      target: lockfileEntry.target ?? lockfileEntry.adapter,
       installed_root: lockfileEntry.installed_root,
       expected_tree_sha256: lockfileEntry.tree_sha256,
       actual_tree_sha256: actualTree.treeHash,
@@ -695,7 +1025,127 @@ function lockfileDriftBlocker(lockfileEntry) {
   return undefined;
 }
 
-function inspectArchive(archiveBytes, artifact) {
+function lockfileEntryTarget(entry) {
+  return entry.target ?? entry.adapter;
+}
+
+function lockfileEntryRoots(entry) {
+  if (entry.installed_roots) {
+    return Object.values(entry.installed_roots);
+  }
+  return entry.installed_root ? [entry.installed_root] : [];
+}
+
+function rootsOverlap(leftRoots, rightRoots) {
+  return leftRoots.some((left) =>
+    rightRoots.some((right) => left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)),
+  );
+}
+
+function targetRootConflictBlocker(target, path, reason) {
+  return {
+    code: "target-root-conflict",
+    message: reason,
+    target,
+    path,
+    next_action: "Resolve the existing RigorLoop state before running init.",
+  };
+}
+
+function existingStateSafetyBlocker(descriptor, artifact) {
+  const targetRoots = Object.values(rootsForArtifact(descriptor, artifact));
+  const manifestPath = resolve(process.cwd(), "rigorloop.yaml");
+  if (existsSync(manifestPath)) {
+    const parsedManifest = parseManifestAdapterBlocks(readFileSync(manifestPath, "utf8"));
+    if (parsedManifest.error) {
+      return {
+        code: "state-invalid",
+        message: "Existing RigorLoop state is malformed; refusing to mutate target roots.",
+        path: "rigorloop.yaml",
+        next_action: "Fix or move rigorloop.yaml before running init.",
+      };
+    }
+    const selectedEntries = parsedManifest.adapters.filter((entry) => entry.name === descriptor.name);
+    if (selectedEntries.length > 1) {
+      return {
+        code: "duplicate-target-entry",
+        message: `Existing rigorloop.yaml contains duplicate ${descriptor.displayName} target entries.`,
+        path: "rigorloop.yaml",
+        next_action: "Remove duplicate target entries before running init.",
+      };
+    }
+    for (const entry of parsedManifest.adapters) {
+      if (entry.name === descriptor.name && entry.roots.length && !rootsOverlap(entry.roots, targetRoots)) {
+        return targetRootConflictBlocker(
+          descriptor.name,
+          "rigorloop.yaml",
+          `Existing RigorLoop state records target ${descriptor.name} with a conflicting install root.`,
+        );
+      }
+      if (entry.name !== descriptor.name && rootsOverlap(entry.roots, targetRoots)) {
+        return targetRootConflictBlocker(
+          descriptor.name,
+          "rigorloop.yaml",
+          `Existing RigorLoop state records an overlapping install root for target ${entry.name}.`,
+        );
+      }
+    }
+  }
+
+  const lockfilePath = resolve(process.cwd(), LOCKFILE_PATH);
+  if (!existsSync(lockfilePath)) {
+    return undefined;
+  }
+  const parsedLockfile = parseLockfile(readFileSync(lockfilePath, "utf8"));
+  if (!parsedLockfile.ok) {
+    return {
+      code: parsedLockfile.code,
+      message: "Existing RigorLoop lock state is malformed or unsupported; refusing to mutate target roots.",
+      path: LOCKFILE_PATH,
+      next_action: "Fix or move rigorloop.lock before running init.",
+    };
+  }
+  const entries = parsedLockfile.lockfile.generated.targets ?? parsedLockfile.lockfile.generated.adapters;
+  for (const entry of entries) {
+    const entryTarget = lockfileEntryTarget(entry);
+    const entryRoots = lockfileEntryRoots(entry);
+    const selected = entryTarget === descriptor.name;
+    const overlapping = rootsOverlap(entryRoots, targetRoots);
+    if (selected && entryRoots.length && !overlapping) {
+      return targetRootConflictBlocker(
+        descriptor.name,
+        LOCKFILE_PATH,
+        `Existing RigorLoop lock state records target ${descriptor.name} with a conflicting install root.`,
+      );
+    }
+    if (!selected && overlapping) {
+      return targetRootConflictBlocker(
+        descriptor.name,
+        LOCKFILE_PATH,
+        `Existing RigorLoop lock state records an overlapping install root for target ${entryTarget}.`,
+      );
+    }
+    if (selected || overlapping) {
+      const drift = lockfileDriftBlocker(entry);
+      if (drift) {
+        return drift;
+      }
+    }
+  }
+  return undefined;
+}
+
+function firstLockfileDriftBlocker() {
+  for (const entry of currentLockfileEntries()) {
+    const blocker = lockfileDriftBlocker(entry);
+    if (blocker) {
+      return blocker;
+    }
+  }
+  return undefined;
+}
+
+function inspectArchive(archiveBytes, artifact, descriptor) {
   if (artifact.size_bytes !== undefined && archiveBytes.length !== artifact.size_bytes) {
     return { error: { code: "archive-size-mismatch", message: "Archive size does not match metadata." } };
   }
@@ -716,7 +1166,7 @@ function inspectArchive(archiveBytes, artifact) {
     if (isArchiveSupportEntry(entry.name)) {
       continue;
     }
-    const pathCode = unsafePathCode(entry.name);
+    const pathCode = unsafePathCode(entry.name, descriptor, artifact);
     if (pathCode) {
       return { error: { code: pathCode, message: `Archive entry is not allowed: ${entry.name}`, path: entry.name } };
     }
@@ -727,14 +1177,34 @@ function inspectArchive(archiveBytes, artifact) {
   }
 
   const files = installEntries.filter((entry) => !entry.directory);
-  const treeHash = treeHashForEntries(files);
-  if (artifact.tree_sha256 && treeHash !== artifact.tree_sha256) {
-    return { error: { code: "tree-hash-mismatch", message: "Installed tree hash does not match metadata." } };
+  const rootHashes = rootHashesForEntries(files, descriptor, artifact);
+  for (const [role, hash] of Object.entries(rootHashes)) {
+    const expected = artifact.root_hashes?.[role] ?? { tree_sha256: artifact.tree_sha256, file_count: artifact.file_count };
+    if (expected.tree_sha256 && hash.tree_sha256 !== expected.tree_sha256) {
+      return { error: { code: "tree-hash-mismatch", message: "Installed tree hash does not match metadata." } };
+    }
+    if (expected.file_count !== undefined && hash.file_count !== expected.file_count) {
+      return { error: { code: "tree-hash-mismatch", message: "Installed tree file count does not match metadata." } };
+    }
   }
-  return { entries: files, archiveHash, treeHash, fileCount: files.length };
+  if (descriptor.name === "opencode") {
+    for (const aliasPath of opencodeCommandAliasPaths(artifact) ?? []) {
+      if (!files.some((entry) => entry.name === aliasPath)) {
+        return {
+          error: {
+            code: "opencode-command-alias-missing",
+            message: "Declared opencode command alias is missing from archive.",
+            path: aliasPath,
+          },
+        };
+      }
+    }
+  }
+  return { entries: files, archiveHash, rootHashes, treeHash: rootHashes.skills?.tree_sha256, fileCount: rootHashes.skills?.file_count ?? files.length };
 }
 
-function addArchiveActions(plan, entries) {
+function addArchiveActions(plan, entries, descriptor) {
+  const installRoot = descriptor.primaryInstallRoot();
   const directories = new Set();
   for (const entry of entries) {
     const parts = entry.name.split("/");
@@ -770,7 +1240,7 @@ function addArchiveActions(plan, entries) {
     const state = pathState(resolve(process.cwd(), entry.name));
     let existingMatches = false;
     if (state === "file") {
-      const relativePath = entry.name.slice(`${INSTALL_ROOT}/`.length);
+      const relativePath = entry.name.slice(`${installRoot}/`.length);
       const existingBytes = relativePath.endsWith(".md")
         ? normalizeText(readFileSync(resolve(process.cwd(), entry.name)))
         : readFileSync(resolve(process.cwd(), entry.name));
@@ -783,9 +1253,9 @@ function addArchiveActions(plan, entries) {
       status: state === "absent" ? "pending" : existingMatches ? "skipped" : "blocked",
       reason:
         state === "absent"
-          ? "Install verified Codex adapter file."
+          ? `Install verified ${descriptor.displayName} adapter file.`
           : existingMatches
-            ? `${entry.name} already matches verified Codex adapter content.`
+            ? `${entry.name} already matches verified ${descriptor.displayName} adapter content.`
             : `${entry.name} already exists.`,
     });
     plan.artifacts.push({
@@ -804,23 +1274,47 @@ function addArchiveActions(plan, entries) {
   }
 }
 
-function writeArchiveEntries(entries) {
+function writeArchiveEntries(entries, descriptor) {
+  const installRoot = descriptor.primaryInstallRoot();
   for (const entry of entries) {
     const outputPath = resolve(process.cwd(), entry.name);
     mkdirSync(dirname(outputPath), { recursive: true });
-    const relativePath = entry.name.slice(`${INSTALL_ROOT}/`.length);
+    const relativePath = entry.name.slice(`${installRoot}/`.length);
     const bytes = relativePath.endsWith(".md") ? normalizeText(entry.bytes) : entry.bytes;
     writeFileSync(outputPath, bytes);
   }
 }
 
-function planDirectoryActions(flags) {
+function initWarnings(descriptor, artifact) {
+  if (
+    descriptor.name === "opencode" &&
+    artifact &&
+    !artifact.command_aliases?.opencode &&
+    !rootsForArtifact(descriptor, artifact).commands
+  ) {
+    return [
+      {
+        code: "opencode-command-aliases-not-declared",
+        message: "Selected opencode archive metadata does not declare command aliases; only skills were installed.",
+      },
+    ];
+  }
+  return [];
+}
+
+function directoryPlanForRoots(roots) {
+  return [...new Set(Object.values(roots).flatMap((root) => [root.split("/").slice(0, -1).join("/"), root]).filter(Boolean))];
+}
+
+function planDirectoryActions(flags, descriptor, artifact) {
   const actions = [];
   const artifacts = [];
   const blockers = [];
   let parentBlocked = false;
 
-  for (const relativePath of DIRECTORY_PLAN) {
+  const directoryPlan = directoryPlanForRoots(rootsForArtifact(descriptor, artifact));
+  const rootParent = directoryPlan[0];
+  for (const relativePath of directoryPlan) {
     const state = parentBlocked ? "blocked-by-parent" : pathState(resolve(process.cwd(), relativePath));
     if (state === "absent") {
       actions.push({
@@ -831,7 +1325,7 @@ function planDirectoryActions(flags) {
       });
       artifacts.push({
         path: relativePath,
-        kind: directoryKind(relativePath),
+        kind: directoryKind(relativePath, descriptor, artifact),
         status: flags.dryRun ? "planned" : "pending",
       });
     } else if (state === "directory") {
@@ -843,7 +1337,7 @@ function planDirectoryActions(flags) {
       });
       artifacts.push({
         path: relativePath,
-        kind: directoryKind(relativePath),
+        kind: directoryKind(relativePath, descriptor, artifact),
         status: "existing",
       });
     } else {
@@ -853,12 +1347,12 @@ function planDirectoryActions(flags) {
         status: "blocked",
         reason:
           state === "blocked-by-parent"
-            ? `${relativePath} cannot be created because ${AGENTS_ROOT} is not a directory.`
+            ? `${relativePath} cannot be created because ${rootParent} is not a directory.`
             : `${relativePath} exists and is not a directory.`,
       });
       artifacts.push({
         path: relativePath,
-        kind: directoryKind(relativePath),
+        kind: directoryKind(relativePath, descriptor, artifact),
         status: "blocked",
       });
       if (state !== "blocked-by-parent") {
@@ -869,7 +1363,7 @@ function planDirectoryActions(flags) {
           next_action: `Move the existing file before running init.`,
         });
       }
-      if (relativePath === AGENTS_ROOT) {
+      if (relativePath === rootParent) {
         parentBlocked = true;
       }
     }
@@ -887,7 +1381,7 @@ function addLockfilePlan(flags, actions, artifacts, blockers, errors) {
       status: flags.dryRun ? "planned" : "pending",
       reason: flags.dryRun
         ? "Plan durable lockfile content."
-        : "Write durable lockfile after verified Codex adapter install.",
+        : "Write durable lockfile after verified target install.",
     });
     artifacts.push({
       path: LOCKFILE_PATH,
@@ -905,7 +1399,7 @@ function addLockfilePlan(flags, actions, artifacts, blockers, errors) {
       status: flags.dryRun ? "planned" : "pending",
       reason: flags.dryRun
         ? "Plan update to supported rigorloop.lock."
-        : "Update supported rigorloop.lock after verified Codex adapter install.",
+        : "Update supported rigorloop.lock after verified target install.",
     });
     artifacts.push({
       path: LOCKFILE_PATH,
@@ -944,15 +1438,16 @@ function addLockfilePlan(flags, actions, artifacts, blockers, errors) {
   }
 }
 
-function buildInitPlan(flags, artifact) {
+function buildInitPlan(flags, descriptor, artifact) {
   const info = packageInfo();
-  const source = sourceForFlags(flags, info);
+  const source = sourceForFlags(flags, info, descriptor);
   if (artifact) {
     source.artifact = artifact;
   }
   const manifestPath = "rigorloop.yaml";
   const manifestAbsolutePath = resolve(process.cwd(), manifestPath);
-  const manifest = manifestContent(info, source);
+  const existingManifest = existsSync(manifestAbsolutePath) ? readFileSync(manifestAbsolutePath, "utf8") : undefined;
+  const manifest = flags.writeState ? manifestContent(info, source, descriptor, existingManifest) : undefined;
   const actions = [];
   const artifacts = [];
   const blockers = [];
@@ -963,59 +1458,67 @@ function buildInitPlan(flags, artifact) {
       code: "invalid-archive-path",
       message: "Missing required value for --from-archive.",
       path: "--from-archive",
-      next_action: "Provide an existing Codex adapter archive path or omit --from-archive.",
+      next_action: `Provide an existing ${descriptor.displayName} adapter archive path or omit --from-archive.`,
     });
   } else if (flags.fromArchiveProvided && !existsSync(resolve(process.cwd(), flags.fromArchive))) {
     errors.push({
       code: "invalid-archive-path",
       message: `Local archive path does not exist: ${flags.fromArchive}`,
       path: flags.fromArchive,
-      next_action: "Provide an existing Codex adapter archive path or omit --from-archive.",
+      next_action: `Provide an existing ${descriptor.displayName} adapter archive path or omit --from-archive.`,
     });
   }
 
-  const directoryPlan = planDirectoryActions(flags);
+  const directoryPlan = planDirectoryActions(flags, descriptor, artifact);
   actions.push(...directoryPlan.actions);
   artifacts.push(...directoryPlan.artifacts);
   blockers.push(...directoryPlan.blockers);
 
-  if (existsSync(manifestAbsolutePath)) {
-    const existingManifest = readFileSync(manifestAbsolutePath, "utf8");
-    if (compatibleManifest(existingManifest)) {
+  if (flags.writeState) {
+    if (existingManifest !== undefined) {
+      const parsedManifest = parseManifestAdapterBlocks(existingManifest);
+      if (parsedManifest.error) {
+        errors.push({
+          code: parsedManifest.error.code,
+          message: parsedManifest.error.message,
+          path: manifestPath,
+          next_action: "Review or move the existing file before running init.",
+        });
+      } else if (parsedManifest.adapters.filter((entry) => entry.name === descriptor.name).length > 1) {
+        blockers.push({
+          code: "duplicate-target-entry",
+          message: `Existing rigorloop.yaml contains duplicate ${descriptor.displayName} target entries.`,
+          path: manifestPath,
+          next_action: "Remove duplicate target entries before running init.",
+        });
+      }
       actions.push({
         type: "write",
         path: manifestPath,
-        status: flags.dryRun ? "planned" : "skipped",
-        reason: "Compatible rigorloop.yaml already exists.",
+        status: flags.dryRun ? "planned" : "pending",
+        reason: `Write target-oriented rigorloop.yaml for ${descriptor.displayName} support.`,
       });
       artifacts.push({
         path: manifestPath,
         kind: "project-manifest",
-        status: "existing",
+        status: flags.dryRun ? "planned" : "pending",
       });
     } else {
-      errors.push({
-        code: "invalid-config",
-        message: "Existing rigorloop.yaml is not compatible with the first-slice Codex init contract.",
+      actions.push({
+        type: "write",
         path: manifestPath,
-        next_action: "Review or move the existing file before running init.",
+        status: flags.dryRun ? "planned" : "pending",
+        reason: "Create target-oriented RigorLoop project manifest.",
+      });
+      artifacts.push({
+        path: manifestPath,
+        kind: "project-manifest",
+        status: flags.dryRun ? "planned" : "pending",
       });
     }
-  } else {
-    actions.push({
-      type: "write",
-      path: manifestPath,
-      status: flags.dryRun ? "planned" : "pending",
-      reason: "Create first-slice RigorLoop project manifest.",
-    });
-    artifacts.push({
-      path: manifestPath,
-      kind: "project-manifest",
-      status: flags.dryRun ? "planned" : "pending",
-    });
-  }
 
-  addLockfilePlan(flags, actions, artifacts, blockers, errors);
+    addLockfilePlan(flags, actions, artifacts, blockers, errors);
+  }
 
   return {
     info,
@@ -1025,7 +1528,7 @@ function buildInitPlan(flags, artifact) {
     artifacts,
     blockers,
     errors,
-    planned_lockfile: plannedLockfile(info, source, manifest),
+    planned_lockfile: flags.writeState ? plannedLockfile(info, source, manifest, descriptor) : undefined,
   };
 }
 
@@ -1111,19 +1614,19 @@ function invalidArchivePath(message, flags) {
     code: "invalid-archive-path",
     message,
     path: flags.fromArchive,
-    next_action: "Provide an existing Codex adapter archive path or omit --from-archive.",
+    next_action: "Provide an existing supported adapter archive path or omit --from-archive.",
   });
 }
 
 function unsupportedAdapter(adapter, flags) {
   const result = envelope("init", flags, {
     status: "blocked",
-    summary: `Adapter '${adapter}' is not supported in this slice.`,
+    summary: `Target '${adapter}' is not supported.`,
     blockers: [
       {
-        code: "adapter-unsupported",
-        message: `Adapter '${adapter}' is not supported in this slice.`,
-        next_action: "Use --adapter codex.",
+        code: "target-unknown",
+        message: `Target '${adapter}' is not supported.`,
+        next_action: `Use one of: ${supportedAdapterNames().join(", ")}.`,
       },
     ],
   });
@@ -1131,11 +1634,32 @@ function unsupportedAdapter(adapter, flags) {
   if (flags.json) {
     writeJson(result);
   } else {
-    process.stderr.write(`${result.summary}\nUse --adapter codex.\n`);
+    process.stderr.write(`${result.summary}\nUse one of: ${supportedAdapterNames().join(", ")}.\n`);
   }
   return exitCodeForResult({ ...result, exit_class: "blocked" });
 }
 
+function removedAdapterSyntax(flags) {
+  const targets = supportedAdapterNames();
+  const result = envelope("init", flags, {
+    status: "error",
+    summary: "`init --adapter` was removed in RigorLoop 0.3.0.",
+    errors: [
+      {
+        code: "adapter-option-removed",
+        message: "`init --adapter` was removed in RigorLoop 0.3.0.",
+        next_action: `Use target-native init: ${targets.map((target) => `rigorloop init ${target}`).join(", ")}.`,
+      },
+    ],
+  });
+  if (flags.json) {
+    writeJson(result);
+  } else {
+    process.stderr.write(`${result.summary}\n${result.errors[0].next_action}\n`);
+  }
+  return exitCodeForResult({ ...result, exit_class: "invalid_usage" });
+}
+
 function writeBlockedResult(flags, plan, summary, blockers, exitClass = "blocked") {
   for (const action of plan.actions) {
     if (action.status === "pending") {
@@ -1148,18 +1672,26 @@ function writeBlockedResult(flags, plan, summary, blockers, exitClass = "blocked
       artifact.status = "blocked";
     }
   }
+  const statePlan = flags.writeState
+    ? {
+        planned_manifest: {
+          path: "rigorloop.yaml",
+          content: plan.manifest,
+        },
+        planned_lockfile: plan.planned_lockfile,
+      }
+    : {};
   const result = envelope("init", flags, {
     status: "blocked",
     summary,
     actions: plan.actions,
     artifacts: plan.artifacts,
     blockers,
-    planned_manifest: {
-      path: "rigorloop.yaml",
-      content: plan.manifest,
-    },
-    planned_lockfile: plan.planned_lockfile,
+    ...statePlan,
   });
+  if (blockers[0]?.diagnostics) {
+    result.diagnostics = { ...result.diagnostics, ...blockers[0].diagnostics };
+  }
   if (flags.json) {
     writeJson(result);
   } else {
@@ -1184,17 +1716,22 @@ function writeValidationErrorResult(flags, plan, error) {
       artifact.status = "blocked";
     }
   }
+  const statePlan = flags.writeState
+    ? {
+        planned_manifest: {
+          path: "rigorloop.yaml",
+          content: plan.manifest,
+        },
+        planned_lockfile: plan.planned_lockfile,
+      }
+    : {};
   const result = envelope("init", flags, {
     status: "error",
     summary: error.message,
     actions: plan.actions,
     artifacts: plan.artifacts,
     errors: [error],
-    planned_manifest: {
-      path: "rigorloop.yaml",
-      content: plan.manifest,
-    },
-    planned_lockfile: plan.planned_lockfile,
+    ...statePlan,
   });
   if (flags.json) {
     writeJson(result);
@@ -1204,18 +1741,27 @@ function writeValidationErrorResult(flags, plan, error) {
   return exitCodeForResult({ ...result, exit_class: "validation_failed" });
 }
 
-async function archiveWorkForInit(flags, info) {
-  if (flags.dryRun) {
+async function archiveWorkForInit(flags, info, descriptor) {
+  if (flags.dryRun && !flags.fromArchiveProvided) {
     return {};
   }
 
   const bundledMetadata = loadVerifiedBundledMetadata(info);
   if (bundledMetadata.blocker || bundledMetadata.error) {
+    if (flags.dryRun) {
+      return {};
+    }
     return bundledMetadata;
   }
   const metadata = bundledMetadata.metadata;
-  const validation = validateMetadata(metadata, info);
+  const validation = validateMetadata(metadata, info, descriptor);
   if (validation.blocker || validation.error) {
+    if (
+      flags.dryRun &&
+      !["opencode-command-aliases-missing", "opencode-skills-only-compatibility-unmarked"].includes(validation.blocker?.code)
+    ) {
+      return {};
+    }
     return validation;
   }
   const artifact = validation.artifact;
@@ -1223,17 +1769,31 @@ async function archiveWorkForInit(flags, info) {
   if (flags.fromArchiveProvided) {
     const archiveName = basename(flags.fromArchive);
     if (archiveName !== artifact.archive || !archiveName.includes(metadata.release.version)) {
+      if (!archiveName.startsWith(`rigorloop-adapter-${descriptor.name}-`)) {
+        return {
+          error: {
+            code: "adapter-archive-mismatch",
+            message: `Local archive ${archiveName} is not a ${descriptor.displayName} adapter archive.`,
+            path: flags.fromArchive,
+          },
+          artifact,
+        };
+      }
       return {
         blocker: metadataBlocker(
           "release-version-incompatible",
           `Local archive ${archiveName} is not compatible with ${metadata.release.version}.`,
           flags.fromArchive,
-          "Use the Codex adapter archive matching the installed CLI package version.",
+          `Use the ${descriptor.displayName} adapter archive matching the installed CLI package version.`,
         ),
       };
     }
+    // CR-M2-R2-F1: dry-run planning must use trusted metadata roots without reading or extracting archive bytes.
+    if (flags.dryRun) {
+      return { artifact };
+    }
     const archiveBytes = readFileSync(resolve(process.cwd(), flags.fromArchive));
-    const inspected = inspectArchive(archiveBytes, artifact);
+    const inspected = inspectArchive(archiveBytes, artifact, descriptor);
     if (inspected.error) {
       return { error: inspected.error, artifact };
     }
@@ -1258,29 +1818,29 @@ async function archiveWorkForInit(flags, info) {
   }
   try {
     archiveBytes = await fetchBytes(artifact.url);
-  } catch {
+  } catch (error) {
     return {
-      blocker: metadataBlocker(
-        "release-unavailable",
-        "Official Codex adapter archive is unavailable.",
-        artifact.url,
-        "Retry later or use --from-archive with a compatible local archive.",
-      ),
+      blocker: downloadFailureBlocker(error, artifact, descriptor, metadata),
     };
   }
-  const inspected = inspectArchive(archiveBytes, artifact);
+  const inspected = inspectArchive(archiveBytes, artifact, descriptor);
   if (inspected.error) {
     return { error: inspected.error, artifact };
   }
   return { artifact, entries: inspected.entries, archiveHash: inspected.archiveHash, treeHash: inspected.treeHash };
 }
 
-async function handleInit(flags) {
-  if (!flags.adapter) {
-    return invalidUsage("Missing required option: --adapter codex.", flags, "init");
+async function handleInit(flags, initArgs = []) {
+  if (flags.adapterOptionUsed) {
+    return removedAdapterSyntax(flags);
+  }
+  if (initArgs.length !== 1) {
+    return invalidUsage(`init requires exactly one target: ${supportedAdapterNames().join(", ")}.`, flags, "init");
   }
-  if (flags.adapter !== "codex") {
-    return unsupportedAdapter(flags.adapter, flags);
+  const target = initArgs[0];
+  const descriptor = adapterDescriptor(target);
+  if (!descriptor) {
+    return unsupportedAdapter(target, flags);
   }
   if (flags.fromArchiveProvided && (!flags.fromArchive || flags.fromArchive.startsWith("--"))) {
     return invalidArchivePath("Missing required value for --from-archive.", flags);
@@ -1290,7 +1850,7 @@ async function handleInit(flags) {
   }
 
   const info = packageInfo();
-  const plan = buildInitPlan(flags);
+  let plan = buildInitPlan(flags, descriptor);
   if (plan.errors.length > 0) {
     const result = envelope("init", flags, {
       status: "error",
@@ -1298,11 +1858,15 @@ async function handleInit(flags) {
       actions: plan.actions,
       artifacts: plan.artifacts,
       errors: plan.errors,
-      planned_manifest: {
-        path: "rigorloop.yaml",
-        content: plan.manifest,
-      },
-      planned_lockfile: plan.planned_lockfile,
+      ...(flags.writeState
+        ? {
+            planned_manifest: {
+              path: "rigorloop.yaml",
+              content: plan.manifest,
+            },
+            planned_lockfile: plan.planned_lockfile,
+          }
+        : {}),
     });
     if (flags.json) {
       writeJson(result);
@@ -1311,21 +1875,40 @@ async function handleInit(flags) {
     }
     return exitCodeForResult({ ...result, exit_class: "invalid_usage" });
   }
-  if (plan.blockers.length > 0) {
+  const deferrableRootBlockers =
+    descriptor.name === "opencode" &&
+    plan.blockers.length > 0 &&
+    plan.blockers.every((blocker) => String(blocker.path ?? "").startsWith(".opencode/commands"));
+  if (plan.blockers.length > 0 && !deferrableRootBlockers) {
     return writeBlockedResult(flags, plan, plan.blockers[0].message, plan.blockers, exitClassForBlockers(plan.blockers));
   }
+  if (flags.dryRun) {
+    const stateSafety = existingStateSafetyBlocker(descriptor);
+    if (stateSafety) {
+      return writeBlockedResult(flags, plan, stateSafety.message, [stateSafety], exitClassForBlockers([stateSafety]));
+    }
+  }
 
-  const archiveWork = await archiveWorkForInit(flags, info);
-  if (archiveWork.artifact) {
-    plan.source.artifact = archiveWork.artifact;
-    plan.planned_lockfile = plannedLockfile(plan.info, plan.source, plan.manifest);
+  const archiveWork = await archiveWorkForInit(flags, info, descriptor);
+  if (archiveWork.artifact && !archiveWork.blocker && !archiveWork.error) {
+    plan = buildInitPlan(flags, descriptor, archiveWork.artifact);
+    if (plan.errors.length > 0) {
+      return writeValidationErrorResult(flags, plan, plan.errors[0]);
+    }
+    if (plan.blockers.length > 0) {
+      return writeBlockedResult(flags, plan, plan.blockers[0].message, plan.blockers, exitClassForBlockers(plan.blockers));
+    }
   }
   if (archiveWork.entries) {
     const conflict = generatedOutputConflictBlocker(archiveWork.entries);
     if (conflict) {
       return writeBlockedResult(flags, plan, conflict.message, [conflict], "mutation_conflict");
     }
-    const drift = lockfileDriftBlocker(currentCodexLockfileEntry());
+    const stateSafety = existingStateSafetyBlocker(descriptor, archiveWork.artifact);
+    if (stateSafety) {
+      return writeBlockedResult(flags, plan, stateSafety.message, [stateSafety], exitClassForBlockers([stateSafety]));
+    }
+    const drift = flags.writeState ? firstLockfileDriftBlocker() : undefined;
     if (drift) {
       return writeBlockedResult(
         flags,
@@ -1335,11 +1918,11 @@ async function handleInit(flags) {
         drift.code === "overwrite-refused" ? "mutation_conflict" : "blocked",
       );
     }
-    const installedTree = verifyInstalledTree(archiveWork.entries, archiveWork.artifact, { allowMissingOrEmpty: true });
+    const installedTree = verifyInstalledTree(archiveWork.entries, archiveWork.artifact, descriptor, { allowMissingOrEmpty: true });
     if (installedTree.error) {
       return writeValidationErrorResult(flags, plan, installedTree.error);
     }
-    addArchiveActions(plan, archiveWork.entries);
+    addArchiveActions(plan, archiveWork.entries, descriptor);
   }
 
   if (archiveWork.blocker) {
@@ -1353,7 +1936,7 @@ async function handleInit(flags) {
   }
 
   if (!flags.dryRun) {
-    const manifestAction = plan.actions.find((action) => action.path === "rigorloop.yaml");
+    const manifestAction = flags.writeState ? plan.actions.find((action) => action.path === "rigorloop.yaml") : undefined;
     const directoryActions = plan.actions.filter((action) => action.type === "create-dir" && action.status === "pending");
     for (const directoryAction of directoryActions) {
       mkdirSync(resolve(process.cwd(), directoryAction.path));
@@ -1370,7 +1953,7 @@ async function handleInit(flags) {
         const pendingCopyPaths = new Set(
           plan.actions.filter((action) => action.type === "copy" && action.status === "pending").map((action) => action.path),
         );
-        writeArchiveEntries(archiveWork.entries.filter((entry) => pendingCopyPaths.has(entry.name)));
+        writeArchiveEntries(archiveWork.entries.filter((entry) => pendingCopyPaths.has(entry.name)), descriptor);
         for (const action of plan.actions.filter((action) => action.type === "copy" && action.status === "pending")) {
           action.status = "done";
           plan.artifacts.find((artifact) => artifact.path === action.path).status = "created";
@@ -1388,11 +1971,15 @@ async function handleInit(flags) {
               partial_state: "scaffold files may have been written; adapter files may be incomplete.",
             },
           ],
-          planned_manifest: {
-            path: "rigorloop.yaml",
-            content: plan.manifest,
-          },
-          planned_lockfile: plan.planned_lockfile,
+          ...(flags.writeState
+            ? {
+                planned_manifest: {
+                  path: "rigorloop.yaml",
+                  content: plan.manifest,
+                },
+                planned_lockfile: plan.planned_lockfile,
+              }
+            : {}),
         });
         if (flags.json) {
           writeJson(result);
@@ -1402,12 +1989,12 @@ async function handleInit(flags) {
         return exitCodeForResult({ ...result, exit_class: "internal" });
       }
     }
-    if (archiveWork.entries) {
+    if (flags.writeState && archiveWork.entries) {
       const lockfileAction = plan.actions.find((action) => action.path === LOCKFILE_PATH);
       const lockfileArtifact = plan.artifacts.find((artifact) => artifact.path === LOCKFILE_PATH);
       if (lockfileAction?.status === "pending") {
         const lockfilePreviouslyExists = existsSync(resolve(process.cwd(), LOCKFILE_PATH));
-        const verifiedInstalledTree = verifyInstalledTree(archiveWork.entries, archiveWork.artifact);
+        const verifiedInstalledTree = verifyInstalledTree(archiveWork.entries, archiveWork.artifact, descriptor);
         if (verifiedInstalledTree.error) {
           return writeValidationErrorResult(flags, plan, verifiedInstalledTree.error);
         }
@@ -1416,15 +2003,15 @@ async function handleInit(flags) {
           plan.source,
           plan.manifest,
           archiveWork.artifact,
-          archiveWork.artifact.tree_sha256,
-          verifiedInstalledTree.expectedFileCount,
+          verifiedInstalledTree.rootHashes,
+          descriptor,
         );
         writeFileSync(resolve(process.cwd(), LOCKFILE_PATH), serializeLockfile(lockfile), "utf8");
         plan.planned_lockfile = lockfile;
         lockfileAction.status = "done";
         lockfileAction.reason = lockfilePreviouslyExists
-          ? "Updated durable lockfile for verified Codex adapter install."
-          : "Wrote durable lockfile for verified Codex adapter install.";
+          ? `Updated durable lockfile for verified ${descriptor.displayName} adapter install.`
+          : `Wrote durable lockfile for verified ${descriptor.displayName} adapter install.`;
         if (lockfileArtifact) {
           lockfileArtifact.status = lockfilePreviouslyExists ? "updated" : "created";
         }
@@ -1432,22 +2019,29 @@ async function handleInit(flags) {
     }
   }
 
-  const warnings = [];
+  const warnings = initWarnings(descriptor, archiveWork.artifact);
   const result = envelope("init", flags, {
     status: warnings.length > 0 ? "warning" : "success",
     summary: flags.dryRun
       ? "RigorLoop init dry run completed. No files were written."
       : archiveWork.entries
-        ? "RigorLoop initialized with verified Codex adapter files."
-        : "RigorLoop initialized with Codex scaffold.",
+            ? `RigorLoop initialized with verified ${descriptor.displayName} target support.`
+        : `RigorLoop initialized with ${descriptor.displayName} scaffold.`,
     actions: plan.actions,
     artifacts: plan.artifacts,
     warnings,
-    planned_manifest: {
-      path: "rigorloop.yaml",
-      content: plan.manifest,
-    },
-    planned_lockfile: plan.planned_lockfile,
+    state_files: flags.writeState
+      ? { action: flags.dryRun ? "planned" : "written" }
+      : { action: "skipped", reason: "Use --write-state to write rigorloop.yaml and rigorloop.lock." },
+    ...(flags.writeState
+      ? {
+          planned_manifest: {
+            path: "rigorloop.yaml",
+            content: plan.manifest,
+          },
+          planned_lockfile: plan.planned_lockfile,
+        }
+      : {}),
   });
 
   if (flags.json) {
@@ -1457,10 +2051,13 @@ async function handleInit(flags) {
       ? ["RigorLoop init dry run completed.", "No files were written."]
       : [
           archiveWork.entries
-            ? "RigorLoop initialized with verified Codex adapter files."
-            : "RigorLoop initialized with Codex scaffold.",
-          archiveWork.entries ? "rigorloop.lock was written." : "No adapter files were installed.",
+            ? `RigorLoop initialized with verified ${descriptor.displayName} target support.`
+            : `RigorLoop initialized with ${descriptor.displayName} scaffold.`,
+          flags.writeState ? "rigorloop.yaml and rigorloop.lock were written." : "State files were not written; use --write-state to write them.",
         ];
+    for (const warning of warnings) {
+      lines.push(`warning ${warning.code}: ${warning.message}`);
+    }
     writeHuman(`${lines.join("\n")}\n`, flags);
   }
   return exitCodeForResult({ ...result, exit_class: "success" });
@@ -1483,7 +2080,7 @@ async function main() {
       return handleVersion(flags);
     }
     if (command === "init") {
-      return handleInit(flags);
+      return handleInit(flags, positional.slice(1));
     }
     if (command === "new-change") {
       return handleNewChange(rawArgs.slice(rawArgs.indexOf("new-change") + 1));