@kylecheng3146/agent-ops 0.1.4 → 0.1.6

package/dist/runtime/src/install/doctor.js

@@ -5,11 +5,17 @@ import { parseInstallManifest, PROJECT_MANIFEST_PATH } from "../fs/manifest.js";
 import { resolveContainedPath } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
 import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
+import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
+import { harnessDescriptor, managedRules } from "./harness.js";
+import { resolveCapabilities, resolveProfiles } from "./profiles.js";
+import { inspectHarnessSurfaces, inspectHarnessRegistrations } from "./surface-inspection.js";
 const CONFIG_PATH = ".agent-ops/config.json";
 const MINIMUM_NODE_VERSION = [22, 14, 0];
 const MAX_DOCTOR_FILE_BYTES = 1024 * 1024;
-function check(id, status, message) {
-    return { id, status, message };
+function check(id, status, message, code) {
+    return code === undefined
+        ? { id, status, message }
+        : { id, status, message, code };
 }
 function parseNodeVersion(version) {
     const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
@@ -80,7 +86,7 @@ async function readContainedText(root, path) {
 async function checkManifest(root) {
     try {
         const manifest = parseInstallManifest(await readContainedText(root, PROJECT_MANIFEST_PATH));
-        assertSupportedManifestOwnership(manifest);
+        assertSupportedManifestOwnership(manifest, root);
         return {
             check: check("manifest", "PASS", "Installation manifest is valid."),
             manifest
@@ -118,30 +124,89 @@ async function checkConfig(root) {
 }
 async function checkArtifacts(root, manifest) {
     if (manifest === undefined) {
-        return check("artifacts", "FAIL", "Artifacts cannot be verified without a valid manifest.");
+        return {
+            check: check("artifacts", "FAIL", "Artifacts cannot be verified without a valid manifest."),
+            hashesByPath: new Map()
+        };
     }
     const failures = [];
+    const hashesByPath = new Map();
     for (const artifact of manifest.artifacts) {
         try {
             const content = await readContained(root, artifact.path);
-            if (sha256(content) !== artifact.hash) {
+            const hash = sha256(content);
+            if (hash !== artifact.hash ||
+                (artifact.id === "opencode-plugin" &&
+                    !isOpencodeManagedPlugin(content.toString("utf8")))) {
                 failures.push(artifact.path);
             }
+            else {
+                hashesByPath.set(artifact.path, hash);
+            }
         }
         catch {
             failures.push(artifact.path);
         }
     }
-    return failures.length === 0
-        ? check("artifacts", "PASS", "All managed artifacts match their hashes.")
-        : check("artifacts", "FAIL", `Managed artifacts failed verification: ${failures.join(", ")}.`);
+    return {
+        check: failures.length === 0
+            ? check("artifacts", "PASS", "All managed artifacts match their hashes.")
+            : check("artifacts", "FAIL", `Managed artifacts failed verification: ${failures.join(", ")}.`),
+        hashesByPath
+    };
+}
+function checkArtifactStaleness(manifest, config, artifacts, toolkitVersion) {
+    if (manifest === undefined || config === undefined) {
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed without a valid manifest and configuration.");
+    }
+    if (artifacts.check.status !== "PASS") {
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed until artifact integrity passes.");
+    }
+    if (toolkitVersion === undefined) {
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed without the running toolkit version.");
+    }
+    const expectedHashesByPath = new Map();
+    try {
+        const resolved = config.profiles.length === 0
+            ? { profiles: [], capabilities: [] }
+            : resolveCapabilities(config);
+        for (const id of manifest.harness) {
+            const descriptor = harnessDescriptor(id);
+            const path = `.agent-ops/${descriptor.control.instructionFile}`;
+            if (!expectedHashesByPath.has(path)) {
+                expectedHashesByPath.set(path, sha256(managedRules(descriptor, {
+                    scope: manifest.scope,
+                    profiles: resolved.profiles,
+                    capabilities: resolved.capabilities,
+                    toolkitVersion
+                })));
+            }
+        }
+    }
+    catch {
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness could not be assessed safely.");
+    }
+    const stalePaths = [];
+    for (const [path, expectedHash] of expectedHashesByPath) {
+        const actualHash = artifacts.hashesByPath.get(path);
+        if (actualHash === undefined) {
+            return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness could not be assessed safely.");
+        }
+        if (actualHash !== expectedHash) {
+            stalePaths.push(path);
+        }
+    }
+    return stalePaths.length === 0
+        ? check("artifact-staleness", "PASS", "Managed artifacts match the current toolkit and configuration.")
+        : check("artifact-staleness", "DEGRADED", `Managed artifacts need update: ${stalePaths.join(", ")}; run agent-ops update.`, "UPDATE_REQUIRED");
 }
 async function checkMarkers(root, manifest) {
     if (manifest === undefined) {
         return check("markers", "FAIL", "Managed blocks cannot be verified without a valid manifest.");
     }
     const failures = [];
-    const expectedMarkers = assertSupportedManifestOwnership(manifest);
+    const legacyPaths = [];
+    const expectedMarkers = assertSupportedManifestOwnership(manifest, root);
     for (const marker of manifest.markers) {
         try {
             const source = await readContainedText(root, marker.path);
@@ -150,15 +215,22 @@ async function checkMarkers(root, manifest) {
                 failures.push(marker.path);
                 continue;
             }
-            assertExpectedManagedBlock(source, marker, expected);
+            const match = assertExpectedManagedBlock(source, marker, expected);
+            if (match === "legacy") {
+                legacyPaths.push(marker.path);
+            }
         }
         catch {
             failures.push(marker.path);
         }
     }
-    return failures.length === 0
-        ? check("markers", "PASS", "All managed block markers are intact.")
-        : check("markers", "FAIL", `Managed block markers failed verification: ${failures.join(", ")}.`);
+    if (failures.length > 0) {
+        return check("markers", "FAIL", `Managed block markers failed verification: ${failures.join(", ")}.`);
+    }
+    if (legacyPaths.length > 0) {
+        return check("markers", "DEGRADED", `Legacy managed routing blocks need migration: ${legacyPaths.join(", ")}.`);
+    }
+    return check("markers", "PASS", "All managed block markers are intact.");
 }
 async function checkProbe(id, probe) {
     if (probe === undefined) {
@@ -177,21 +249,117 @@ async function checkProbe(id, probe) {
         return check(id, "FAIL", "Probe failed.");
     }
 }
+function checkLifecycleSummary(manifest, config) {
+    if (manifest === undefined || config === undefined) {
+        return check("lifecycle-summary", "UNKNOWN", "Lifecycle summary cannot be assessed without a valid manifest and configuration.");
+    }
+    const hasLifecycleSummary = config.profiles.length > 0 &&
+        resolveProfiles(config.profiles).capabilities.includes("lifecycle-summary");
+    if (!hasLifecycleSummary) {
+        return check("lifecycle-summary", "PASS", "Lifecycle summary has no harness-specific degradation.");
+    }
+    const registrations = manifest.harness.map((id) => ({
+        id,
+        registration: harnessDescriptor(id).control.registrations.find((candidate) => candidate.capability === "lifecycle-summary")
+    }));
+    const missing = registrations
+        .filter(({ registration }) => registration === undefined)
+        .map(({ id }) => id);
+    if (missing.length > 0) {
+        return check("lifecycle-summary", "UNKNOWN", `Lifecycle summary registration is missing for ${missing.join(", ")}.`);
+    }
+    const unsupported = registrations
+        .filter(({ registration }) => registration?.support === "unsupported")
+        .map(({ id }) => id);
+    if (unsupported.length > 0) {
+        return check("lifecycle-summary", "UNSUPPORTED", `Lifecycle summary is not dispatched for ${unsupported.join(", ")}; advisory runtime wiring is unavailable.`);
+    }
+    const degraded = registrations
+        .filter(({ registration }) => registration?.support === "degraded")
+        .map(({ id }) => id);
+    if (degraded.length > 0) {
+        return check("lifecycle-summary", "DEGRADED", `Lifecycle summary is degraded for ${degraded.join(", ")}.`);
+    }
+    const unknown = registrations
+        .filter(({ registration }) => registration?.support === "unknown")
+        .map(({ id }) => id);
+    if (unknown.length > 0) {
+        return check("lifecycle-summary", "UNKNOWN", `Lifecycle summary support is unknown for ${unknown.join(", ")}.`);
+    }
+    return check("lifecycle-summary", "PASS", "Lifecycle summary is reachable for every selected harness.");
+}
+async function checkSurfaceInventory(root, manifest, config) {
+    if (manifest === undefined || config === undefined) {
+        return {
+            check: check("surface-inventory", "UNKNOWN", "Harness surfaces cannot be inventoried without a valid manifest and configuration."),
+            surfaces: []
+        };
+    }
+    try {
+        const surfaces = await inspectHarnessSurfaces({
+            root,
+            scope: manifest.scope,
+            harness: manifest.harness,
+            profiles: config.profiles
+        });
+        const unknown = surfaces.filter(({ status }) => status === "unknown");
+        return {
+            check: check("surface-inventory", unknown.length > 0 ? "UNKNOWN" : "PASS", unknown.length > 0
+                ? `${unknown.length} harness surface(s) could not be inspected.`
+                : "Harness surfaces were inventoried without exposing settings values."),
+            surfaces
+        };
+    }
+    catch {
+        return {
+            check: check("surface-inventory", "UNKNOWN", "Harness surfaces could not be inspected safely."),
+            surfaces: []
+        };
+    }
+}
+async function checkRegistrationDrift(root, manifest, config) {
+    if (manifest === undefined || config === undefined) {
+        return check("registration-drift", "UNKNOWN", "Hook registration drift cannot be assessed without a valid manifest and configuration.");
+    }
+    try {
+        const statuses = await inspectHarnessRegistrations({
+            root,
+            manifest,
+            config
+        });
+        const drifted = statuses
+            .filter(({ registered }) => !registered)
+            .map(({ harness }) => harness);
+        return drifted.length === 0
+            ? check("registration-drift", "PASS", "Managed hook registrations match the desired capabilities.")
+            : check("registration-drift", "FAIL", `Hook registration drift detected for ${drifted.join(", ")}; run agent-ops update.`, "UPDATE_REQUIRED");
+    }
+    catch {
+        return check("registration-drift", "UNKNOWN", "Hook registration drift could not be assessed safely.");
+    }
+}
 export async function doctorInstallation(options) {
     const manifest = await checkManifest(options.root);
     const config = await checkConfig(options.root);
+    const artifacts = await checkArtifacts(options.root, manifest.manifest);
+    const surfaceInventory = await checkSurfaceInventory(options.root, manifest.manifest, config.config);
     const checks = [
         checkNodeVersion(options.nodeVersion ?? process.versions.node),
         manifest.check,
         config.check,
-        await checkArtifacts(options.root, manifest.manifest),
+        artifacts.check,
+        checkArtifactStaleness(manifest.manifest, config.config, artifacts, options.toolkitVersion),
         await checkMarkers(options.root, manifest.manifest),
+        surfaceInventory.check,
+        await checkRegistrationDrift(options.root, manifest.manifest, config.config),
         await checkProbe("hook-registration", options.probes?.hookRegistration),
+        checkLifecycleSummary(manifest.manifest, config.config),
         await checkProbe("repository-trust", options.probes?.repositoryTrust),
         await checkProbe("smoke-availability", options.probes?.smokeAvailability)
     ];
     return {
         checks,
+        surfaces: surfaceInventory.surfaces,
         ...(manifest.manifest === undefined
             ? {}
             : { manifest: manifest.manifest }),

package/dist/runtime/src/install/harness.js

@@ -1,8 +1,233 @@
+import { buildClaudeHookSettings, isClaudeManagedHandler, mergeClaudeSettings, stripClaudeManagedHooks } from "../adapters/claude/config.js";
+import { CLAUDE_CAPABILITY_REGISTRATIONS } from "../adapters/claude/events.js";
+import { normalizeClaudeHookInput } from "../adapters/claude/input.js";
+import { claudeHookOutput } from "../adapters/claude/output.js";
+import { claudeSurfaces } from "../adapters/claude/surfaces.js";
+import { buildCodexHookConfig, CODEX_MANAGED_MARKER, mergeCodexHookConfig, stripCodexManagedHooks } from "../adapters/codex/config.js";
+import { CODEX_CAPABILITY_REGISTRATIONS } from "../adapters/codex/events.js";
+import { normalizeCodexHookInput } from "../adapters/codex/input.js";
+import { codexHookOutput } from "../adapters/codex/output.js";
+import { codexSurfaces } from "../adapters/codex/surfaces.js";
+import { buildOpencodePlugin, isOpencodePluginRegistered, opencodePluginTarget } from "../adapters/opencode/config.js";
+import { OPENCODE_CAPABILITY_REGISTRATIONS } from "../adapters/opencode/events.js";
+import { normalizeOpencodeHookInput } from "../adapters/opencode/input.js";
+import { opencodeHookOutput } from "../adapters/opencode/output.js";
+import { opencodeSurfaces } from "../adapters/opencode/surfaces.js";
 import { AgentOpsError } from "../fs/paths.js";
-export const COMMON_AGENTS_BLOCK = "## Loop Engineering\n\nUse `.agent-ops/AGENTS.md` as the canonical Loop Engineering specification for this project.\n";
-export const COMMON_CLAUDE_BLOCK = "## Loop Engineering\n\nUse `.agent-ops/CLAUDE.md` as the canonical Loop Engineering specification for this project.\n";
-function managedRules(id, context) {
-    const instructionFile = id === "codex" ? "AGENTS.md" : "CLAUDE.md";
+import { findSurfaceById, findSurfaceByPath, isWritableSurface } from "./surfaces.js";
+export const HARNESS_IDS = [
+    "codex",
+    "claude",
+    "opencode"
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJsonSource(source) {
+    if (typeof source !== "string") {
+        return source;
+    }
+    if (source.trim().length === 0) {
+        return {};
+    }
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+}
+function jsonHookRegistered(control, source, capabilities) {
+    if (control.buildHooks === undefined ||
+        control.isManagedHandler === undefined) {
+        return false;
+    }
+    const events = Object.keys(control.buildHooks(capabilities, "probe").hooks);
+    if (events.length === 0) {
+        return true;
+    }
+    const parsed = parseJsonSource(source);
+    if (!isRecord(parsed) || !isRecord(parsed.hooks)) {
+        return false;
+    }
+    const hooks = parsed.hooks;
+    return events.every((event) => {
+        const groups = hooks[event];
+        return (Array.isArray(groups) &&
+            groups.some((group) => isRecord(group) &&
+                Array.isArray(group.hooks) &&
+                group.hooks.some(control.isManagedHandler)));
+    });
+}
+function runtimeFailureResult(capability, registrations, remedy) {
+    const runtimeFailure = registrations.find((registration) => registration.capability === capability)?.runtimeFailure;
+    return {
+        action: runtimeFailure === "fail-closed" ? "block" : "continue",
+        status: "UNKNOWN",
+        code: `${capability.replaceAll("-", "_").toUpperCase()}_UNAVAILABLE`,
+        ...(remedy === undefined ? {} : { remedy })
+    };
+}
+function createJsonDescriptor(options) {
+    const control = {
+        instructionFile: options.instructionFile,
+        routing: options.routing,
+        hookPath: options.hookPath,
+        surfaces: options.surfaces,
+        ownSettingsKeys: options.ownSettingsKeys,
+        buildHooks: options.buildHooks,
+        mergeHooks: options.mergeHooks,
+        stripHooks: options.stripHooks,
+        isManagedHandler: options.isManagedHandler,
+        registrations: options.registrations,
+        plan: (context) => planCommonHarnessContribution(options.id, context),
+        hookRegistered: (source, capabilities) => jsonHookRegistered(control, source, capabilities)
+    };
+    return {
+        id: options.id,
+        control,
+        runtime: {
+            normalizeInput: options.normalizeInput,
+            formatOutput: options.formatOutput,
+            formatRuntimeFailure: (event, capability, remedy) => options.formatOutput(event, runtimeFailureResult(capability, options.registrations, remedy))
+        }
+    };
+}
+const AGENTS_ROUTING = {
+    desired: "## Loop Engineering\n\nLoad `.agent-ops/AGENTS.md` as the agent-ops managed baseline.\nProject-specific instructions in this file remain authoritative.\n",
+    legacy: [
+        "## Loop Engineering\n\nUse `.agent-ops/AGENTS.md` as the canonical Loop Engineering specification for this project.\n"
+    ]
+};
+const CLAUDE_ROUTING = {
+    desired: "## Loop Engineering\n\nLoad `.agent-ops/CLAUDE.md` as the agent-ops managed baseline.\nProject-specific instructions in this file remain authoritative.\n",
+    legacy: [
+        "## Loop Engineering\n\nUse `.agent-ops/CLAUDE.md` as the canonical Loop Engineering specification for this project.\n"
+    ]
+};
+const DESCRIPTORS = {
+    codex: createJsonDescriptor({
+        id: "codex",
+        instructionFile: "AGENTS.md",
+        routing: AGENTS_ROUTING,
+        hookPath: ".codex/hooks.json",
+        surfaces: codexSurfaces,
+        ownSettingsKeys: ["hooks", "description"],
+        buildHooks: (capabilities, runtimePath) => buildCodexHookConfig(capabilities, runtimePath),
+        mergeHooks: (existing, managed) => mergeCodexHookConfig(existing, managed),
+        stripHooks: (existing) => stripCodexManagedHooks(existing),
+        isManagedHandler: (handler) => isRecord(handler) &&
+            typeof handler.command === "string" &&
+            handler.command.includes(CODEX_MANAGED_MARKER),
+        registrations: CODEX_CAPABILITY_REGISTRATIONS,
+        normalizeInput: normalizeCodexHookInput,
+        formatOutput: (event, result) => {
+            const output = codexHookOutput(event, result);
+            return { exitCode: 0, stdout: output.stdout, stderr: "" };
+        }
+    }),
+    claude: createJsonDescriptor({
+        id: "claude",
+        instructionFile: "CLAUDE.md",
+        routing: CLAUDE_ROUTING,
+        hookPath: ".claude/settings.json",
+        surfaces: claudeSurfaces,
+        ownSettingsKeys: ["hooks"],
+        buildHooks: (capabilities, runtimePath) => buildClaudeHookSettings(capabilities, runtimePath),
+        mergeHooks: (existing, managed) => mergeClaudeSettings(existing, managed),
+        stripHooks: (existing) => stripClaudeManagedHooks(existing),
+        isManagedHandler: isClaudeManagedHandler,
+        registrations: CLAUDE_CAPABILITY_REGISTRATIONS,
+        normalizeInput: normalizeClaudeHookInput,
+        formatOutput: (event, result) => claudeHookOutput(event, result)
+    }),
+    opencode: {
+        id: "opencode",
+        control: {
+            instructionFile: "AGENTS.md",
+            routing: AGENTS_ROUTING,
+            hookPath: opencodePluginTarget("project").path,
+            hookPathForScope: (scope, root) => opencodePluginTarget(scope, root).path,
+            surfaces: opencodeSurfaces,
+            registrations: OPENCODE_CAPABILITY_REGISTRATIONS,
+            plan: (context) => planCommonHarnessContribution("opencode", context),
+            hookRegistered: (source, capabilities) => isOpencodePluginRegistered(source, capabilities)
+        },
+        runtime: {
+            normalizeInput: normalizeOpencodeHookInput,
+            formatOutput: (event, result) => opencodeHookOutput(event, result),
+            formatRuntimeFailure: (event, capability, remedy) => opencodeHookOutput(event, runtimeFailureResult(capability, OPENCODE_CAPABILITY_REGISTRATIONS, remedy))
+        }
+    }
+};
+export function harnessDescriptor(id) {
+    const descriptor = DESCRIPTORS[id];
+    if (descriptor === undefined) {
+        throw new AgentOpsError("HARNESS_ADAPTER_MISSING", `Missing harness adapter: ${id}`);
+    }
+    return descriptor;
+}
+export function harnessHookPath(id, scope, root) {
+    const descriptor = harnessDescriptor(id);
+    return descriptor.control.hookPathForScope?.(scope, root) ??
+        descriptor.control.hookPath;
+}
+export function harnessSurfaces(id, scope, root) {
+    return harnessDescriptor(id).control.surfaces(scope, root);
+}
+export function harnessSurfaceById(id, scope, surfaceId, root) {
+    return harnessSurfaces(id, scope, root).find((surface) => surface.id === surfaceId);
+}
+export function harnessSurfaceByPath(id, scope, path, root) {
+    return harnessSurfaces(id, scope, root).find((surface) => surface.path === path);
+}
+export function selectHarnessHookSurface(options) {
+    const descriptor = harnessDescriptor(options.harness);
+    if (descriptor.control.buildHooks === undefined) {
+        throw new AgentOpsError("HOOK_TARGET_UNSUPPORTED", `Harness hook targets are not supported for ${options.harness}.`);
+    }
+    const surfaces = harnessSurfaces(options.harness, options.scope, options.root);
+    const selected = options.surfaceId === undefined
+        ? options.persistedPath === undefined
+            ? surfaces.find((surface) => surface.access === "managed-default" &&
+                surface.representation === "json")
+            : findSurfaceByPath(surfaces, options.persistedPath)
+        : findSurfaceById(surfaces, options.surfaceId);
+    if (selected === undefined ||
+        selected.scope !== options.scope ||
+        !isWritableSurface(selected) ||
+        selected.representation !== "json") {
+        const requested = options.surfaceId ?? options.persistedPath ?? "default surface";
+        throw new AgentOpsError("HOOK_TARGET_INVALID", `Harness hook target is not a writable ${options.scope} surface: ${options.harness}=${requested}.`);
+    }
+    return selected;
+}
+export function isHarnessId(value) {
+    return Object.hasOwn(DESCRIPTORS, value);
+}
+/**
+ * `both` predates opencode and remains an input alias. `all` follows the
+ * registry and selects every registered harness.
+ */
+const HARNESS_ALIASES = {
+    all: HARNESS_IDS,
+    both: ["codex", "claude"]
+};
+export function resolveHarnessSelection(value) {
+    const alias = HARNESS_ALIASES[value.trim()];
+    if (alias !== undefined) {
+        return [...alias];
+    }
+    const ids = value.split(",").map((entry) => entry.trim());
+    return ids.length > 0 &&
+        ids.every(isHarnessId) &&
+        new Set(ids).size === ids.length
+        ? ids
+        : null;
+}
+export const COMMON_AGENTS_BLOCK = DESCRIPTORS.codex.control.routing.desired;
+export const COMMON_CLAUDE_BLOCK = DESCRIPTORS.claude.control.routing.desired;
+export function managedRules(descriptor, context) {
     const lines = [
         "# Loop Engineering",
         "",
@@ -22,44 +247,75 @@ function managedRules(id, context) {
         lines.push("Advisory lifecycle summaries and local logs are informational. Advisory", "failures must remain fail-open and cannot become verification evidence.", "");
     }
     if (context.capabilities.includes("command-policy")) {
-        lines.push("Command policy guards high-confidence unsafe actions. Optional Stop", "verification never marks a task complete by itself.", "");
+        lines.push("Command policy guards high-confidence unsafe actions. Explicitly enabled", "Stop verification is report-only and never marks a task complete by itself.", "");
     }
-    lines.push(`This file is routed from the active ${instructionFile}.`, "");
+    lines.push(`This file is routed from the active ${descriptor.control.instructionFile}.`, "");
     return lines.join("\n");
 }
+function instructionStem(instructionFile) {
+    return instructionFile.replace(/\.md$/iu, "").toLowerCase();
+}
+export function rulesArtifactId(descriptor) {
+    return `${instructionStem(descriptor.control.instructionFile)}-rules`;
+}
+export function routingBlockId(id, scope, descriptor = harnessDescriptor(id)) {
+    return scope === "project" && descriptor.control.instructionFile === "AGENTS.md"
+        ? "agents-routing"
+        : `${id}-routing`;
+}
+function dedupeByPath(entries) {
+    const kept = [];
+    for (const entry of entries) {
+        const duplicate = kept.some((existing) => existing.path === entry.path && existing.content === entry.content);
+        if (!duplicate) {
+            kept.push(entry);
+        }
+    }
+    return kept;
+}
+async function planCommonHarnessContribution(id, context) {
+    const descriptor = harnessDescriptor(id);
+    const artifacts = [
+        {
+            id: rulesArtifactId(descriptor),
+            path: `.agent-ops/${descriptor.control.instructionFile}`,
+            content: managedRules(descriptor, context)
+        }
+    ];
+    if (id === "opencode" && context.runtimePath !== undefined) {
+        const plugin = buildOpencodePlugin(context.capabilities, context.runtimePath);
+        if (plugin !== null) {
+            artifacts.push({
+                id: "opencode-plugin",
+                path: context.opencodePluginPath ??
+                    opencodePluginTarget(context.scope, context.root).path,
+                content: plugin
+            });
+        }
+    }
+    return {
+        artifacts,
+        blocks: [
+            {
+                id: routingBlockId(id, context.scope, descriptor),
+                path: context.scope === "project"
+                    ? descriptor.control.instructionFile
+                    : `.${id}/${descriptor.control.instructionFile}`,
+                version: 1,
+                content: descriptor.control.routing.desired
+            }
+        ]
+    };
+}
 export function commonHarnessAdapters() {
-    return ["codex", "claude"].map((id) => {
-        const instructionFile = id === "codex" ? "AGENTS.md" : "CLAUDE.md";
-        const blockContent = id === "codex" ? COMMON_AGENTS_BLOCK : COMMON_CLAUDE_BLOCK;
+    return HARNESS_IDS.map((id) => {
+        const descriptor = harnessDescriptor(id);
         return {
             id,
-            async plan(context) {
-                return {
-                    artifacts: [
-                        {
-                            id: `${id}-rules`,
-                            path: `.agent-ops/${instructionFile}`,
-                            content: managedRules(id, context)
-                        }
-                    ],
-                    blocks: [
-                        {
-                            id: `${id}-routing`,
-                            path: context.scope === "project"
-                                ? instructionFile
-                                : `.${id}/${instructionFile}`,
-                            version: 1,
-                            content: blockContent
-                        }
-                    ]
-                };
-            }
+            plan: (context) => descriptor.control.plan(context)
         };
     });
 }
-export function requestedHarnessIds(harness) {
-    return harness === "both" ? ["codex", "claude"] : [harness];
-}
 function selectAdapter(id, adapters) {
     const matches = adapters.filter((adapter) => adapter.id === id);
     if (matches.length === 0) {
@@ -75,7 +331,7 @@ function selectAdapter(id, adapters) {
     return adapter;
 }
 export async function planHarnessContributions(harness, context, adapters) {
-    const selectedAdapters = requestedHarnessIds(harness).map((id) => selectAdapter(id, adapters));
+    const selectedAdapters = harness.map((id) => selectAdapter(id, adapters));
     const artifacts = [];
     const blocks = [];
     for (const adapter of selectedAdapters) {
@@ -83,5 +339,8 @@ export async function planHarnessContributions(harness, context, adapters) {
         artifacts.push(...contribution.artifacts);
         blocks.push(...contribution.blocks);
     }
-    return { artifacts, blocks };
+    return {
+        artifacts: dedupeByPath(artifacts),
+        blocks: dedupeByPath(blocks)
+    };
 }