agentic-workflow-manager 3.0.1 → 3.2.0

package/dist/src/core/export/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/core/init/mutation-targets.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planInitMutationTargets = planInitMutationTargets;
+// src/core/init/mutation-targets.ts
+//
+// Enumerates, WITHOUT writing anything, every filesystem path a real `awm
+// init` run for a given agent is about to touch. `runInit` feeds this list to
+// `beginBackupSession` (install-transaction.ts) BEFORE any step runs, so a
+// failed init can roll every one of them back to its pre-run state.
+//
+// Deliberately generous rather than exhaustively precise: a path that ends up
+// unused this run (e.g. an ambient bundle whose signal isn't present) is
+// harmless to include — beginBackupSession just snapshots it (a no-op backup
+// entry when nothing exists there yet). The one failure mode that matters is
+// under-enumeration: a real write to a path NOT in this list would land
+// outside the backup session and survive a rollback.
+const path_1 = __importDefault(require("path"));
+const providers_1 = require("../../providers");
+const bundles_1 = require("../bundles");
+const bundle_install_1 = require("../bundle-install");
+const install_planner_1 = require("../install-planner");
+const artifact_state_1 = require("../artifact-state");
+const paths_1 = require("../paths");
+const profile_1 = require("../profile");
+const registries_1 = require("../registries");
+// Thin wrapper over install-planner.ts's `physicalTarget` (the single source
+// of truth for the dir+filename computation, including the `.toml` rename for
+// codex-agent-toml) — adapts its throw-on-unsupported contract to this
+// module's null-on-unsupported one, and drops the `renderer` field this
+// module's callers never needed.
+function physicalTarget(type, agent, scope, installName, projectRoot) {
+    try {
+        return (0, install_planner_1.physicalTarget)({ name: installName, installName, type, sourcePath: '' }, agent, scope, projectRoot ?? '').targetPath;
+    }
+    catch {
+        return null;
+    }
+}
+function addBundleTargets(targets, bundleName, bundles, agent, scope, projectRoot, contentDir) {
+    let intents;
+    try {
+        intents = (0, bundle_install_1.expandBundleArtifacts)({
+            bundleName,
+            bundles,
+            agents: [agent],
+            method: 'symlink',
+            projectRoot,
+            contentDir,
+        });
+    }
+    catch {
+        // Bundle not resolvable (e.g. missing dependency in a partially-seeded
+        // test registry) — nothing to enumerate for it, not a hard failure.
+        return;
+    }
+    for (const intent of intents) {
+        const p = physicalTarget(intent.type, agent, scope, intent.installName, projectRoot);
+        if (p)
+            targets.add(p);
+    }
+}
+/**
+ * Enumerates every path `runInitSteps` may write to for `agent`, given the
+ * discovered bundle catalog. Driven entirely by `agent` (the single target
+ * being initialized this run) and `bundles` — not by preferences, since
+ * enumeration never needs to know about any OTHER enabled agent's targets.
+ * Pure / read-only (does hit the filesystem to discover project root and
+ * read the project profile, but never writes).
+ */
+function planInitMutationTargets(params) {
+    const { cwd, agent, bundles } = params;
+    const targets = new Set();
+    // preferences.json + the artifact ownership ledger (state/artifacts.json)
+    targets.add(path_1.default.join((0, paths_1.awmHome)(), 'preferences.json'));
+    targets.add((0, artifact_state_1.artifactStateFile)());
+    const provider = (0, providers_1.providerFor)(agent);
+    // hook: settings file (or hooks.json for codex) + the scripts directory it points at
+    if (provider.hooks) {
+        targets.add(provider.hooks.settingsPath);
+        targets.add(provider.hooks.scriptsDir);
+    }
+    // Global skills directory itself, not just the bundle-derived skill
+    // subdirectories enumerated below. stepGlobalSkillsRepair (steps.ts) calls
+    // repairGlobalSkills, which readdirSync's the WHOLE skills dir and
+    // rm/symlinks individual entries classified as repairable/dead — i.e.
+    // entries that, by definition, don't belong to any currently-known
+    // bundle, so they can never be enumerated by addBundleTargets below.
+    // Adding the parent directory here makes beginBackupSession snapshot the
+    // whole tree (backupEntryFor does a recursive fs.cpSync for directory
+    // targets — verified in install-transaction.ts), covering any entry that
+    // repair might mutate. Broad-but-safe, per this module's own philosophy.
+    targets.add(provider.skill.global);
+    // global context / AGENTS.md injection (covered by the hook for claude-code)
+    const injection = provider.injection;
+    if (injection) {
+        if (injection.type === 'config-instructions')
+            targets.add(injection.configPath);
+        if (injection.type === 'managed-agents-md')
+            targets.add(injection.globalPath);
+    }
+    // machine-level bundle targets: baseline (dev-core) + ambient, global scope
+    const roots = (0, registries_1.contentRoots)();
+    const contentDir = roots[0] ?? '';
+    const machineBundles = bundles.filter((b) => b.scope === 'baseline' || b.scope === 'ambient');
+    for (const b of machineBundles) {
+        addBundleTargets(targets, b.name, bundles, agent, 'global', cwd, contentDir);
+    }
+    // project-level: profile, sensors manifest, project injection, and every
+    // extension currently recorded in .awm/profile.json
+    const projectRoot = (0, profile_1.findProjectRoot)(cwd);
+    if (projectRoot) {
+        targets.add(path_1.default.join(projectRoot, '.awm', 'profile.json'));
+        targets.add(path_1.default.join(projectRoot, '.awm', 'sensors.json'));
+        if (injection?.type === 'config-instructions') {
+            targets.add(path_1.default.join(projectRoot, path_1.default.basename(injection.configPath)));
+        }
+        if (injection?.type === 'managed-agents-md') {
+            targets.add(path_1.default.join(projectRoot, path_1.default.basename(injection.localFile)));
+        }
+        let profile;
+        try {
+            profile = (0, profile_1.readProfile)(projectRoot);
+        }
+        catch {
+            profile = { extensions: [] };
+        }
+        for (const ext of profile.extensions) {
+            const extBundle = bundles.find((b) => b.name === ext);
+            if (!extBundle)
+                continue;
+            const scope = (0, bundles_1.defaultScopeForBundle)(extBundle.scope);
+            addBundleTargets(targets, ext, bundles, agent, scope, projectRoot, contentDir);
+        }
+    }
+    return Array.from(targets);
+}

package/dist/src/core/init/provider-facts.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatherProviderFacts = gatherProviderFacts;
+exports.assertClaudeBaselinePreserved = assertClaudeBaselinePreserved;
+// src/core/init/provider-facts.ts
+//
+// R19's "Claude baseline is read-only" guarantee: when `awm init` targets a
+// non-Claude agent (today: Codex), nothing this run does may change what's
+// already managed for claude-code. `gatherProviderFacts` snapshots every path
+// Claude's own init run would touch (hooks, skill/agent dirs, injection);
+// `assertClaudeBaselinePreserved` compares a before/after pair and throws if
+// anything moved. Directories are hashed by recursively walking the full tree
+// and folding in every nested file's own content hash — this is an absolute
+// safety invariant (R19), so a mutation nested arbitrarily deep under a
+// managed directory (e.g. a `copy`-mode global install materializing a
+// nested source tree) must still be detected, not just a top-level stat
+// summary. These are small, provider-managed directories (skills/agents/
+// hook scripts), never arbitrary user content, so full content hashing stays
+// cheap.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const providers_1 = require("../../providers");
+function hashFileContent(target) {
+    return crypto_1.default.createHash('sha256').update(fs_1.default.readFileSync(target)).digest('hex');
+}
+/**
+ * Recursively walks `dir`, producing a digest that changes if ANY nested
+ * file's content changes at ANY depth, or any entry is added/removed/renamed/
+ * changes kind (file/dir/symlink) — not just the top-level entries.
+ *
+ * `exclude` names absolute paths to omit entirely — not just their content,
+ * but their very presence as an entry — from the hash. This exists because
+ * Codex's hook scripts directory (`~/.awm/hooks/codex/`) is physically NESTED
+ * inside Claude's own hook scripts directory (`~/.awm/hooks/` —
+ * providers/index.ts), so a naive full recursive hash of Claude's scriptsDir
+ * would flag a REAL Codex hook install as "Claude's baseline changed" — first
+ * by content, and (if merely masked to a placeholder rather than fully
+ * dropped) still by the sibling directory's mere appearance/disappearance as
+ * an entry — either way making R19's guard permanently unsatisfiable for any
+ * Codex init that actually installs its hook (caught via Task 9's real
+ * end-to-end init test). Fully omitting another agent's own managed paths
+ * keeps the guard scoped to what it's meant to protect — content Claude
+ * itself owns — without weakening it for genuine Claude-owned changes.
+ */
+function hashDirectoryTree(dir, exclude) {
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(dir).sort();
+    }
+    catch {
+        return 'unreadable';
+    }
+    const parts = entries
+        .filter((name) => !exclude.has(path_1.default.resolve(path_1.default.join(dir, name))))
+        .map((name) => {
+        const p = path_1.default.join(dir, name);
+        let s;
+        try {
+            s = fs_1.default.lstatSync(p);
+        }
+        catch {
+            return `${name}:missing`;
+        }
+        if (s.isSymbolicLink()) {
+            try {
+                return `${name}:l:${fs_1.default.readlinkSync(p)}`;
+            }
+            catch {
+                return `${name}:l:unreadable`;
+            }
+        }
+        if (s.isDirectory()) {
+            return `${name}:d:${hashDirectoryTree(p, exclude)}`;
+        }
+        try {
+            return `${name}:f:${hashFileContent(p)}`;
+        }
+        catch {
+            return `${name}:f:unreadable`;
+        }
+    });
+    return parts.join('|');
+}
+function hashPath(target, exclude) {
+    let stat;
+    try {
+        stat = fs_1.default.lstatSync(target);
+    }
+    catch {
+        return 'absent';
+    }
+    if (stat.isSymbolicLink()) {
+        return `symlink:${fs_1.default.readlinkSync(target)}`;
+    }
+    if (stat.isDirectory()) {
+        return `dir:${hashDirectoryTree(target, exclude)}`;
+    }
+    return `file:${hashFileContent(target)}`;
+}
+/** Paths that materially represent `agent`'s managed AWM state (hook, injection, artifact dirs). */
+function providerManagedPaths(agent) {
+    const provider = (0, providers_1.providerFor)(agent);
+    const paths = new Set();
+    if (provider.hooks) {
+        paths.add(provider.hooks.settingsPath);
+        paths.add(provider.hooks.scriptsDir);
+    }
+    if (provider.injection) {
+        if (provider.injection.type === 'config-instructions')
+            paths.add(provider.injection.configPath);
+        if (provider.injection.type === 'managed-agents-md')
+            paths.add(provider.injection.globalPath);
+    }
+    if (provider.skill)
+        paths.add(provider.skill.global);
+    if (provider.workflow)
+        paths.add(provider.workflow.global);
+    if (provider.agent)
+        paths.add(provider.agent.global);
+    return Array.from(paths).sort();
+}
+/** Every OTHER agent's own managed paths, resolved — see hashDirectoryTree's docstring:
+ *  these get excluded from `agent`'s recursive hash so a sibling agent's writes to a
+ *  path nested inside `agent`'s own managed directory (Codex's scriptsDir under
+ *  Claude's, today) don't register as a change to `agent`'s baseline. */
+function otherAgentManagedPaths(agent) {
+    const out = new Set();
+    for (const other of providers_1.AGENT_TARGETS) {
+        if (other === agent)
+            continue;
+        for (const p of providerManagedPaths(other))
+            out.add(path_1.default.resolve(p));
+    }
+    return out;
+}
+/** Snapshots `agent`'s managed AWM state. Pure read — never writes. */
+function gatherProviderFacts(agent) {
+    const paths = providerManagedPaths(agent);
+    const exclude = otherAgentManagedPaths(agent);
+    const hash = crypto_1.default.createHash('sha256');
+    for (const p of paths) {
+        hash.update(p).update('\0').update(hashPath(p, exclude)).update('\0');
+    }
+    return { agent, paths, hash: hash.digest('hex') };
+}
+/**
+ * Throws when `before`/`after` diverge — i.e. Claude's managed state changed
+ * during an init run that targeted a different agent. `before`/`after` must
+ * both be for the SAME agent (mismatched agents is a caller bug, not a
+ * baseline violation, so it throws a distinct message).
+ */
+function assertClaudeBaselinePreserved(before, after) {
+    if (before.agent !== after.agent) {
+        throw new Error(`assertClaudeBaselinePreserved: mismatched agents (${before.agent} vs ${after.agent})`);
+    }
+    if (before.hash !== after.hash) {
+        throw new Error(`Claude Code baseline changed during a non-Claude init — this must never happen (R19). ` +
+            `Inspected: ${before.paths.join(', ')}`);
+    }
+}

package/dist/src/core/init/steps.js

@@ -29,9 +29,11 @@ const context_1 = require("../diagnostics/context");
 const detector_1 = require("./detector");
 const orchestrator_1 = require("../context/orchestrator");
 const providers_1 = require("../../providers");
+const install_planner_1 = require("../install-planner");
 const skill_integrity_1 = require("../skill-integrity");
 const registries_2 = require("../registries");
 const project_constitution_inject_1 = require("../context/project-constitution-inject");
+const codex_agents_1 = require("../context/strategies/codex-agents");
 // ---------------------------------------------------------------------------
 // defaultActions — bridges the real functions to the InitActions interface
 // ---------------------------------------------------------------------------
@@ -43,6 +45,9 @@ exports.defaultActions = {
         registryRoot: o.registryRoot,
         installMethod: o.installMethod,
     }),
+    // No `applyPlan` override here — installBundle defaults to the real
+    // applyInstallPlan (install-transaction.ts, Task 6), so this materializes
+    // for real on the `awm init` code path.
     installBundle: (o) => (0, bundle_install_1.installBundle)({
         bundleName: o.bundleName,
         bundles: o.bundles,
@@ -51,6 +56,7 @@ exports.defaultActions = {
         projectRoot: o.projectRoot,
         contentDir: o.contentDir,
     }),
+    // Same as installBundle above — defaults to the real applyInstallPlan.
     syncProfile: (o) => (0, bundle_install_1.syncProfile)({
         projectRoot: o.projectRoot,
         bundles: o.bundles,
@@ -68,7 +74,12 @@ exports.defaultActions = {
     contextStatus: (op) => realInjectionOrchestrator.contextStatus(op),
     installContext: (op) => { realInjectionOrchestrator.installContext(op); },
     repairGlobalSkills: (skillsDir, registryContentDirs) => (0, skill_integrity_1.repairGlobalSkills)(skillsDir, registryContentDirs),
-    injectProjectConstitution: (o) => (0, project_constitution_inject_1.injectProjectConstitution)(o.projectRoot, o.agent),
+    injectProjectConstitution: (o) => {
+        if ((0, providers_1.getInjection)(o.agent)?.type === 'managed-agents-md') {
+            return new codex_agents_1.CodexAgentsStrategy().injectProject(o.projectRoot) === 'injected' ? 'injected' : 'already';
+        }
+        return (0, project_constitution_inject_1.injectProjectConstitution)(o.projectRoot, o.agent);
+    },
 };
 // ---------------------------------------------------------------------------
 // Step helpers
@@ -82,6 +93,42 @@ function failed(id, level, error) {
 // ---------------------------------------------------------------------------
 // Machine-level steps
 // ---------------------------------------------------------------------------
+/**
+ * Agents to pass as `agents` when auto-installing a global-scope bundle for
+ * `d.agent`: `d.agent` itself, plus every other currently-enabled agent that
+ * shares `d.agent`'s physical skill directory (today: OpenCode and Codex
+ * both resolve to `~/.agents/skills`, see providers/index.ts). Baseline/
+ * ambient bundles always install at 'global' scope (bundles.ts's
+ * `defaultScopeForBundle` — 'baseline'/'ambient' never map to 'local'), so
+ * scope is fixed here rather than threaded through InitDeps.
+ *
+ * Without this, a `[d.agent]` singleton would make install-planner.ts's
+ * `assertCompleteSharedGroup` (R14) refuse the install outright whenever a
+ * co-owner is independently enabled (e.g. `awm init --agent codex` on a
+ * machine with OpenCode already enabled) — that was a BLOCKER: it broke the
+ * exact "multiple providers coexist on one machine" scenario this plan
+ * exists to deliver. Including the co-owner here is safe: it already has
+ * this exact skill installed from its own prior init (same source, same
+ * target), so `planInstall`'s dedup (R15/R15.1) collapses it into the same
+ * physical operation and simply re-confirms ownership — it does not change
+ * the co-owner's installed content.
+ */
+function sharedInstallAgents(d) {
+    const group = (0, install_planner_1.agentsSharingSkillTarget)(d.agent, d.enabledAgents, 'global', d.cwd);
+    return group.includes(d.agent) ? group : [d.agent, ...group];
+}
+/**
+ * Same reasoning as `sharedInstallAgents`, but for LOCAL-scope project
+ * extension bundles (`stepActivation`'s `syncProfile` call). OpenCode and
+ * Codex share both their global AND local skill directories
+ * (`providers/index.ts`), so a project with a skill-bearing extension hits
+ * the identical R14 refusal `sharedInstallAgents` was added to avoid — just
+ * scoped to `proj.root` instead of the machine-global directory.
+ */
+function sharedActivationAgents(d, projectRoot) {
+    const group = (0, install_planner_1.agentsSharingSkillTarget)(d.agent, d.enabledAgents, 'local', projectRoot);
+    return group.includes(d.agent) ? group : [d.agent, ...group];
+}
 /** Step 1 – Sync the registry cache (clone / pull). */
 async function stepCache(d) {
     const { registryCache } = d.ctx.machine;
@@ -99,6 +146,16 @@ async function stepCache(d) {
 }
 /** Step 2 – Install the session-start hook for the target agent. */
 function stepHook(d) {
+    // Not every agent has a hook mechanism (today: OpenCode, Antigravity —
+    // providers/index.ts's `hooks` is optional). Mirrors provider-checks.ts's
+    // `hookTrustCheck`, which treats a missing `hooks` config as "not
+    // applicable" rather than a failure. Without this guard, a real
+    // (unstubbed) `awm init --agent opencode` throws "hooks not supported for
+    // agent target: opencode" from `installHook` — a real, previously-latent
+    // bug caught while building this plan's real end-to-end init test
+    // (tests/integration/codex-provider-isolated.test.ts).
+    if (!(0, providers_1.providerFor)(d.agent).hooks)
+        return ok('machine.hook', 'machine', 'skipped', 'no hook mechanism for this agent');
     const { hook } = d.ctx.machine;
     if (hook.present && !hook.degraded)
         return ok('machine.hook', 'machine', 'skipped');
@@ -121,7 +178,7 @@ function stepDevCore(d) {
     d.actions.installBundle({
         bundleName,
         bundles: d.bundles,
-        agents: [d.agent],
+        agents: sharedInstallAgents(d),
         method: d.installMethod,
         projectRoot: d.cwd,
         contentDir: d.contentDir,
@@ -134,7 +191,7 @@ function stepGlobalSkillsRepair(d) {
     const broken = globalSkills.repairable.length + globalSkills.dead.length;
     if (broken === 0)
         return ok('machine.globalSkills', 'machine', 'skipped');
-    const skillsDir = providers_1.PROVIDERS[d.agent].skill.global;
+    const skillsDir = (0, providers_1.providerFor)(d.agent).skill.global;
     const r = d.actions.repairGlobalSkills(skillsDir, (0, registries_2.contentRoots)());
     return ok('machine.globalSkills', 'machine', 'applied', `re-linked ${r.relinked.length}, pruned ${r.pruned.length}`);
 }
@@ -150,7 +207,7 @@ function stepAmbient(d) {
         d.actions.installBundle({
             bundleName,
             bundles: d.bundles,
-            agents: [d.agent],
+            agents: sharedInstallAgents(d),
             method: d.installMethod,
             projectRoot: d.cwd,
             contentDir: d.contentDir,
@@ -206,7 +263,7 @@ function stepActivation(d) {
     d.actions.syncProfile({
         projectRoot: proj.root,
         bundles: d.bundles,
-        agents: [d.agent],
+        agents: sharedActivationAgents(d, proj.root),
         method: d.installMethod,
         contentDir: d.contentDir,
     });
@@ -231,17 +288,16 @@ function stepConstitution(d) {
         return ok('project.constitution', 'project', 'skipped');
     return ok('project.constitution', 'project', 'pending', 'skill: project-constitution');
 }
-/** Step 8b – Entregar CONSTITUTION.md a agentes con inyección config-instructions
- *  (opencode) vía un opencode.json local del proyecto. Claude lo recibe por el hook. */
+/** Step 8b – Deliver project guidance via the provider-specific context mechanism. */
 function stepConstitutionInjection(d) {
     const proj = d.ctx.project;
     if (!proj)
         return ok('project.constitutionInjection', 'project', 'skipped', 'no project');
     const inj = (0, providers_1.getInjection)(d.agent);
-    if (!inj || inj.type !== 'config-instructions') {
+    if (!inj || inj.type === 'cc-settings-merge') {
         return ok('project.constitutionInjection', 'project', 'skipped', 'covered by hook');
     }
-    if (!proj.constitution.present) {
+    if (inj.type === 'config-instructions' && !proj.constitution.present) {
         return ok('project.constitutionInjection', 'project', 'skipped', 'no CONSTITUTION.md');
     }
     const res = d.actions.injectProjectConstitution({ projectRoot: proj.root, agent: d.agent });

package/dist/src/core/install-planner.js

@@ -0,0 +1,206 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.physicalTarget = physicalTarget;
+exports.skillTargetDir = skillTargetDir;
+exports.agentsSharingSkillTarget = agentsSharingSkillTarget;
+exports.planInstall = planInstall;
+exports.planRemoval = planRemoval;
+// src/core/install-planner.ts
+//
+// Pure planning layer for artifact install/removal: no filesystem writes.
+// Given artifact intents and a set of agent targets, computes the physical
+// operations to perform, deduping targets that multiple agents' provider
+// configs happen to resolve to the same directory (e.g. OpenCode and Codex
+// both point their `skill` config at ~/.agents/skills), and tracks ownership
+// so a later removal can tell whether a shared target is still needed by
+// another agent before deleting it.
+//
+// Task 6 (applyInstallPlan) consumes InstallPlan/RemovalPlan to perform the
+// actual transactional filesystem writes, backups, and ManagedArtifactRecord
+// persistence (artifact-state.ts). This module only computes the plan.
+const path_1 = __importDefault(require("path"));
+const providers_1 = require("../providers");
+/** Resolves the single physical filesystem location an intent renders to for one agent. */
+/**
+ * Resolves the physical target path + renderer for one artifact intent on one
+ * agent (dir + filename, applying the `.toml` rename for `codex-agent-toml`).
+ * Shared with `core/init/mutation-targets.ts`, which needs the exact same
+ * dir/filename computation to enumerate paths before a real `awm init` run —
+ * duplicating this logic there would let the two silently diverge.
+ */
+function physicalTarget(intent, agent, scope, projectRoot) {
+    const config = (0, providers_1.providerFor)(agent)[intent.type];
+    if (!config)
+        throw new Error(`${intent.type}s are not supported by ${(0, providers_1.providerFor)(agent).label}`);
+    const dir = scope === 'local' ? path_1.default.join(projectRoot, config.local) : config.global;
+    const filename = config.renderer === 'codex-agent-toml'
+        ? `${path_1.default.parse(intent.installName).name}.toml`
+        : intent.installName;
+    return { targetPath: path_1.default.join(dir, filename), renderer: config.renderer };
+}
+/**
+ * The physical directory `agent`'s skill artifacts resolve to at `scope` —
+ * independent of any specific artifact/intent, since every skill intent for
+ * a given agent+scope shares the same directory and only the filename
+ * inside it varies (`physicalTarget`'s `dir` component, without the
+ * filename). Exposed so callers that need to answer "does agent X share
+ * agent Y's skill target?" purely structurally — e.g. deciding which agents
+ * to proactively include in a `selectedAgents` set — don't need to invent a
+ * throwaway `ArtifactIntent` just to ask a directory-equality question.
+ */
+function skillTargetDir(agent, scope, projectRoot) {
+    const config = (0, providers_1.providerFor)(agent).skill;
+    return scope === 'local' ? path_1.default.join(projectRoot, config.local) : config.global;
+}
+/**
+ * Of `candidates`, the ones that share `agent`'s skill physical target at
+ * `scope` (includes `agent` itself when it appears in `candidates`). Used by
+ * `core/init/steps.ts` to compute the correct `selectedAgents` for an
+ * automatic baseline/ambient bundle install: `stepDevCore`/`stepAmbient`
+ * used to pass a `[agent]` singleton, which `assertCompleteSharedGroup`
+ * below (R14) then refused whenever a co-owner (e.g. OpenCode alongside
+ * Codex) was independently enabled — a BLOCKER that made `awm init --agent
+ * codex` structurally fail once OpenCode was already enabled, and vice
+ * versa. Passing the complete shared group up front avoids tripping R14 in
+ * the first place, without weakening the assertion itself.
+ */
+function agentsSharingSkillTarget(agent, candidates, scope, projectRoot) {
+    const target = skillTargetDir(agent, scope, projectRoot);
+    return candidates.filter((candidate) => skillTargetDir(candidate, scope, projectRoot) === target);
+}
+/**
+ * Skills are, today, the only artifact type where two agents' provider
+ * configs physically resolve to the exact same directory (OpenCode and Codex
+ * both use `~/.agents/skills` globally). Because that target is shared,
+ * selecting only part of the group sharing it would either strand the
+ * unselected agent's install or silently delete on its behalf. Refuse the
+ * whole change instead (R14): every enabled agent that shares a given
+ * skill's physical target with a selected agent must itself be selected.
+ */
+function assertCompleteSharedGroup(intent, selected, enabled, scope, projectRoot) {
+    if (intent.type !== 'skill')
+        return;
+    for (const agent of selected) {
+        const target = physicalTarget(intent, agent, scope, projectRoot).targetPath;
+        const group = enabled.filter((candidate) => physicalTarget(intent, candidate, scope, projectRoot).targetPath === target);
+        if (group.some((candidate) => !selected.includes(candidate))) {
+            throw new Error(`Shared skill target cannot diverge; select the complete shared target group: ${group.join(',')}`);
+        }
+    }
+}
+/**
+ * Plans installation of `artifacts` for `selectedAgents`. Pure — no
+ * filesystem access. Groups by physical location (targetPath + renderer) —
+ * NOT sourcePath: a target path is one filesystem location, so at most one
+ * source may back it. When two selected agents resolve an intent to the
+ * identical physical location with the SAME sourcePath, they collapse into a
+ * single PlannedOperation with both agents listed as owners (R15/R15.1), so
+ * the operation is only ever performed once. When two intents resolve to the
+ * same physical location with DIFFERENT sourcePaths (e.g. same skill name
+ * shipped by two different registries), that is a genuine conflict — one
+ * target can't be backed by two different sources — and planInstall throws
+ * before producing any operations, in the same "abort before writes" spirit
+ * as assertCompleteSharedGroup's shared-group error. Independently addressed
+ * artifact types (workflow, agent) never collapse across agents, since each
+ * agent's provider config points at its own directory (R12/R13). An artifact
+ * type unsupported by a given agent (provider config is null for that type)
+ * is silently skipped for that agent, mirroring the legacy installBundle
+ * skip semantics — it is not an error.
+ *
+ * Within a shared group, the first owner (in selection order) is reported
+ * with action 'install' (it is the one that causes the operation) and any
+ * additional co-owners are reported 'retain' (the write already covers
+ * them; they simply gain ownership of it).
+ */
+function planInstall(params) {
+    const { artifacts, selectedAgents, enabledAgents, scope, projectRoot, method } = params;
+    for (const intent of artifacts) {
+        assertCompleteSharedGroup(intent, selectedAgents, enabledAgents, scope, projectRoot);
+    }
+    const groups = new Map();
+    for (const intent of artifacts) {
+        for (const agent of selectedAgents) {
+            const config = (0, providers_1.providerFor)(agent)[intent.type];
+            if (!config)
+                continue;
+            const { targetPath, renderer } = physicalTarget(intent, agent, scope, projectRoot);
+            // Key on the physical location alone (targetPath + renderer), NOT
+            // sourcePath: a target path is one filesystem location, so it can
+            // only ever be backed by one source. Including sourcePath in the
+            // key would let two intents with different sources but the same
+            // target silently produce two operations for the same physical
+            // location — see the conflict check just below.
+            const key = `${targetPath}\0${renderer}`;
+            let group = groups.get(key);
+            if (!group) {
+                group = {
+                    name: intent.name,
+                    type: intent.type,
+                    sourcePath: intent.sourcePath,
+                    targetPath,
+                    renderer,
+                    owners: [],
+                };
+                groups.set(key, group);
+            }
+            else if (group.sourcePath !== intent.sourcePath) {
+                throw new Error(`physical target already claimed by a different source: ${targetPath} (${group.sourcePath} vs ${intent.sourcePath})`);
+            }
+            if (!group.owners.includes(agent))
+                group.owners.push(agent);
+        }
+    }
+    const operations = [];
+    const records = [];
+    const reports = [];
+    for (const group of groups.values()) {
+        const record = {
+            name: group.name,
+            type: group.type,
+            scope,
+            targetPath: group.targetPath,
+            sourcePath: group.sourcePath,
+            renderer: group.renderer,
+            owners: group.owners,
+        };
+        records.push(record);
+        operations.push({ ...record, method, output: group.renderer });
+        group.owners.forEach((owner, index) => {
+            reports.push({ owner, targetPath: group.targetPath, action: index === 0 ? 'install' : 'retain' });
+        });
+    }
+    return { operations, records, reports };
+}
+/**
+ * Plans removal of `artifactNames` for `selectedAgents` against the
+ * currently persisted `records`. For each matching record, owners being
+ * removed drop out of its owner list; if any remaining owner is still in
+ * `enabledAgents`, the physical target is retained (R16) — no unlink is
+ * produced, and the record is carried forward with the reduced owner list.
+ * Only when no enabled owner remains does the record become an unlink
+ * operation, dropping out of the returned records. Records for artifacts not
+ * named in `artifactNames` pass through unchanged.
+ */
+function planRemoval(params) {
+    const { records, selectedAgents, enabledAgents, artifactNames } = params;
+    const operations = [];
+    const resultRecords = [];
+    for (const record of records) {
+        if (!artifactNames.includes(record.name)) {
+            resultRecords.push(record);
+            continue;
+        }
+        const remainingOwners = record.owners.filter((owner) => !selectedAgents.includes(owner));
+        const activeOwners = remainingOwners.filter((owner) => enabledAgents.includes(owner));
+        if (activeOwners.length > 0) {
+            resultRecords.push({ ...record, owners: remainingOwners });
+        }
+        else {
+            operations.push({ ...record, owners: remainingOwners, action: 'unlink' });
+        }
+    }
+    return { operations, records: resultRecords };
+}