@webpresso/agent-kit 3.3.4 → 3.3.6

package/dist/esm/mcp/blueprint/handlers/document-mutations.d.ts

@@ -1,5 +1,80 @@
+import { z } from "zod";
 import type { ProjectResolver } from "#project-resolver.js";
 import type { ToolHandlerResult } from "#mcp/auto-discover.js";
+declare const putDocumentSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"blueprint">>;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        archived: "archived";
+        completed: "completed";
+        draft: "draft";
+        "in-progress": "in-progress";
+        parked: "parked";
+        planned: "planned";
+    }>;
+    complexity: z.ZodEnum<{
+        L: "L";
+        M: "M";
+        S: "S";
+        XL: "XL";
+        XS: "XS";
+    }>;
+    owner: z.ZodString;
+    created: z.ZodString;
+    last_updated: z.ZodString;
+    progress: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    product_wedge_anchor: z.ZodObject<{
+        stage_outcome: z.ZodString;
+        consuming_surface: z.ZodString;
+        new_user_visible_capability: z.ZodString;
+    }, z.core.$strip>;
+    summary: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodDefault<z.ZodEnum<{
+            blocked: "blocked";
+            done: "done";
+            dropped: "dropped";
+            "in-progress": "in-progress";
+            todo: "todo";
+        }>>;
+        wave: z.ZodOptional<z.ZodString>;
+        lane: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        acceptance: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    trust_dossier: z.ZodOptional<z.ZodObject<{
+        readiness: z.ZodObject<{
+            promotion_ready: z.ZodBoolean;
+            unresolved_count: z.ZodNumber;
+            verified_at: z.ZodString;
+            verified_head: z.ZodString;
+            trust_gate_version: z.ZodString;
+        }, z.core.$strip>;
+        material_claims: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            claim: z.ZodString;
+            evidence: z.ZodString;
+        }, z.core.$strip>>;
+        material_decisions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            decision: z.ZodString;
+            chosen_option: z.ZodString;
+            rejected_alternatives: z.ZodString;
+            rationale: z.ZodString;
+        }, z.core.$strip>>;
+        promotion_gates: z.ZodArray<z.ZodObject<{
+            gate: z.ZodString;
+            command: z.ZodString;
+            expected_outcome: z.ZodString;
+            last_result: z.ZodString;
+            defer: z.ZodOptional<z.ZodLiteral<"pre-implementation">>;
+        }, z.core.$strip>>;
+        residual_unknowns: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const putInputJsonSchema: {
     type: string;
     properties: {
@@ -233,6 +308,28 @@ export declare const putInputJsonSchema: {
     };
     required: string[];
 };
+/**
+ * Promotion-grade dossier completeness (promotion-ready: true,
+ * unresolved-count: 0, Residual Unknowns exactly `None.`, non-empty material
+ * claims/decisions/gates, passing gate results) is a PROMOTION-time
+ * requirement, not a draft-authoring one. `wp_blueprint_put` only ever writes
+ * `status: draft` documents (see the refusal in `handleBlueprintPut` above);
+ * gating every intermediate draft save on full promotion readiness forced
+ * authors to either fabricate readiness fields or keep genuinely-finished
+ * tasks marked `todo` to dodge the "checked box implies unreviewed
+ * completion" ambiguity scan -- inverting the draft -> planned lifecycle.
+ *
+ * `promotionCandidate` is therefore derived from the document's OWN target
+ * `status`, not hardcoded: a `draft` target skips promotion-grade dossier
+ * completeness entirely (an incomplete/in-progress dossier round-trips
+ * as-is), while any non-draft target keeps today's full strictness
+ * unchanged. Real promotion strictness is enforced separately and
+ * unconditionally at `wp_blueprint_transition`'s `crossesDraftApprovalBoundary`
+ * gate (`applyPromotionTrustGate` in `#trust/promotion.ts`), which still
+ * hardcodes `promotionCandidate: true` and is untouched by this function.
+ */
+export declare function validatePutTrustDossier(repoRoot: string, file: string, markdown: string, targetStatus: z.infer<typeof putDocumentSchema>["status"]): string | null;
 export declare function handleBlueprintPut(projectResolver: ProjectResolver, cwd: string, raw: unknown): Promise<ToolHandlerResult>;
 export declare function handleBlueprintTransition(projectResolver: ProjectResolver, cwd: string, raw: unknown): Promise<ToolHandlerResult>;
 export declare function handleBlueprintCreate(projectResolver: ProjectResolver, cwd: string, raw: unknown): Promise<ToolHandlerResult>;
+export {};

package/dist/esm/mcp/blueprint/handlers/document-mutations.js

@@ -427,13 +427,33 @@ function describeEvidenceLossRefusal(taskId, submittedStatus) {
         `that evidence. Keep task ${taskId} present with status "done" in the payload; put will carry ` +
         `the recorded evidence forward automatically.`);
 }
-function validatePutTrustDossier(repoRoot, file, markdown) {
+/**
+ * Promotion-grade dossier completeness (promotion-ready: true,
+ * unresolved-count: 0, Residual Unknowns exactly `None.`, non-empty material
+ * claims/decisions/gates, passing gate results) is a PROMOTION-time
+ * requirement, not a draft-authoring one. `wp_blueprint_put` only ever writes
+ * `status: draft` documents (see the refusal in `handleBlueprintPut` above);
+ * gating every intermediate draft save on full promotion readiness forced
+ * authors to either fabricate readiness fields or keep genuinely-finished
+ * tasks marked `todo` to dodge the "checked box implies unreviewed
+ * completion" ambiguity scan -- inverting the draft -> planned lifecycle.
+ *
+ * `promotionCandidate` is therefore derived from the document's OWN target
+ * `status`, not hardcoded: a `draft` target skips promotion-grade dossier
+ * completeness entirely (an incomplete/in-progress dossier round-trips
+ * as-is), while any non-draft target keeps today's full strictness
+ * unchanged. Real promotion strictness is enforced separately and
+ * unconditionally at `wp_blueprint_transition`'s `crossesDraftApprovalBoundary`
+ * gate (`applyPromotionTrustGate` in `#trust/promotion.ts`), which still
+ * hardcodes `promotionCandidate: true` and is untouched by this function.
+ */
+export function validatePutTrustDossier(repoRoot, file, markdown, targetStatus) {
     const validated = validateBlueprintTrust({
         repoRoot,
         file,
         status: "draft",
         markdown,
-        promotionCandidate: true,
+        promotionCandidate: targetStatus !== "draft",
         requirePassingGates: false,
         scanTaskAmbiguity: true,
     });
@@ -509,7 +529,7 @@ export async function handleBlueprintPut(projectResolver, cwd, raw) {
             markdown = preserved.markdown;
         }
         if (document.trust_dossier) {
-            const trustDossierFailure = validatePutTrustDossier(writeCwd, overviewPath, markdown);
+            const trustDossierFailure = validatePutTrustDossier(writeCwd, overviewPath, markdown, document.status);
             if (trustDossierFailure) {
                 return err("wp_blueprint_put validation error", trustDossierFailure);
             }

package/dist/esm/mcp/blueprint/handlers/finalize.js

@@ -7,7 +7,7 @@ import { ensureProjectionReady } from "#projection-ready.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 import { dbPath } from "#mcp/blueprint/_shared/db";
 import { err, finishPayload, jsonContent } from "#mcp/blueprint/_shared/errors";
-import { applyLocalBlueprintTransition, assertBlueprintCanComplete, NON_COMPLETED_BLUEPRINT_STATES, } from "#mcp/blueprint/_shared/lifecycle";
+import { applyLocalBlueprintTransition, collectBlueprintCompletionBlockers, NON_COMPLETED_BLUEPRINT_STATES, } from "#mcp/blueprint/_shared/lifecycle";
 import { toStr } from "#mcp/blueprint/_shared/payload";
 import { findBlueprintDir, resolveToolProject } from "#mcp/blueprint/_shared/project";
 import { resolveSyncAdapter, runPlatformMutationSync } from "#mcp/blueprint/_shared/sync";
@@ -53,8 +53,6 @@ export async function handleFinalize(projectResolver, cwd, raw) {
     finally {
         conn.close();
     }
-    if (openTasks.length > 0)
-        return err("wp_blueprint_finalize refused", `Blueprint "${slug}" has open tasks: ${openTasks.map((t) => `${t.task_id} (${t.status})`).join(", ")}`);
     const root = resolveBlueprintRoot(projectCwd);
     const found = findBlueprintDir(root, slug, NON_COMPLETED_BLUEPRINT_STATES);
     if (!found) {
@@ -69,11 +67,24 @@ export async function handleFinalize(projectResolver, cwd, raw) {
             });
         return err("wp_blueprint_finalize failed", `Blueprint "${slug}" not found`);
     }
-    try {
-        assertBlueprintCanComplete(found.path, slug);
+    // Gather EVERY blocking condition up front, from every check this handler
+    // (and applyLocalBlueprintTransition, invoked later) is capable of raising
+    // — open tasks per the DB projection, zero-task/unfinished-task/missing-
+    // evidence per the raw markdown, doc-validate gaps, and the completed
+    // approval/digest gate. Refusing once per condition costs one failed
+    // round-trip per fix; a single combined refusal costs one. This also
+    // fixes atomicity at the handler level: neither the platform-sync side
+    // effect below nor the local move in applyLocalBlueprintTransition is
+    // ever attempted while any blocker remains, so a failed finalize call
+    // can never partially move — or platform-sync without locally moving —
+    // the blueprint.
+    const blockers = [];
+    if (openTasks.length > 0) {
+        blockers.push(`Blueprint "${slug}" has open tasks: ${openTasks.map((t) => `${t.task_id} (${t.status})`).join(", ")}`);
     }
-    catch (error) {
-        return err("wp_blueprint_finalize refused", toStr(error));
+    blockers.push(...collectBlueprintCompletionBlockers(found.path, slug));
+    if (blockers.length > 0) {
+        return err("wp_blueprint_finalize refused", blockers.join("; "));
     }
     // Platform-first path: push event + pull fresh replica before local move.
     // Iron rule: resolveSyncAdapter() returns null when WP_BLUEPRINT_PLATFORM_DISABLED=1.

package/dist/esm/mcp/blueprint/registration.js

@@ -255,7 +255,7 @@ export async function registerBlueprintTools(registrar, cwd, projectResolver = c
             "next_action",
         ],
     }, (r) => handleBlueprintCreate(projectResolver, cwd, r), { title: "Blueprint Create", destructiveHint: false, openWorldHint: false });
-    registrar.registerTool("wp_blueprint_task_verify", "Mark a task done with an Evidence Contract. Requires at least one pass evidence item. Accepts optional request_id for idempotent retries, optional head_at_ingest from wp_blueprint_get/wp_blueprint_context to reject stale writes, and re-ingests DB on success. Returns { status, idempotent, next_action? }.", {
+    registrar.registerTool("wp_blueprint_task_verify", "Mark a task done with an Evidence Contract. Requires at least one pass evidence item. Accepts optional request_id for idempotent retries, optional head_at_ingest from wp_blueprint_get/wp_blueprint_context to reject stale writes, and re-ingests DB on success. Returns { status, idempotent, next_action? }. Each evidence item's required fields depend on its `kind`: 'test' requires `command` + `exit_code` (must be 0 when result='pass'); 'integration' additionally requires a non-empty `target_files`; 'audit' requires `audit_kind` + `passed:true` when result='pass'; 'manual' requires `actor`, `description`, the literal `allow_manual:true` (an explicit anti-shortcut opt-in), and a non-empty `log_excerpt` (<=4096 bytes) — it does NOT accept a `note` field.", {
         type: "object",
         properties: {
             project_id: { type: "string" },
@@ -271,7 +271,36 @@ export async function registerBlueprintTools(registrar, cwd, projectResolver = c
                     properties: {
                         kind: { type: "string", enum: ["test", "integration", "audit", "manual"] },
                         result: { type: "string", enum: ["pass", "fail"] },
-                        ts: { type: "string" },
+                        ts: { type: "string", description: "ISO 8601 date-time string" },
+                        agent: { type: "string" },
+                        command: {
+                            type: "string",
+                            description: "Required for kind='test'/'integration'",
+                        },
+                        exit_code: {
+                            type: "number",
+                            description: "Required for kind='test'/'integration'; must be 0 when result='pass'",
+                        },
+                        target_files: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Required non-empty array for kind='integration'",
+                        },
+                        audit_kind: { type: "string", description: "Required for kind='audit'" },
+                        passed: {
+                            type: "boolean",
+                            description: "Required for kind='audit'; must be true when result='pass'",
+                        },
+                        actor: { type: "string", description: "Required for kind='manual'" },
+                        description: { type: "string", description: "Required for kind='manual'" },
+                        allow_manual: {
+                            type: "boolean",
+                            description: "Required for kind='manual'; must be the literal boolean true (anti-shortcut opt-in)",
+                        },
+                        log_excerpt: {
+                            type: "string",
+                            description: "Required for kind='manual'; <=4096 bytes",
+                        },
                     },
                     required: ["kind", "result", "ts"],
                 },

package/dist/esm/review/authority.js

@@ -9,6 +9,7 @@ import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { evaluateReviewEvents, parseReviewEventLog } from "./events.js";
+import { isPolicyApprovalVerdict } from "./verdict.js";
 import { createDeliverySubjectAtRef, createLegacyPlanSubjectAtRef, createPlanSubjectAtRef, createPreTagsStripPlanSubjectAtRef, resolveReviewCommit, } from "./subject.js";
 const GIT_TIMEOUT_MS = 5_000;
 const GIT_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
@@ -114,6 +115,54 @@ function markCompromisedArtifactEvents(cwd, entries, blueprintDirectory, events)
     }
     return { compromisedIds, issues };
 }
+/** Bounded `git branch -a --contains <commit>` probe, tolerant of a pruned/unknown object. */
+function branchesContainingCommit(cwd, commit) {
+    try {
+        const output = gitBuffer(cwd, ["branch", "-a", "--contains", commit]).toString("utf8");
+        return output
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    catch {
+        return null;
+    }
+}
+// Diagnostic-only: names historical ledger approvals whose `reviewedCommit` is
+// no longer reachable from any branch (typically because a rebase rewrote the
+// history that commit lived on). Such an approval no longer matches the
+// current subjectDigest, so it already contributes zero approvals under the
+// existing policy in ./events.ts -- this only makes the reason visible instead
+// of the operator seeing a bare "approvals does not satisfy the promotion
+// reviewer mix" and mistaking a dead commit ref for a genuinely missing
+// review. Never mutates `approvals`/`matching`; policy is unchanged.
+function markOrphanedApprovalEvents(cwd, events, current) {
+    const issues = [];
+    const seen = new Set();
+    for (const event of events) {
+        if (event.purpose !== current.purpose ||
+            event.blueprintSlug !== current.blueprintSlug ||
+            event.subjectScheme !== current.subjectScheme ||
+            event.subjectDigest === current.subjectDigest ||
+            event.status !== "complete" ||
+            !isPolicyApprovalVerdict(event.verdict)) {
+            continue;
+        }
+        const key = `${event.reviewer}:${event.reviewedCommit}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const branches = branchesContainingCommit(cwd, event.reviewedCommit);
+        if (branches === null || branches.length === 0) {
+            issues.push(`Historical approval from ${event.reviewer} (event ${event.id}) reviewed commit ` +
+                `${event.reviewedCommit}, which is unreachable from any branch (git branch -a ` +
+                `--contains ${event.reviewedCommit} found nothing) -- likely orphaned by a rebase. ` +
+                "This approval does not count toward the current subject; rebase this worktree onto " +
+                "the latest base and re-run the gate.");
+        }
+    }
+    return issues;
+}
 export function readReviewAuthorityAtRef(cwd, ref, stableSlug, purpose) {
     const commit = resolveReviewCommit(cwd, ref);
     const entries = parseRefTree(cwd, commit);
@@ -131,6 +180,12 @@ export function readReviewAuthorityAtRef(cwd, ref, stableSlug, purpose) {
     const subject = purpose === "plan"
         ? createPlanSubjectAtRef(cwd, commit, stableSlug, overview.path)
         : createDeliverySubjectAtRef(cwd, commit, stableSlug, overview.path);
+    const orphanIssues = markOrphanedApprovalEvents(cwd, events, {
+        purpose,
+        blueprintSlug: stableSlug,
+        subjectScheme: subject.scheme,
+        subjectDigest: subject.digest,
+    });
     let evaluation = evaluateReviewEvents(events, {
         purpose,
         blueprintSlug: stableSlug,
@@ -166,7 +221,7 @@ export function readReviewAuthorityAtRef(cwd, ref, stableSlug, purpose) {
         subject,
         events,
         ...evaluation,
-        issues,
+        issues: [...issues, ...orphanIssues],
     };
 }
 export function readWorkingReviewEvents(blueprintPath, stableSlug) {

package/dist/esm/review/delivery-verifier.d.ts

@@ -21,6 +21,10 @@ export interface ReviewGateVerification {
     readonly logPath?: string;
     readonly sandbox?: ReviewSandboxMode;
     readonly sandboxReason?: string;
+    readonly violations?: readonly {
+        readonly section: string;
+        readonly message: string;
+    }[];
 }
 /** Runs one gate command in the review checkout and returns its raw result. */
 export type RunSandboxedGate = (args: {

package/dist/esm/review/delivery-verifier.js

@@ -18,7 +18,15 @@ export async function verifyDeliveryPromotionGates(input) {
             parsed.violations[0]?.message === "missing Trust Dossier section") {
             return undefined;
         }
-        return { status: "failed", commands: [], failureCode: "malformed-trust-dossier" };
+        return {
+            status: "failed",
+            commands: [],
+            failureCode: "malformed-trust-dossier",
+            violations: parsed.violations.map((violation) => ({
+                section: violation.section,
+                message: violation.message,
+            })),
+        };
     }
     const gates = parsed.dossier?.gates ?? [];
     if (gates.length === 0)

package/dist/esm/symlinker/consumers.d.ts

@@ -17,7 +17,7 @@
  * the canonical `.agent/{rules,skills}` SSOT always project.
  *
  * The `UNIFIED_CONSUMERS` registry below describes per-IDE projection of the
- * unified rule/skill content kinds (catalog ∪ consumer). Strategies:
+ * unified rule/skill/agent content kinds (catalog ∪ consumer). Strategies:
  *   - 'symlink':   create a relative symlink to the source (file or dir)
  *   - 'copy':      copy file or recursively copy dir tree
  *   - 'transform': run a transform function over the body and write the
@@ -78,6 +78,23 @@ export interface UnifiedConsumerConfig {
      * always project.
      */
     readonly host?: AgentHostName;
+    /**
+     * Who owns the target directory, and therefore what agent-kit may destroy in
+     * it. Defaults to `"exclusive"`, preserving the historical sweep behavior.
+     *
+     * - `"exclusive"` — agent-kit owns the directory. It is generated and
+     *   gitignored, has no hand-authoring workflow, and unexpected entries
+     *   matching the managed shape are stale projections, safe to remove.
+     * - `"shared"` — a host-native authoring surface co-owned with the user
+     *   (`.claude/agents` is Claude Code's own subagent authoring location).
+     *   agent-kit may destroy only paths it can prove it created; anything else
+     *   is preserved, because the surface is gitignored and loss is permanent.
+     *
+     * Declared rather than inferred on purpose: the stance used to be derived
+     * from `acceptsKind === "agent"` at each use site, which meant one code path
+     * had the guard and another silently did not.
+     */
+    readonly ownership?: "exclusive" | "shared";
     /**
      * Legacy flag retained for shape compatibility. Plugin hosts no longer
      * reactivate project-local skill projections under skip envs.
@@ -116,6 +133,8 @@ export declare function unifiedRuleFilename(consumer: UnifiedConsumerConfig, slu
  * `selectUnifiedConsumers(hosts)`:
  *   - `.agent/{rules,skills}/` (working dir, SSOT): symlink, always
  *   - `.claude/rules/`: symlink, always (rules are not plugin-delivered)
+ *   - `.claude/agents/`: symlink, always (canonical subagents; Claude has no
+ *     native subagent delivery channel, so this projection is not plugin-owned)
  *
  * Project-local legacy skill roots are intentionally omitted. Codex has no
  * `.codex/agents/` consumer.

package/dist/esm/symlinker/consumers.js

@@ -17,7 +17,7 @@
  * the canonical `.agent/{rules,skills}` SSOT always project.
  *
  * The `UNIFIED_CONSUMERS` registry below describes per-IDE projection of the
- * unified rule/skill content kinds (catalog ∪ consumer). Strategies:
+ * unified rule/skill/agent content kinds (catalog ∪ consumer). Strategies:
  *   - 'symlink':   create a relative symlink to the source (file or dir)
  *   - 'copy':      copy file or recursively copy dir tree
  *   - 'transform': run a transform function over the body and write the
@@ -59,6 +59,8 @@ export function unifiedRuleFilename(consumer, slug) {
  * `selectUnifiedConsumers(hosts)`:
  *   - `.agent/{rules,skills}/` (working dir, SSOT): symlink, always
  *   - `.claude/rules/`: symlink, always (rules are not plugin-delivered)
+ *   - `.claude/agents/`: symlink, always (canonical subagents; Claude has no
+ *     native subagent delivery channel, so this projection is not plugin-owned)
  *
  * Project-local legacy skill roots are intentionally omitted. Codex has no
  * `.codex/agents/` consumer.
@@ -69,6 +71,18 @@ export const DEFAULT_UNIFIED_CONSUMERS = [
     { id: "agent-skills", dir: ".agent/skills", acceptsKind: "skill", strategy: "symlink" },
     // Claude: rules are scaffolded to .claude/rules; skills come from native channels.
     { id: "claude-rules", dir: ".claude/rules", acceptsKind: "rule", strategy: "symlink" },
+    // Claude: canonical subagents are scaffolded to .claude/agents. Host-agnostic
+    // (unconditional) because subagents were previously scaffolded unconditionally
+    // by the now-retired standalone scaffoldSubagents scaffolder.
+    {
+        id: "claude-agents",
+        dir: ".claude/agents",
+        acceptsKind: "agent",
+        strategy: "symlink",
+        // Claude Code's own subagent authoring location: the user may hand-author
+        // here, and agent-kit gitignores it, so a wrong deletion is unrecoverable.
+        ownership: "shared",
+    },
 ];
 /**
  * Projection surfaces retired by a newer agent-kit release.

package/dist/esm/symlinker/ownership.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Who may destroy a path under a consumer directory.
+ *
+ * This is the single owner of that question. It exists because the answer was
+ * previously implemented twice — conservatively in `pruneStale`, not at all in
+ * `applyTarget` — and the two drifted, which is how a consumer-authored file
+ * whose name collided with a catalog slug came to be deleted silently.
+ *
+ * The predicate is deliberately narrow: agent-kit may destroy a path only when
+ * it can PROVE it created that path, i.e. the path is a symlink resolving into
+ * a directory agent-kit projects from. A real file, a real directory, or a
+ * symlink pointing anywhere else is somebody else's and is never destroyed on a
+ * `shared` surface.
+ */
+export interface ManagedSourceDirsInput {
+    /** Catalog root passed to `runUnifiedSync` (may itself be a symlink alias). */
+    readonly catalogDir: string;
+    /** Consumer repo root, already realpath-resolved by the caller. */
+    readonly consumerRoot: string;
+}
+/**
+ * Directories agent-kit projects agent records from.
+ *
+ * Derived from CONFIGURATION, never from the planned record set, so the result
+ * is non-empty even when the catalog agents directory is empty or entirely
+ * absent. That matters: with a plans-derived set, a broken or partial install
+ * produces zero plans, an empty managed set, and a sweep that can no longer
+ * tell agent-kit's own relics from the operator's files.
+ *
+ * The catalog child is derived from `realpathSync(catalogDir)` rather than by
+ * realpathing the child itself. `loadContent` throws when `catalogDir` is
+ * missing, so the parent always resolves — whereas the child may not exist yet
+ * (or any more), and a non-existent child silently contributes only its
+ * unresolved alias form, which then fails to match a symlink recorded against
+ * the real path.
+ */
+export declare function resolveManagedSourceDirs(input: ManagedSourceDirsInput): ReadonlySet<string>;
+/**
+ * True when `targetPath` is a symlink agent-kit projected — the only shape it
+ * is allowed to destroy on a `shared` surface.
+ *
+ * The resolved target need not still exist: a dangling link left behind by a
+ * removed catalog record is agent-kit's own relic and must stay prunable.
+ * Containment is delegated to `isPathContained`, which canonicalizes both sides
+ * and rejects `..` escapes, so a sibling directory such as `<managed>-evil`
+ * cannot masquerade as managed.
+ */
+export declare function isAgentKitOwned(targetPath: string, managedSourceDirs: ReadonlySet<string>): boolean;

package/dist/esm/symlinker/ownership.js

@@ -0,0 +1,83 @@
+/**
+ * Who may destroy a path under a consumer directory.
+ *
+ * This is the single owner of that question. It exists because the answer was
+ * previously implemented twice — conservatively in `pruneStale`, not at all in
+ * `applyTarget` — and the two drifted, which is how a consumer-authored file
+ * whose name collided with a catalog slug came to be deleted silently.
+ *
+ * The predicate is deliberately narrow: agent-kit may destroy a path only when
+ * it can PROVE it created that path, i.e. the path is a symlink resolving into
+ * a directory agent-kit projects from. A real file, a real directory, or a
+ * symlink pointing anywhere else is somebody else's and is never destroyed on a
+ * `shared` surface.
+ */
+import { existsSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { isPathContained } from "#worktrees/identity.js";
+/**
+ * Directories agent-kit projects agent records from.
+ *
+ * Derived from CONFIGURATION, never from the planned record set, so the result
+ * is non-empty even when the catalog agents directory is empty or entirely
+ * absent. That matters: with a plans-derived set, a broken or partial install
+ * produces zero plans, an empty managed set, and a sweep that can no longer
+ * tell agent-kit's own relics from the operator's files.
+ *
+ * The catalog child is derived from `realpathSync(catalogDir)` rather than by
+ * realpathing the child itself. `loadContent` throws when `catalogDir` is
+ * missing, so the parent always resolves — whereas the child may not exist yet
+ * (or any more), and a non-existent child silently contributes only its
+ * unresolved alias form, which then fails to match a symlink recorded against
+ * the real path.
+ */
+export function resolveManagedSourceDirs(input) {
+    const dirs = new Set();
+    const catalogRoots = new Set([resolve(input.catalogDir)]);
+    if (existsSync(input.catalogDir))
+        catalogRoots.add(realpathSync(input.catalogDir));
+    for (const catalogRoot of catalogRoots)
+        dirs.add(join(catalogRoot, "agents"));
+    // Consumer-side override dir. It is frequently absent (no scaffolder creates
+    // it), so it gets the same parent-anchored treatment.
+    const consumerRoots = new Set([resolve(input.consumerRoot)]);
+    if (existsSync(input.consumerRoot))
+        consumerRoots.add(realpathSync(input.consumerRoot));
+    for (const consumerRootForm of consumerRoots)
+        dirs.add(join(consumerRootForm, "agent-agents"));
+    return dirs;
+}
+/**
+ * True when `targetPath` is a symlink agent-kit projected — the only shape it
+ * is allowed to destroy on a `shared` surface.
+ *
+ * The resolved target need not still exist: a dangling link left behind by a
+ * removed catalog record is agent-kit's own relic and must stay prunable.
+ * Containment is delegated to `isPathContained`, which canonicalizes both sides
+ * and rejects `..` escapes, so a sibling directory such as `<managed>-evil`
+ * cannot masquerade as managed.
+ */
+export function isAgentKitOwned(targetPath, managedSourceDirs) {
+    let stat;
+    try {
+        stat = lstatSync(targetPath);
+    }
+    catch {
+        return false;
+    }
+    if (!stat.isSymbolicLink())
+        return false;
+    let resolved;
+    try {
+        resolved = resolve(dirname(targetPath), readlinkSync(targetPath));
+    }
+    catch {
+        return false;
+    }
+    const linkParent = dirname(resolved);
+    for (const managedDir of managedSourceDirs) {
+        if (isPathContained(managedDir, linkParent))
+            return true;
+    }
+    return false;
+}

package/dist/esm/symlinker/unified-sync.d.ts

@@ -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.
  */
@@ -68,6 +84,22 @@ export interface UnifiedSyncResult {
     readonly fixCount: number;
     /** Mismatches surfaced in check mode. Empty in non-check mode. */
     readonly mismatches: readonly UnifiedSyncMismatch[];
+    /**
+     * Paths on a `shared` surface that agent-kit refused to replace because it
+     * could not prove it created them.
+     *
+     * Deliberately NOT mismatches: a mismatch means drift the tool should fix,
+     * and `wp sync --check` exits non-zero on drift. A user who legitimately
+     * customized a subagent would then red every CI run forever, which is the
+     * pressure that makes people delete their own file. These are warnings.
+     */
+    readonly preserved: readonly UnifiedSyncPreserved[];
+}
+export interface UnifiedSyncPreserved {
+    readonly consumerId: string;
+    readonly targetPath: string;
+    /** Slug the catalog wanted to project there. */
+    readonly slug: string;
 }
 export declare function isSymlinkPointingTo(linkPath: string, expectedAbs: string): boolean;
 /**