@unbrained/pm-cli 2026.8.27 → 2026.8.29

package/dist/sdk/completion.js

@@ -4,7 +4,7 @@
  * Implements the pm completion command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c8446891-4e65-54c3-9826-eb40f4922f3b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4bf2b42b-91f3-5850-b1f1-d8a01525860c")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
@@ -601,13 +601,13 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen(`${PACKAGE_LIFECYCLE_ACTIONS} ${PACKAGE_LIFECYCLE_FLAGS} ${UPGRADE_FLAGS}`)})`,
         "      ;;",
         "    comments)",
-        `      COMPREPLY=(${compgen("--add --body --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --body --stdin --file --edit --delete --limit --full-history --if-absent --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    notes)",
-        `      COMPREPLY=(${compgen("--add --add-json --stdin --file --edit --delete --limit --since --event-type --include-meta --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --add-json --stdin --file --edit --delete --limit --since --event-type --include-meta --full-history --if-absent --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    learnings)",
-        `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --full-history --if-absent --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    files)",
         `      COMPREPLY=(${compgen("discover lookup --add --add-glob --remove --migrate --list --apply --note --append-stable --validate-paths --scope --limit --offset --no-truncate --strict-read --explain --lines --decision-depth --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
@@ -1370,6 +1370,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--delete[Delete the comment at 1-based index]:index' \\
             '--limit[Return only latest n entries]:number' \\
             '--full-history[Return complete post-mutation history]' \\
+            '--if-absent[Append only when the resolved author and text are absent]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1390,6 +1391,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--event-type[Return structured events with this top-level type]:event_type' \\
             '--include-meta[Include result counts and truncation metadata]' \\
             '--full-history[Return complete post-mutation history]' \\
+            '--if-absent[Append only when the resolved author and text are absent]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1406,6 +1408,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--delete[Delete the entry at a 1-based index]:index' \\
             '--limit[Return only latest n entries]:number' \\
             '--full-history[Return complete post-mutation history]' \\
+            '--if-absent[Append only when the resolved author and text are absent]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -2452,6 +2455,7 @@ complete -c pm -n '__fish_seen_subcommand_from comments' -l stdin -d 'Read comme
 complete -c pm -n '__fish_seen_subcommand_from comments' -l file -d 'Read comment text from file (supports multiline markdown)' -r
 complete -c pm -n '__fish_seen_subcommand_from comments' -l edit -d 'Replace the comment at 1-based index (text from positional/--add/--stdin/--file)' -r
 complete -c pm -n '__fish_seen_subcommand_from comments' -l delete -d 'Delete the comment at 1-based index' -r
+complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l if-absent -d 'Append only when the resolved author and text are absent'
 complete -c pm -n '__fish_seen_subcommand_from notes' -l stdin -d 'Read entry text from stdin'
 complete -c pm -n '__fish_seen_subcommand_from notes' -l file -d 'Read entry text from file' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l edit -d 'Replace the entry at a 1-based index' -r
@@ -2794,4 +2798,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=c8446891-4e65-54c3-9826-eb40f4922f3b
+//# debugId=4bf2b42b-91f3-5850-b1f1-d8a01525860c

package/dist/sdk/contracts.d.ts

@@ -13,6 +13,7 @@ export * from "./flag-invocation-contracts.js";
 export * from "./cli-contracts/flag-lexicon-contracts.js";
 export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
+export * from "./agent/task-transcript-contracts.js";
 export * from "./read-output-contracts.js";
 export * from "./agent/refusal-closure.js";
 export * from "./agent/closed-domain-contracts.js";

package/dist/sdk/contracts.js

@@ -4,7 +4,7 @@
  * Exposes command and action contract data without loading SDK runtime code.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8bdc03e5-c5cd-5842-b438-cf7bc79863f0")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b47a3cc6-caba-5de8-8813-a4e6112dbe61")}catch(e){}}();
 export * from "./cli-contracts.js";
 export * from "./cli-contracts/grammar-contracts.js";
 export * from "./cli-contracts/command-exit-contracts.js";
@@ -15,9 +15,10 @@ export * from "./flag-invocation-contracts.js";
 export * from "./cli-contracts/flag-lexicon-contracts.js";
 export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
+export * from "./agent/task-transcript-contracts.js";
 export * from "./read-output-contracts.js";
 export * from "./agent/refusal-closure.js";
 export * from "./agent/closed-domain-contracts.js";
 export * from "./agent/tracker-preflight-contracts.js";
 //# sourceMappingURL=contracts.js.map
-//# debugId=8bdc03e5-c5cd-5842-b438-cf7bc79863f0
+//# debugId=b47a3cc6-caba-5de8-8813-a4e6112dbe61

package/dist/sdk/dependency-provenance.d.ts

@@ -1,9 +1,58 @@
+export { isExternalDependencyReference, isExternalDependencySourceKind, } from "../core/item/dependency-reference.js";
 /** Provenance value declaring that a dependency id belongs to another workspace. */
 export declare const EXTERNAL_DEPENDENCY_SOURCE_KIND = "global";
 /** Human-facing alias accepted wherever external dependency provenance is parsed. */
 export declare const EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS = "external";
-/** Return whether a dependency provenance value identifies an external workspace target. */
-export declare function isExternalDependencySourceKind(sourceKind: string | undefined): boolean;
+/** Stable external lifecycle values understood without coupling core to a provider. */
+export declare const EXTERNAL_DEPENDENCY_RESOLUTION_STATUSES: readonly ["open", "closed", "unknown"];
+/** External lifecycle value returned by a registered dependency resolver. */
+export type ExternalDependencyResolutionStatus = (typeof EXTERNAL_DEPENDENCY_RESOLUTION_STATUSES)[number];
+/** Provider-owned external dependency data before the SDK applies output bounds. */
+export interface ExternalDependencyResolverResult {
+    /** Provider lifecycle state normalized to the universal external status vocabulary. */
+    status: ExternalDependencyResolutionStatus;
+    /** Optional bounded human context for the remote dependency. */
+    title?: string;
+    /** Optional canonical provider URL or locator used as evidence. */
+    source?: string;
+    /** Optional provider observation timestamp; invalid timestamps are replaced by SDK time. */
+    checkedAt?: string;
+}
+/** Package-provided resolver contract for one or more external dependency locator families. */
+export interface ExternalDependencyResolver {
+    /** Stable resolver identity surfaced in agent-facing evidence. */
+    name: string;
+    /** Return whether this resolver owns the supplied external locator. */
+    supports(reference: string): boolean;
+    /** Resolve the locator without exposing provider credentials or unbounded response data. */
+    resolve(reference: string): Promise<ExternalDependencyResolverResult | null>;
+}
+/** Bounded provider-neutral evidence returned by the public resolver registry. */
+export interface ExternalDependencyResolution {
+    /** Original normalized dependency locator. */
+    id: string;
+    /** Provider lifecycle state. */
+    status: ExternalDependencyResolutionStatus;
+    /** Whether trusted provider evidence proves the blocker terminal. */
+    resolved: boolean;
+    /** Bounded remote title, or null when the provider did not supply one. */
+    title: string | null;
+    /** Bounded evidence locator. */
+    source: string;
+    /** Observation timestamp supplied by the provider or SDK clock. */
+    checked_at: string;
+    /** Registered resolver identity that produced this evidence. */
+    resolver: string;
+}
+/** Deterministic clock override for external resolver acceptance and tests. */
+export interface ExternalDependencyResolutionOptions {
+    /** Return the timestamp used when provider evidence omits or corrupts checkedAt. */
+    now?: () => string;
+}
+/** Register a package-owned external dependency resolver and return its idempotent disposer. */
+export declare function registerExternalDependencyResolver(resolver: ExternalDependencyResolver): () => void;
+/** Resolve one external locator through registered package providers with bounded provider-neutral evidence. */
+export declare function resolveExternalDependencyReference(reference: string, options?: ExternalDependencyResolutionOptions): Promise<ExternalDependencyResolution | null>;
 /** Canonicalize external provenance while preserving other named source kinds. */
 export declare function normalizeDependencySourceKind(sourceKind: string | undefined): string | undefined;
 /**

package/dist/sdk/dependency-provenance.js

@@ -5,17 +5,101 @@
  * items outside the current workspace.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1b2f1ac3-82b3-58a2-9f40-2dd95ab1b2bc")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f3f3beb2-1d60-52fe-88ce-1ab3cb9dba0d")}catch(e){}}();
 import { normalizeItemId } from "../core/item/id.js";
+import { isExternalDependencyReference, isExternalDependencySourceKind, } from "../core/item/dependency-reference.js";
+export { isExternalDependencyReference, isExternalDependencySourceKind, } from "../core/item/dependency-reference.js";
 /** Provenance value declaring that a dependency id belongs to another workspace. */
 export const EXTERNAL_DEPENDENCY_SOURCE_KIND = "global";
 /** Human-facing alias accepted wherever external dependency provenance is parsed. */
 export const EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS = "external";
-/** Return whether a dependency provenance value identifies an external workspace target. */
-export function isExternalDependencySourceKind(sourceKind) {
-    const normalized = sourceKind?.trim().toLowerCase();
-    return (normalized === EXTERNAL_DEPENDENCY_SOURCE_KIND ||
-        normalized === EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS);
+/** Stable external lifecycle values understood without coupling core to a provider. */
+export const EXTERNAL_DEPENDENCY_RESOLUTION_STATUSES = [
+    "open",
+    "closed",
+    "unknown",
+];
+const externalDependencyResolvers = new Map();
+const MAX_EXTERNAL_TITLE_LENGTH = 240;
+const MAX_EXTERNAL_SOURCE_LENGTH = 2_048;
+/** Normalize and cap provider strings before they reach agent-facing output. */
+function boundedExternalText(value, fallback, maximumLength) {
+    return (value?.trim() || fallback).slice(0, maximumLength);
+}
+/** Reject provider payloads that violate the runtime resolver-result contract. */
+function isExternalDependencyResolverResult(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.status === "string" &&
+        (candidate.title == null || typeof candidate.title === "string") &&
+        (candidate.source == null || typeof candidate.source === "string") &&
+        (candidate.checkedAt == null || typeof candidate.checkedAt === "string"));
+}
+/** Register a package-owned external dependency resolver and return its idempotent disposer. */
+export function registerExternalDependencyResolver(resolver) {
+    const name = resolver.name.trim();
+    if (name.length === 0) {
+        throw new Error("External dependency resolver name must not be empty");
+    }
+    if (externalDependencyResolvers.has(name)) {
+        throw new Error(`External dependency resolver already registered: ${name}`);
+    }
+    const registeredResolver = {
+        name,
+        supports: (reference) => resolver.supports(reference),
+        resolve: (reference) => resolver.resolve(reference),
+    };
+    externalDependencyResolvers.set(name, registeredResolver);
+    return () => {
+        if (externalDependencyResolvers.get(name) === registeredResolver) {
+            externalDependencyResolvers.delete(name);
+        }
+    };
+}
+/** Resolve one external locator through registered package providers with bounded provider-neutral evidence. */
+export async function resolveExternalDependencyReference(reference, options = {}) {
+    const id = reference.trim();
+    if (!isExternalDependencyReference(id)) {
+        return null;
+    }
+    const resolvers = [...externalDependencyResolvers.values()].filter((resolver) => {
+        try {
+            return resolver.supports(id);
+        }
+        catch {
+            return false;
+        }
+    });
+    const outcomes = await Promise.allSettled(resolvers.map((resolver) => Promise.resolve().then(() => resolver.resolve(id))));
+    for (const [index, outcome] of outcomes.entries()) {
+        if (outcome.status !== "fulfilled" ||
+            !isExternalDependencyResolverResult(outcome.value)) {
+            continue;
+        }
+        const resolver = resolvers[index];
+        const candidate = outcome.value;
+        const status = EXTERNAL_DEPENDENCY_RESOLUTION_STATUSES.includes(candidate.status)
+            ? candidate.status
+            : "unknown";
+        const title = boundedExternalText(candidate.title, "", MAX_EXTERNAL_TITLE_LENGTH);
+        const source = boundedExternalText(candidate.source, id, MAX_EXTERNAL_SOURCE_LENGTH);
+        const observedAtMs = Date.parse(candidate.checkedAt?.trim() ?? "");
+        const checkedAt = Number.isFinite(observedAtMs)
+            ? new Date(observedAtMs).toISOString()
+            : (options.now?.() ?? new Date().toISOString());
+        return {
+            id,
+            status,
+            resolved: status === "closed",
+            title: title.length > 0 ? title : null,
+            source,
+            checked_at: checkedAt,
+            resolver: resolver.name,
+        };
+    }
+    return null;
 }
 /** Canonicalize external provenance while preserving other named source kinds. */
 export function normalizeDependencySourceKind(sourceKind) {
@@ -39,4 +123,4 @@ export function normalizeDependencySeedId(id, prefix, sourceKind) {
         : normalizeItemId(trimmed, prefix);
 }
 //# sourceMappingURL=dependency-provenance.js.map
-//# debugId=1b2f1ac3-82b3-58a2-9f40-2dd95ab1b2bc
+//# debugId=f3f3beb2-1d60-52fe-88ce-1ab3cb9dba0d

package/dist/sdk/extension/install-sources.d.ts

@@ -107,7 +107,7 @@ export declare function wrapNpmPackResolutionError(spec: string, error: unknown)
 declare function resolveNpmPackSpec(spec: string): Promise<string>;
 /** Implements normalize npm local file alias spec for the public runtime surface of this module. */
 export declare function normalizeNpmLocalFileAliasSpec(spec: string, cwd?: string): string;
-declare function parsePackedNpmPackage(stdout: string, packDirectory: string): {
+declare function parsePackedNpmPackage(stdout: string, packDirectory: string, expectedPackage?: string): {
     tarball: string;
     package?: string;
     version?: string;
@@ -118,6 +118,13 @@ declare function resolveNpmSourceDirectory(source: NpmInstallSource): Promise<{
     version?: string;
     cleanup: () => Promise<void>;
 }>;
+/**
+ * Resolve an npm source with an injectable, argv-safe package-manager runner.
+ *
+ * Local package directories remain in place, while local and registry archives
+ * share the same bounded validation, dependency installation, and cleanup
+ * contract. Registry artifacts must also exist inside the requested pack root.
+ */
 declare function resolveNpmSourceDirectoryWithRunner(source: NpmInstallSource, npmRunner: typeof runNpmCommand): Promise<{
     directory: string;
     package?: string;

package/dist/sdk/extension/install-sources.js

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Install Sources.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="89b84412-aa15-5868-95b3-c8d898b1f480")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="05f56edb-c08d-570c-b8b5-641fc694331e")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -237,6 +237,14 @@ function npmPackageNameFromSpec(spec) {
     const unscoped = withoutAlias.match(/^([^/@\s]+)/);
     return unscoped?.[1] ?? withoutAlias;
 }
+/** Return whether an npm spec is a complete local-file alias, including unchanged UNC targets. */
+function isNpmLocalFileAliasSpec(spec) {
+    const marker = "@file:";
+    const markerIndex = spec.lastIndexOf(marker);
+    return (markerIndex > 0 &&
+        spec.slice(0, markerIndex).trim().length > 0 &&
+        spec.slice(markerIndex + marker.length).trim().length > 0);
+}
 /** Implements check whether npm not found error for the public runtime surface of this module. */
 export function isNpmNotFoundError(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -358,14 +366,11 @@ async function resolveNpmPackSpec(spec) {
 export function normalizeNpmLocalFileAliasSpec(spec, cwd = process.cwd()) {
     const marker = "@file:";
     const markerIndex = spec.lastIndexOf(marker);
-    if (markerIndex <= 0) {
+    if (!isNpmLocalFileAliasSpec(spec)) {
         return spec;
     }
     const packageName = spec.slice(0, markerIndex);
     const target = spec.slice(markerIndex + marker.length);
-    if (packageName.trim().length === 0 || target.trim().length === 0) {
-        return spec;
-    }
     // `file://host/share` (exactly two leading slashes) is a UNC / network spec,
     // not a local path — leave it for npm to resolve.
     if (target.startsWith("//") && !target.startsWith("///")) {
@@ -397,38 +402,117 @@ export function normalizeNpmLocalFileAliasSpec(spec, cwd = process.cwd()) {
         : decodedPath;
     return `${packageName}@${nativePath}`;
 }
-function parsePackedNpmPackage(stdout, packDirectory) {
+/**
+ * Parse npm pack output and bind the reported artifact to its isolated target.
+ *
+ * Supports current JSON metadata and the legacy filename-only form while
+ * refusing absolute or traversing results before the filesystem is consulted.
+ */
+function resolvePackedTarball(packDirectory, filename) {
+    const tarball = path.resolve(packDirectory, filename);
+    const relativeTarball = path.relative(packDirectory, tarball);
+    if (relativeTarball.length === 0 ||
+        relativeTarball === ".." ||
+        relativeTarball.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeTarball)) {
+        throw new PmCliError("npm pack reported a package archive outside its isolated destination.", EXIT_CODE.GENERIC_FAILURE, {
+            code: "npm_package_archive_unsafe",
+            required: "Retry with a trusted npm client that writes its archive inside the requested pack destination.",
+            why: "pm will not read a package-manager artifact outside the isolated directory created for this install.",
+        });
+    }
+    return tarball;
+}
+function decodePackedNpmCandidate(value, key) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    if (typeof record.filename !== "string" ||
+        record.filename.trim().length === 0) {
+        return undefined;
+    }
+    return {
+        ...(key === undefined ? {} : { key }),
+        filename: record.filename,
+        ...(typeof record.name === "string" ? { name: record.name } : {}),
+        ...(typeof record.version === "string" ? { version: record.version } : {}),
+    };
+}
+function collectPackedNpmCandidates(parsed) {
+    const entries = Array.isArray(parsed)
+        ? parsed.map((value) => ({ value }))
+        : typeof parsed === "object" && parsed !== null
+            ? Object.entries(parsed).map(([key, value]) => ({ key, value }))
+            : [];
+    return entries.flatMap(({ key, value }) => {
+        const candidate = decodePackedNpmCandidate(value, key);
+        return candidate ? [candidate] : [];
+    });
+}
+function selectPackedNpmCandidate(candidates, expectedPackage) {
+    const normalizedExpected = expectedPackage?.trim().toLowerCase();
+    const matchingCandidates = normalizedExpected
+        ? candidates.filter((candidate) => {
+            const normalizedName = candidate.name?.trim().toLowerCase();
+            return normalizedName !== undefined
+                ? normalizedName === normalizedExpected
+                : candidate.key?.trim().toLowerCase() === normalizedExpected;
+        })
+        : [];
+    if (matchingCandidates.length === 1)
+        return matchingCandidates[0];
+    if (candidates.length !== 1)
+        return undefined;
+    const soleCandidate = candidates[0];
+    const soleIdentity = soleCandidate.name ?? soleCandidate.key;
+    return normalizedExpected &&
+        soleIdentity !== undefined &&
+        soleIdentity.trim().toLowerCase() !== normalizedExpected
+        ? undefined
+        : soleCandidate;
+}
+function parsePackedNpmPackage(stdout, packDirectory, expectedPackage) {
+    let parsed;
     try {
-        const parsed = JSON.parse(stdout);
-        const first = Array.isArray(parsed) ? parsed[0] : undefined;
-        if (first &&
-            typeof first.filename === "string" &&
-            first.filename.trim().length > 0) {
-            return {
-                tarball: path.resolve(packDirectory, first.filename),
-                package: typeof first.name === "string" ? first.name : undefined,
-                version: typeof first.version === "string" ? first.version : undefined,
-            };
-        }
+        parsed = JSON.parse(stdout);
     }
     catch {
-        // Fall back to the last stdout line for older npm output.
-    }
-    const lastLine = stdout
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0)
-        .at(-1);
-    if (!lastLine) {
-        throw new PmCliError("npm pack did not report a tarball filename.", EXIT_CODE.GENERIC_FAILURE);
+        const filename = stdout
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .at(-1);
+        if (!filename) {
+            throw new PmCliError("npm pack did not report a tarball filename.", EXIT_CODE.GENERIC_FAILURE);
+        }
+        return { tarball: resolvePackedTarball(packDirectory, filename) };
+    }
+    const candidates = collectPackedNpmCandidates(parsed);
+    const selected = selectPackedNpmCandidate(candidates, expectedPackage);
+    if (!selected) {
+        throw new PmCliError("npm pack --json returned an unsupported or ambiguous package receipt.", EXIT_CODE.GENERIC_FAILURE, {
+            code: "npm_pack_json_shape_unsupported",
+            required: "Use an npm client that returns an array of package receipts or an object keyed by package name, with exactly one requested package entry containing filename.",
+            why: `Well-formed JSON contained ${candidates.length} usable package receipt(s), but pm could not select ${expectedPackage ?? "one package"} deterministically.`,
+        });
     }
     return {
-        tarball: path.resolve(packDirectory, lastLine),
+        tarball: resolvePackedTarball(packDirectory, selected.filename),
+        package: selected.name ?? selected.key,
+        version: selected.version,
     };
 }
 async function resolveNpmSourceDirectory(source) {
     return resolveNpmSourceDirectoryWithRunner(source, runNpmCommand);
 }
+/**
+ * Resolve an npm source with an injectable, argv-safe package-manager runner.
+ *
+ * Local package directories remain in place, while local and registry archives
+ * share the same bounded validation, dependency installation, and cleanup
+ * contract. Registry artifacts must also exist inside the requested pack root.
+ */
 async function resolveNpmSourceDirectoryWithRunner(source, npmRunner) {
     const localPackageRoot = await resolveLocalNpmPackagePath(source.spec);
     if (localPackageRoot) {
@@ -451,9 +535,7 @@ async function resolveNpmSourceDirectoryWithRunner(source, npmRunner) {
     }
     const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "pm-npm-package-source-"));
     const packDirectory = path.join(tempRoot, "pack");
-    const extractDirectory = path.join(tempRoot, "extract");
     await fs.mkdir(packDirectory, { recursive: true });
-    await fs.mkdir(extractDirectory, { recursive: true });
     try {
         const packSpec = await resolveNpmPackSpec(source.spec);
         const packStdout = await npmRunner([
@@ -463,17 +545,28 @@ async function resolveNpmSourceDirectoryWithRunner(source, npmRunner) {
             "--pack-destination",
             packDirectory,
         ]);
-        const packed = parsePackedNpmPackage(packStdout, packDirectory);
-        await execFileAsync("tar", ["-xzf", packed.tarball, "-C", extractDirectory], { encoding: "utf8" });
-        const packageRoot = path.join(extractDirectory, "package");
-        await installNpmPackageRuntimeDependencies(packageRoot);
-        const directory = await resolvePackageExtensionDirectory(packageRoot, source.input);
+        const packed = parsePackedNpmPackage(packStdout, packDirectory, isNpmLocalFileAliasSpec(source.spec)
+            ? undefined
+            : npmPackageNameFromSpec(source.spec));
+        if (!(await pathExists(packed.tarball))) {
+            throw new PmCliError("npm pack did not create its reported package archive.", EXIT_CODE.GENERIC_FAILURE, {
+                code: "npm_package_archive_missing",
+                required: "Retry the npm package install with a healthy registry and writable temporary directory.",
+                why: "The package manager reported a tarball filename that was absent before validation, so pm cannot safely extract or install it.",
+            });
+        }
+        const extracted = await extractLocalPackageArchive(packed.tarball);
         return {
-            directory,
-            package: packed.package,
-            version: packed.version,
+            directory: extracted.directory,
+            package: packed.package ?? extracted.package,
+            version: packed.version ?? extracted.version,
             cleanup: async () => {
-                await fs.rm(tempRoot, { recursive: true, force: true });
+                try {
+                    await extracted.cleanup();
+                }
+                finally {
+                    await fs.rm(tempRoot, { recursive: true, force: true });
+                }
             },
         };
     }
@@ -962,4 +1055,4 @@ export const _testOnlyInstallSources = {
     runNpmCommand,
 };
 //# sourceMappingURL=install-sources.js.map
-//# debugId=89b84412-aa15-5868-95b3-c8d898b1f480
+//# debugId=05f56edb-c08d-570c-b8b5-641fc694331e