@webpresso/agent-kit 3.3.4 → 3.3.6

package/dist/esm/symlinker/unified-sync.js

@@ -1,8 +1,8 @@
 /**
- * Unified rule + skill sync.
+ * Unified rule + skill + agent sync.
  *
- * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills}/`) UNION
- * consumer (`<repo>/agent-{rules,skills}/`). The loader returns a
+ * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills,agents}/`)
+ * UNION consumer (`<repo>/agent-{rules,skills,agents}/`). The loader returns a
  * source-tagged record list; this module projects that list into per-IDE
  * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
  *
@@ -16,6 +16,22 @@
  * filename pattern but is not in the expected set is removed. This propagates
  * deletions in `agent-rules/` and `agent-skills/` to per-IDE cleanup.
  *
+ * Ownership: a consumer declares `ownership` (see `UnifiedConsumerConfig`).
+ * On a `shared` surface agent-kit destroys only what it can prove it created,
+ * via the single predicate in `ownership.ts`. Both write paths consult that one
+ * predicate but take DIFFERENT actions, and the asymmetry is deliberate:
+ *
+ *   | path        | situation                          | action                  |
+ *   |-------------|------------------------------------|-------------------------|
+ *   | pruneStale  | nothing in the catalog claims this | leave untouched         |
+ *   |             | name                               |                         |
+ *   | applyTarget | a catalog record DOES claim it     | preserve + skip + warn  |
+ *
+ * Quarantining or deleting an unclaimed file would be gratuitous — it is in
+ * nobody's way. Silently replacing a claimed one is the data-loss bug this
+ * guard exists to prevent, because `.claude/agents` is gitignored and the loss
+ * is unrecoverable.
+ *
  * `--check` mode (dry-run): produce a list of (target, status) pairs and
  * return the count of mismatches; perform no writes.
  */
@@ -24,6 +40,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { loadContent } from "#content/loader";
 import { DEFAULT_PACKAGED_SKILL_SLUG_SET } from "#content/skill-policy";
 import { RETIRED_UNIFIED_CONSUMERS, selectUnifiedConsumers, unifiedRuleFilename, } from "./consumers.js";
+import { isAgentKitOwned, resolveManagedSourceDirs } from "./ownership.js";
 import { pathHasSymlinkComponent } from "./retired-surfaces.js";
 /**
  * Create a symlink with explicit Windows type hint. POSIX ignores the type;
@@ -86,7 +103,9 @@ function planTargets(records, consumers, consumerRoot) {
             const consumerDirAbs = join(consumerRoot, consumer.dir);
             let entryName;
             let targetPath;
-            if (record.kind === "rule") {
+            if (record.kind === "rule" || record.kind === "agent") {
+                // agent records are file-shaped like rules (a single <slug>.md),
+                // not dir-shaped like skills.
                 entryName = unifiedRuleFilename(consumer, record.slug);
                 targetPath = join(consumerDirAbs, entryName);
             }
@@ -168,12 +187,49 @@ function dirsEqual(srcDir, destDir) {
     }
     return true;
 }
+/**
+ * True when applying `plan` would destroy something agent-kit cannot prove it
+ * created, on a surface the user co-owns.
+ *
+ * This is the apply-side half of the ownership question. The prune side asks
+ * the same question via the same predicate but takes a different action, and
+ * the asymmetry is deliberate — see the module docstring.
+ *
+ * An `exclusive` consumer is unaffected: its directory is generated and
+ * gitignored, so replacing an unexpected entry is the intended behavior.
+ */
+function wouldDestroyForeignPath(plan, managedSourceDirs) {
+    if ((plan.consumer.ownership ?? "exclusive") !== "shared")
+        return false;
+    if (!existsSync(plan.targetPath) && !isSymlinkLike(plan.targetPath))
+        return false;
+    return !isAgentKitOwned(plan.targetPath, managedSourceDirs);
+}
+/** `existsSync` follows symlinks, so a dangling link needs its own probe. */
+function isSymlinkLike(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Apply a single planned target. Returns 1 on write, 0 if already correct.
+ *
+ * `preserved` is a third outcome, distinct from both: the projection was
+ * skipped because the target belongs to the operator. It is reported as a
+ * warning, never as drift — see `UnifiedSyncResult`.
  */
-function applyTarget(plan, check) {
+function applyTarget(plan, check, managedSourceDirs) {
     const { consumer, record, targetPath } = plan;
     const sourcePath = record.kind === "skill" ? dirname(record.filePath) : record.filePath;
+    // Gate EVERY strategy, not just the symlink branch: each one below uses its
+    // "is it already what we'd write?" check as the destruction gate, and none of
+    // those checks can distinguish "stale projection" from "operator's file".
+    if (wouldDestroyForeignPath(plan, managedSourceDirs)) {
+        return { wrote: 0, preserved: targetPath };
+    }
     switch (consumer.strategy) {
         case "symlink": {
             // Use the resolved (real) source path so links survive pnpm version churn.
@@ -254,7 +310,7 @@ function applyTarget(plan, check) {
  * managed pattern (rule files: `<slug><ext>`; skill dirs: subdirectories).
  * Real files outside the managed pattern (README.md, .gitkeep) are left alone.
  */
-function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
+function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs, configuredAgentSourceDirs) {
     const expectedByConsumerDir = new Map();
     for (const plan of plans) {
         const key = plan.consumer.dir;
@@ -265,6 +321,16 @@ function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
         }
         set.add(plan.entryName);
     }
+    // Plan-derived source dirs are folded in alongside the configuration-derived
+    // set. The configured set already guarantees non-emptiness (see
+    // `resolveManagedSourceDirs`); the plan-derived entries additionally cover a
+    // consumer override dir the configuration cannot know about.
+    const agentSourceDirs = new Set([
+        ...configuredAgentSourceDirs,
+        ...plans
+            .filter((plan) => plan.record.kind === "agent")
+            .map((plan) => dirname(plan.record.filePath)),
+    ]);
     let removed = 0;
     const mismatches = [];
     // Each unique dir gets a single sweep — multiple consumers can share a dir
@@ -292,15 +358,30 @@ function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
                 preserveSkillSlugs.has(name) &&
                 entry.isDirectory())
                 continue;
-            // Only prune entries that match a managed shape: rule extension OR a
-            // directory (skill).
-            const matchesRulePattern = consumersForDir.some((c) => c.acceptsKind === "rule" && name.endsWith(c.ruleExtension ?? ".md"));
+            // Only prune entries that match a managed shape: rule/agent extension
+            // OR a directory (skill). Agent records are file-shaped like rules.
+            const matchesRulePattern = consumersForDir.some((c) => (c.acceptsKind === "rule" || c.acceptsKind === "agent") &&
+                name.endsWith(c.ruleExtension ?? ".md"));
             const matchesSkillPattern = consumersForDir.some((c) => c.acceptsKind === "skill") && entry.isDirectory();
             // Also handle stale symlinks of either shape.
             const isLink = entry.isSymbolicLink();
             if (!matchesRulePattern && !matchesSkillPattern && !isLink)
                 continue;
             const fullPath = join(dirAbs, name);
+            // Conservative prune on a shared surface: skip real files, real dirs, and
+            // foreign symlinks (anything agent-kit cannot prove it created). The
+            // stance is read from the consumer's DECLARED ownership rather than
+            // inferred from its kind — inference by `.every(c => acceptsKind ===
+            // "agent")` would silently switch the guard off for the whole directory
+            // the moment any non-agent consumer was registered on it.
+            //
+            // Exclusive dirs (rules, skills) are generated and gitignored with no
+            // hand-authoring workflow, so their sweep-everything behavior is
+            // deliberately unchanged.
+            const isSharedDir = consumersForDir.some((c) => (c.ownership ?? "exclusive") === "shared");
+            if (isSharedDir && !isAgentKitOwned(fullPath, agentSourceDirs)) {
+                continue;
+            }
             if (check) {
                 mismatches.push({
                     consumerId: consumersForDir[0]?.id ?? dir,
@@ -348,7 +429,7 @@ function pruneEmptyRetiredConsumerDirs(consumers, consumerRoot, check) {
  * Main entrypoint. See module docstring.
  */
 export function runUnifiedSync(options) {
-    const kinds = options.kinds ?? ["rule", "skill"];
+    const kinds = options.kinds ?? ["rule", "skill", "agent"];
     const kindSet = new Set(kinds);
     const consumers = (options.consumers ?? selectUnifiedConsumers(options.hosts)).filter((consumer) => kindSet.has(consumer.acceptsKind));
     const activeDirs = new Set(consumers.map((consumer) => consumer.dir));
@@ -379,10 +460,27 @@ export function runUnifiedSync(options) {
         throw new Error(`wp sync: slug collisions between catalog and consumer (rename consumer copy):\n${lines.join("\n")}`);
     }
     const plans = planTargets(filteredRecords, consumers, consumerRoot);
+    // The directories agent-kit projects agent records from. Configuration-
+    // derived and therefore never empty, so a broken install cannot collapse
+    // ownership into "everything is ours". Owned by ownership.ts, shared by the
+    // apply and prune paths so they cannot answer the question differently.
+    const configuredAgentSourceDirs = resolveManagedSourceDirs({
+        catalogDir: options.catalogDir,
+        consumerRoot,
+    });
     let fixCount = 0;
     const mismatches = [];
+    const preserved = [];
     for (const plan of plans) {
-        const result = applyTarget(plan, options.check === true);
+        const result = applyTarget(plan, options.check === true, configuredAgentSourceDirs);
+        if (result.preserved !== undefined) {
+            preserved.push({
+                consumerId: plan.consumer.id,
+                targetPath: result.preserved,
+                slug: plan.record.slug,
+            });
+            continue;
+        }
         if (result.wrote > 0) {
             fixCount += result.wrote;
             if (options.check === true && result.mismatch !== undefined) {
@@ -394,14 +492,14 @@ export function runUnifiedSync(options) {
             }
         }
     }
-    const prune = pruneStale(plans, consumers, consumerRoot, options.check === true, options.preserveSkillSlugs);
+    const prune = pruneStale(plans, consumers, consumerRoot, options.check === true, options.preserveSkillSlugs, configuredAgentSourceDirs);
     fixCount += prune.removed;
     mismatches.push(...prune.mismatches);
-    const retiredPrune = pruneStale([], retiredConsumers, consumerRoot, options.check === true, undefined);
+    const retiredPrune = pruneStale([], retiredConsumers, consumerRoot, options.check === true, undefined, configuredAgentSourceDirs);
     fixCount += retiredPrune.removed;
     mismatches.push(...retiredPrune.mismatches);
     const retiredDirectories = pruneEmptyRetiredConsumerDirs(retiredConsumers, consumerRoot, options.check === true);
     fixCount += retiredDirectories.removed;
     mismatches.push(...retiredDirectories.mismatches);
-    return { fixCount, mismatches };
+    return { fixCount, mismatches, preserved };
 }

package/dist/esm/test/shard-durations.json

@@ -296,7 +296,6 @@
             "src/hooks/dispatch/index.test.ts": 11.771874999999994,
             "src/hooks/shared/hook-bootstrap.test.ts": 58.217375000000004,
             "src/cli/commands/init/scaffolders/agent-hooks/emitters/grok.test.ts": 67.57654199999999,
-            "src/cli/commands/init/scaffolders/subagents/index.test.ts": 49.99270800000005,
             "src/blueprint/core/validation/criteria.test.ts": 9.635125000000016,
             "src/cli/commands/session.test.ts": 662.8378339999999,
             "src/cli/commands/dash/run-registry.test.ts": 793.002083,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpresso/agent-kit",
-  "version": "3.3.4",
+  "version": "3.3.6",
   "private": false,
   "description": "TypeScript-first agent harness for guarded develop/deploy workflows: wp CLI gates, MCP tools, hooks, memory, worktrees, secrets, audits, and evidence checks.",
   "keywords": [
@@ -514,16 +514,16 @@
     "setupWpActionRef": "c2c71a7a4be446fc6858e6b57bf55a11ccfa2d88"
   },
   "optionalDependencies": {
-    "@webpresso/agent-kit-runtime-darwin-arm64": "3.3.4",
-    "@webpresso/agent-kit-runtime-darwin-x64": "3.3.4",
-    "@webpresso/agent-kit-runtime-linux-x64": "3.3.4",
-    "@webpresso/agent-kit-runtime-linux-arm64": "3.3.4",
-    "@webpresso/agent-kit-runtime-windows-x64": "3.3.4",
-    "@webpresso/agent-kit-session-memory-darwin-x64": "3.3.4",
-    "@webpresso/agent-kit-session-memory-darwin-arm64": "3.3.4",
-    "@webpresso/agent-kit-session-memory-linux-x64": "3.3.4",
-    "@webpresso/agent-kit-session-memory-linux-arm64": "3.3.4",
-    "@webpresso/agent-kit-session-memory-win32-x64": "3.3.4",
-    "@webpresso/agent-kit-session-memory-win32-arm64": "3.3.4"
+    "@webpresso/agent-kit-runtime-darwin-arm64": "3.3.6",
+    "@webpresso/agent-kit-runtime-darwin-x64": "3.3.6",
+    "@webpresso/agent-kit-runtime-linux-x64": "3.3.6",
+    "@webpresso/agent-kit-runtime-linux-arm64": "3.3.6",
+    "@webpresso/agent-kit-runtime-windows-x64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-darwin-x64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-darwin-arm64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-linux-x64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-linux-arm64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-win32-x64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-win32-arm64": "3.3.6"
   }
 }

package/dist/esm/cli/commands/init/scaffolders/subagents/index.d.ts

@@ -1,6 +0,0 @@
-import type { MergeOptions, MergeResult } from "#cli/commands/init/merge";
-export interface ScaffoldSubagentsInput {
-    repoRoot: string;
-    options: MergeOptions;
-}
-export declare function scaffoldSubagents(input: ScaffoldSubagentsInput): MergeResult[];

package/dist/esm/cli/commands/init/scaffolders/subagents/index.js

@@ -1,77 +0,0 @@
-import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync, } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { readPackageJson } from "#cli/commands/init/detect-consumer";
-import { resolveAgentKitPackageRootOrThrow } from "#cli/commands/init/package-root";
-function detectMode(repoRoot) {
-    const pkg = readPackageJson(repoRoot).info;
-    if (pkg?.name === "@webpresso/agent-kit") {
-        return {
-            mode: "self",
-            sourceRoot: join(repoRoot, "catalog", "agent", "agents"),
-        };
-    }
-    const installedPackageJsonPath = join(repoRoot, "node_modules", "@webpresso", "agent-kit", "package.json");
-    const installedAgentsRoot = join(repoRoot, "node_modules", "@webpresso", "agent-kit", "catalog", "agent", "agents");
-    if (existsSync(installedPackageJsonPath) && existsSync(installedAgentsRoot)) {
-        return {
-            mode: "consumer",
-            sourceRoot: installedAgentsRoot,
-        };
-    }
-    return {
-        mode: "package-fallback",
-        sourceRoot: join(resolveCurrentPackageRoot(), "catalog", "agent", "agents"),
-    };
-}
-function resolveCurrentPackageRoot() {
-    return resolveAgentKitPackageRootOrThrow("wp init: could not locate the webpresso package root for subagents fallback.", { requireCatalog: true });
-}
-export function scaffoldSubagents(input) {
-    const { repoRoot, options } = input;
-    const mode = detectMode(repoRoot);
-    const sourceRoot = mode.sourceRoot;
-    const targetRoot = join(repoRoot, ".claude", "agents");
-    const results = [];
-    if (!existsSync(sourceRoot))
-        return results;
-    const entries = readdirSync(sourceRoot).filter((f) => f.endsWith(".md") && f !== "README.md");
-    if (entries.length === 0)
-        return results;
-    if (!options.dryRun) {
-        mkdirSync(targetRoot, { recursive: true });
-    }
-    for (const name of entries) {
-        const sourcePath = join(sourceRoot, name);
-        const targetPath = join(targetRoot, name);
-        const symTarget = relative(dirname(targetPath), sourcePath);
-        if (options.dryRun) {
-            results.push({ targetPath, action: "created" });
-            continue;
-        }
-        try {
-            const stat = lstatSync(targetPath);
-            if (stat.isSymbolicLink()) {
-                const currentTarget = readlinkSync(targetPath);
-                if (currentTarget === symTarget) {
-                    results.push({ targetPath, action: "identical" });
-                }
-                else if (options.overwrite) {
-                    rmSync(targetPath);
-                    symlinkSync(symTarget, targetPath);
-                    results.push({ targetPath, action: "overwritten" });
-                }
-                else {
-                    results.push({ targetPath, action: "drifted" });
-                }
-            }
-            else {
-                results.push({ targetPath, action: "identical" });
-            }
-        }
-        catch {
-            symlinkSync(symTarget, targetPath);
-            results.push({ targetPath, action: "created" });
-        }
-    }
-    return results;
-}