@timurproko/a1 0.1.8-dev.536 → 0.1.8-dev.546

package/dist/foundation/lifecycle/session-repository-context.js

@@ -0,0 +1,173 @@
+import { createHash, randomUUID } from "node:crypto";
+import { open, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { resolveProductPaths } from "./paths.js";
+const SCHEMA = "a1-session-repository-context-v1";
+const MAX_RECORD_BYTES = 16 * 1024;
+const MAX_HEADER_BYTES = 64 * 1024;
+const GIT_TIMEOUT_MS = 5_000;
+/** Persist one explicit same-repository worktree association for a stable Pi session. */
+export async function setSessionRepositoryContext(identity, worktreePath, options = {}) {
+    const header = await readSessionHeader(identity);
+    const startup = await readGitWorktreeIdentity(header.cwd, false, options.signal);
+    const selected = await readGitWorktreeIdentity(worktreePath, true, options.signal);
+    if (!samePath(startup.commonDir, selected.commonDir)) {
+        throw new Error("associated worktree belongs to a different Git repository");
+    }
+    const record = {
+        schema: SCHEMA,
+        sessionId: header.id,
+        sessionFile: header.file,
+        startupRoot: startup.root,
+        startupCommonDir: startup.commonDir,
+        worktreeRoot: selected.root,
+        worktreeCommonDir: selected.commonDir,
+        worktreeGitDir: selected.gitDir,
+        updatedAt: new Date().toISOString(),
+    };
+    const destination = recordPath(header, options);
+    const directory = dirname(destination);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        await rename(temporary, destination);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+    return { cwd: selected.root, branch: requireBranch(selected) };
+}
+/** Remove only the association belonging to the supplied stable session. */
+export async function clearSessionRepositoryContext(identity, options = {}) {
+    const header = await readSessionHeader(identity);
+    await rm(recordPath(header, options), { force: true });
+}
+/** Read and revalidate a persisted association; malformed or stale state fails closed to absence. */
+export async function readSessionRepositoryContext(identity, options = {}) {
+    let header;
+    try {
+        header = await readSessionHeader(identity);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const path = recordPath(header, options);
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size === 0 || metadata.size > MAX_RECORD_BYTES)
+            return null;
+        const bytes = await readFile(path, { signal: options.signal });
+        const value = JSON.parse(bytes.toString("utf8"));
+        if (!isRecord(value)
+            || value.schema !== SCHEMA
+            || value.sessionId !== header.id
+            || value.sessionFile !== header.file
+            || !validPath(value.startupRoot)
+            || !validPath(value.startupCommonDir)
+            || !validPath(value.worktreeRoot)
+            || !validPath(value.worktreeCommonDir)
+            || !validPath(value.worktreeGitDir)
+            || typeof value.updatedAt !== "string")
+            return null;
+        const startup = await readGitWorktreeIdentity(header.cwd, false, options.signal);
+        const selected = await readGitWorktreeIdentity(value.worktreeRoot, true, options.signal);
+        if (!samePath(startup.root, value.startupRoot)
+            || !samePath(startup.commonDir, value.startupCommonDir)
+            || !samePath(selected.root, value.worktreeRoot)
+            || !samePath(selected.commonDir, value.worktreeCommonDir)
+            || !samePath(selected.gitDir, value.worktreeGitDir)
+            || !samePath(startup.commonDir, selected.commonDir))
+            return null;
+        return { cwd: selected.root, branch: requireBranch(selected) };
+    }
+    catch {
+        return null;
+    }
+}
+async function readSessionHeader(identity) {
+    if (!validSessionId(identity.sessionId) || !validPath(identity.sessionFile))
+        throw new Error("active session identity is unavailable");
+    const file = await realpath(resolve(identity.sessionFile));
+    const handle = await open(file, "r");
+    try {
+        const buffer = Buffer.alloc(MAX_HEADER_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, 0);
+        const newline = buffer.subarray(0, bytesRead).indexOf(0x0a);
+        if (newline < 0)
+            throw new Error("session header is unavailable");
+        const value = JSON.parse(buffer.subarray(0, newline).toString("utf8"));
+        if (!isRecord(value) || value.type !== "session" || value.id !== identity.sessionId || !validPath(value.cwd)) {
+            throw new Error("active session identity does not match its session file");
+        }
+        return { id: identity.sessionId, cwd: await realpath(resolve(value.cwd)), file };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readGitWorktreeIdentity(path, requireWorktreeRoot, signal) {
+    if (!validPath(path))
+        throw new Error("associated worktree path is invalid");
+    const cwd = await realpath(resolve(path));
+    const { stdout } = await executeGit(["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir", "--git-dir"], cwd, MAX_RECORD_BYTES, signal);
+    const lines = stdout.split(/\r?\n/u).filter(Boolean);
+    if (lines.length !== 3)
+        throw new Error("associated worktree identity is invalid");
+    const [rootValue, commonValue, gitValue] = lines;
+    if (!rootValue || !commonValue || !gitValue)
+        throw new Error("associated worktree identity is incomplete");
+    const root = await realpath(rootValue);
+    if (requireWorktreeRoot && !samePath(root, cwd))
+        throw new Error("associated path must be a Git worktree root");
+    const commonDir = await realpath(commonValue);
+    const gitDir = await realpath(gitValue);
+    let branch = null;
+    if (requireWorktreeRoot) {
+        const branchResult = await executeGit(["symbolic-ref", "--quiet", "--short", "HEAD"], cwd, 4_096, signal);
+        branch = branchResult.stdout.trim();
+        if (branch.length === 0 || branch.length > 256)
+            throw new Error("associated worktree has a detached or invalid branch");
+    }
+    return { root, commonDir, gitDir, branch };
+}
+async function executeGit(arguments_, cwd, maxBuffer, signal) {
+    const { execFile } = await import("node:child_process");
+    const execute = promisify(execFile);
+    return await execute("git", [...arguments_], {
+        cwd,
+        windowsHide: true,
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer,
+        encoding: "utf8",
+        signal,
+    });
+}
+function requireBranch(identity) {
+    if (identity.branch === null)
+        throw new Error("associated worktree branch is unavailable");
+    return identity.branch;
+}
+function recordPath(header, options) {
+    const dataDir = options.dataDir ?? resolveProductPaths().dataDir;
+    const digest = createHash("sha256").update(header.id).update("\0").update(pathKey(header.file)).digest("hex");
+    return join(dataDir, PRODUCT_IDENTITY.state.sessionRepositoryDirectory, `${digest}.json`);
+}
+function samePath(left, right) {
+    return pathKey(left) === pathKey(right);
+}
+function pathKey(value) {
+    const normalized = resolve(value);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function validSessionId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u.test(value);
+}
+function validPath(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 32_768 && !value.includes("\0") && isAbsolute(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/foundation/release/index.d.ts

@@ -21,11 +21,11 @@ export type { RestartSeal, RestartValidationEvent } from "./restart-certificatio
 export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistry } from "./stable-release.js";
 export type { StableRegistryState, StableRegistryVerificationOptions, StableReleaseEvidence, StableReleaseEvidenceInput } from "./stable-release.js";
 export { PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
-export type { ProcessRequest, ProcessResult, SelfUpdateOptions, UpdateActivationPhase, UpdateChannel, UpdateFileSystem, UpdateLifecycleCoordinator, UpdateMaterializationProgress, UpdateMeasuredPhase, UpdateOutput, UpdateOwnershipAction, UpdatePackageReplacementInput, UpdatePerformanceEvidence, UpdatePhaseTimingEvent, UpdateProcessRunner, UpdateTransactionJournal, } from "./update.js";
+export type { ProcessRequest, ProcessResult, SelfUpdateOptions, UpdateActivationPhase, UpdateChannel, UpdateFileMetadata, UpdateFileSystem, UpdateLifecycleCoordinator, UpdateMaterializationProgress, UpdateMeasuredPhase, UpdateOutput, UpdateOwnershipAction, UpdatePackageReplacementInput, UpdatePerformanceEvidence, UpdatePhaseTimingEvent, UpdateProcessRunner, UpdateTransactionJournal, } from "./update.js";
 export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
 export type { UpdateActivationCallbacks, UpdateActivationEvent, UpdateActivationRequest } from "./update-activation.js";
 export { selectSupervisorLaunchReleaseId, selectUpdateLaunchRelease } from "./update-launch.js";
-export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, } from "./update-recovery.js";
+export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, npmPrefixForGlobalRoot, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
 export type { ProtectedPackageReplacementOptions, ProtectedPackageReplacementResult, UpdateRecoveryCapsule, UpdateRecoveryResult } from "./update-recovery.js";
 export { UPDATE_JOURNAL_SCHEMA, UpdateTransactionStore } from "./update-transaction.js";
 export type { UpdateRecoveryState, UpdateTransaction, UpdateTransactionPhase } from "./update-transaction.js";

package/dist/foundation/release/index.js

@@ -12,6 +12,6 @@ export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistr
 export { PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
 export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
 export { selectSupervisorLaunchReleaseId, selectUpdateLaunchRelease } from "./update-launch.js";
-export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, } from "./update-recovery.js";
+export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, npmPrefixForGlobalRoot, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
 export { UPDATE_JOURNAL_SCHEMA, UpdateTransactionStore } from "./update-transaction.js";
 export { warmMaterializedRelease } from "./warmup.js";

package/dist/foundation/release/update-recovery.d.ts

@@ -39,6 +39,8 @@ export interface UpdateRecoveryResult {
 export interface ProtectedPackageReplacementOptions {
     readonly dataDir: string;
     readonly globalRoot: string;
+    /** Root used only to locate the active npm implementation; installation remains pinned to globalRoot. */
+    readonly npmCliRoot?: string;
     readonly packageRoot: string;
     readonly transaction: UpdateTransaction;
     readonly priorRelease: {
@@ -58,7 +60,11 @@ export interface ProtectedPackageReplacementOptions {
 export interface ProtectedPackageReplacementResult extends UpdateRecoveryResult {
     readonly recovery: UpdateRecoveryState;
 }
-/** Resolve the complete public launcher set npm owns for the active platform. */
+/** Derive the only npm prefix that can own a platform's canonical global package root. */
+export declare function npmPrefixForGlobalRoot(globalRoot: string, platform?: NodeJS.Platform): string;
+/** Fixed replacement arguments pin npm to the installation that owns the invoked launcher. */
+export declare function updateNpmInstallArguments(globalRoot: string, targetVersion: string, platform?: NodeJS.Platform): readonly string[];
+/** Resolve the complete public launcher set npm owns for the selected platform and prefix. */
 export declare function updateLauncherPaths(globalRoot: string, platform?: NodeJS.Platform): readonly string[];
 /** Validate transaction-scoped recovery authority without trusting npm temporary names. */
 export declare function readUpdateRecoveryCapsule(manifestPath: string, platform?: NodeJS.Platform): Promise<UpdateRecoveryCapsule>;

package/dist/foundation/release/update-recovery.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { processIsAlive } from "./process-cleanup.js";
@@ -9,9 +9,29 @@ import { PRIVATE_LAUNCH_CONTRACT, assertCurrentLaunchContract } from "../launch-
 export const UPDATE_RECOVERY_SCHEMA = "a1-update-recovery-v1";
 const WORKER_TIMEOUT_MS = 15 * 60 * 1_000;
 const POLL_MS = 50;
-/** Resolve the complete public launcher set npm owns for the active platform. */
+/** Derive the only npm prefix that can own a platform's canonical global package root. */
+export function npmPrefixForGlobalRoot(globalRoot, platform = process.platform) {
+    const root = resolve(globalRoot);
+    if (!sameSegment(basename(root), "node_modules", platform))
+        throw new Error(`npm global root has an unsupported layout: ${globalRoot}`);
+    if (platform === "win32")
+        return dirname(root);
+    const libraryRoot = dirname(root);
+    if (!sameSegment(basename(libraryRoot), "lib", platform))
+        throw new Error(`npm global root has an unsupported layout: ${globalRoot}`);
+    return dirname(libraryRoot);
+}
+/** Fixed replacement arguments pin npm to the installation that owns the invoked launcher. */
+export function updateNpmInstallArguments(globalRoot, targetVersion, platform = process.platform) {
+    return [
+        "install", "--global", "--prefix", npmPrefixForGlobalRoot(globalRoot, platform),
+        "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_TEXT.packageName}@${targetVersion}`,
+    ];
+}
+/** Resolve the complete public launcher set npm owns for the selected platform and prefix. */
 export function updateLauncherPaths(globalRoot, platform = process.platform) {
-    const launcherRoot = platform === "win32" ? dirname(globalRoot) : resolve(globalRoot, "..", "..", "bin");
+    const prefix = npmPrefixForGlobalRoot(globalRoot, platform);
+    const launcherRoot = platform === "win32" ? prefix : resolve(prefix, "bin");
     return platform === "win32"
         ? [resolve(launcherRoot, "a1"), resolve(launcherRoot, "a1.cmd"), resolve(launcherRoot, "a1.ps1")]
         : [resolve(launcherRoot, "a1")];
@@ -33,9 +53,11 @@ export async function readUpdateRecoveryCapsule(manifestPath, platform = process
     const expectedPackage = resolve(canonicalGlobal, ...capsule.packageName.split("/"));
     if (!samePath(canonicalPackage, expectedPackage) || !containedBy(canonicalGlobal, canonicalPackage))
         throw new Error("recovery package root is outside npm global root");
-    const expectedNpmArguments = ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${capsule.packageName}@${capsule.targetVersion}`];
-    if (JSON.stringify(capsule.npmArguments) !== JSON.stringify(expectedNpmArguments))
-        throw new Error("recovery npm arguments differ from the selected target");
+    const expectedNpmArguments = updateNpmInstallArguments(canonicalGlobal, capsule.targetVersion, platform);
+    const legacyNpmArguments = ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${capsule.packageName}@${capsule.targetVersion}`];
+    if (![expectedNpmArguments, legacyNpmArguments].some(arguments_ => sameArguments(capsule.npmArguments, arguments_))) {
+        throw new Error("recovery npm arguments differ from the selected target and prefix");
+    }
     const expectedLaunchers = updateLauncherPaths(canonicalGlobal, platform);
     if (JSON.stringify(capsule.launchers.map(path => resolve(path))) !== JSON.stringify(expectedLaunchers.map(path => resolve(path)))) {
         throw new Error("recovery launcher set differs from the canonical npm launcher set");
@@ -94,8 +116,10 @@ export async function prepareUpdateRecoveryCapsule(options) {
         await chmod(candidateEntry, 0o500);
         const canonicalGlobal = await realpath(options.globalRoot);
         const platform = options.platform ?? process.platform;
-        const launcherRoot = platform === "win32" ? dirname(canonicalGlobal) : resolve(canonicalGlobal, "..", "..", "bin");
-        const npmCli = await resolveNpmCli(canonicalGlobal, options.environment ?? process.env);
+        const prefix = npmPrefixForGlobalRoot(canonicalGlobal, platform);
+        const launcherRoot = platform === "win32" ? prefix : resolve(prefix, "bin");
+        const npmCliRoot = await realpath(options.npmCliRoot ?? canonicalGlobal);
+        const npmCli = await resolveNpmCli(npmCliRoot, options.environment ?? process.env);
         const capsule = {
             schema: UPDATE_RECOVERY_SCHEMA,
             launchContract: PRIVATE_LAUNCH_CONTRACT,
@@ -114,7 +138,7 @@ export async function prepareUpdateRecoveryCapsule(options) {
             recoveryEntryDigest: createHash("sha256").update(entryBytes).digest("hex"),
             nodeExecutable: process.execPath,
             npmCli,
-            npmArguments: ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_TEXT.packageName}@${options.transaction.targetVersion}`],
+            npmArguments: updateNpmInstallArguments(canonicalGlobal, options.transaction.targetVersion, platform),
             cancellationPath: resolve(finalRoot, "cancel.json"),
             resultPath: resolve(finalRoot, "result.json"),
             ownerPath: resolve(finalRoot, "owner.json"),
@@ -341,6 +365,12 @@ async function readJson(path) { return JSON.parse(await readFile(path, "utf8"));
 function samePath(left, right) {
     return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
 }
+function sameSegment(left, right, platform) {
+    return platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+function sameArguments(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
 function containedBy(parent, child) {
     const fromParent = relative(parent, child);
     return fromParent.length > 0 && fromParent !== ".." && !fromParent.startsWith(`..${sep}`) && !isAbsolute(fromParent);

package/dist/foundation/release/update.d.ts

@@ -13,9 +13,15 @@ export interface ProcessResult {
     stderr?: string;
 }
 export type UpdateProcessRunner = (command: string, arguments_: readonly string[], request: ProcessRequest) => Promise<ProcessResult>;
+export interface UpdateFileMetadata {
+    readonly mode: number;
+    isFile(): boolean;
+    isSymbolicLink(): boolean;
+}
 export interface UpdateFileSystem {
     readFile(path: string): Promise<string>;
     realpath(path: string): Promise<string>;
+    lstat?(path: string): Promise<UpdateFileMetadata>;
     access?(path: string): Promise<void>;
 }
 export interface UpdateOutput {
@@ -85,6 +91,7 @@ export interface UpdateTransactionJournal {
 export interface UpdatePackageReplacementInput {
     readonly dataDir: string;
     readonly globalRoot: string;
+    readonly npmCliRoot: string;
     readonly packageRoot: string;
     readonly transaction: UpdateTransaction;
     readonly priorRelease: {

package/dist/foundation/release/update.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
-import { access, readFile, realpath } from "node:fs/promises";
+import { access, lstat, readFile, realpath } from "node:fs/promises";
 import { connect } from "node:net";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import crossSpawn from "cross-spawn";
 import { valid as validSemver } from "semver";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
@@ -15,12 +15,13 @@ import { materializeRelease, readMaterializedRelease } from "./release-store.js"
 import { scheduleReleaseCleanup } from "./release-gc.js";
 import { UPDATE_ACTIVATION_CONTRACT, activateInstalledRelease, delegateActivation, readActivationContracts, } from "./update-activation.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
-import { removeUpdateRecoveryCapsule, runProtectedPackageReplacement } from "./update-recovery.js";
+import { npmPrefixForGlobalRoot, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
 export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
 const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
 const defaultFileSystem = {
     async readFile(path) { return await readFile(path, "utf8"); },
     realpath,
+    lstat,
     access,
 };
 const defaultOutput = {
@@ -308,6 +309,106 @@ async function resolveRequestedPreview(runner, requested, output) {
     output.stderr(`${PRODUCT_TEXT.diagnostic(`published no preview for ${requested}.`)}\n`);
     return { version: null, exitCode: 1 };
 }
+async function resolveManagedNpmInstallation(requestedPackageRoot, fileSystem, runner, output) {
+    const rootLookup = await runNpm(runner, ["root", "--global"], true, output, "resolve npm's global package root");
+    if (rootLookup.result === null)
+        return { installation: null, exitCode: rootLookup.exitCode };
+    const activeRootText = rootLookup.result.stdout.trim();
+    if (activeRootText.length === 0) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic("could not verify its installation because npm returned an empty global package root.")}\n`);
+        return { installation: null, exitCode: 1 };
+    }
+    let packageRoot;
+    let activeGlobalRoot;
+    try {
+        [packageRoot, activeGlobalRoot] = await Promise.all([fileSystem.realpath(requestedPackageRoot), fileSystem.realpath(activeRootText)]);
+    }
+    catch (error) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not canonicalize the running and global npm paths: ${errorMessage(error)}`)}\n`);
+        return { installation: null, exitCode: 1 };
+    }
+    const expectedActivePackage = resolve(activeGlobalRoot, ...PRODUCT_PACKAGE.split("/"));
+    if (samePath(packageRoot, expectedActivePackage)) {
+        try {
+            npmPrefixForGlobalRoot(activeGlobalRoot);
+            return {
+                installation: {
+                    packageRoot,
+                    globalRoot: activeGlobalRoot,
+                    npmCliRoot: activeGlobalRoot,
+                },
+                exitCode: 0,
+            };
+        }
+        catch (error) {
+            output.stderr(`${PRODUCT_TEXT.diagnostic(`could not verify npm's active global package layout: ${errorMessage(error)}`)}\n`);
+            return { installation: null, exitCode: 1 };
+        }
+    }
+    let candidateGlobalRoot = packageRoot;
+    for (const _segment of PRODUCT_PACKAGE.split("/"))
+        candidateGlobalRoot = dirname(candidateGlobalRoot);
+    let candidatePrefix;
+    try {
+        candidatePrefix = npmPrefixForGlobalRoot(candidateGlobalRoot);
+    }
+    catch {
+        reportUnmanagedInstallation(output, packageRoot, activeGlobalRoot);
+        return { installation: null, exitCode: 1 };
+    }
+    if (!samePath(packageRoot, resolve(candidateGlobalRoot, ...PRODUCT_PACKAGE.split("/")))) {
+        reportUnmanagedInstallation(output, packageRoot, activeGlobalRoot);
+        return { installation: null, exitCode: 1 };
+    }
+    const confirmation = await runNpm(runner, ["root", "--global", "--prefix", candidatePrefix], true, output, "confirm npm ownership of the running installation");
+    if (confirmation.result === null)
+        return { installation: null, exitCode: confirmation.exitCode };
+    const confirmedRootText = confirmation.result.stdout.trim();
+    if (confirmedRootText.length === 0) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic("could not verify its installation because npm returned an empty global package root for the inferred prefix.")}\n`);
+        return { installation: null, exitCode: 1 };
+    }
+    let confirmedRoot;
+    try {
+        confirmedRoot = await fileSystem.realpath(confirmedRootText);
+    }
+    catch (error) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not canonicalize npm's confirmed global package root: ${errorMessage(error)}`)}\n`);
+        return { installation: null, exitCode: 1 };
+    }
+    if (!samePath(confirmedRoot, candidateGlobalRoot)
+        || !await launchersOwnPackage(candidateGlobalRoot, fileSystem)) {
+        reportUnmanagedInstallation(output, packageRoot, activeGlobalRoot);
+        return { installation: null, exitCode: 1 };
+    }
+    return {
+        installation: {
+            packageRoot,
+            globalRoot: candidateGlobalRoot,
+            npmCliRoot: activeGlobalRoot,
+        },
+        exitCode: 0,
+    };
+}
+async function launchersOwnPackage(globalRoot, fileSystem) {
+    const token = `node_modules/${PRODUCT_PACKAGE}/bin/cli.js`;
+    try {
+        for (const launcher of updateLauncherPaths(globalRoot)) {
+            const metadata = await (fileSystem.lstat ?? lstat)(launcher);
+            if (!metadata.isFile() || metadata.isSymbolicLink() || (process.platform !== "win32" && (metadata.mode & 0o111) === 0))
+                return false;
+            if (!(await fileSystem.readFile(launcher)).replaceAll("\\", "/").includes(token))
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function reportUnmanagedInstallation(output, packageRoot, activeGlobalRoot) {
+    output.stderr(`${PRODUCT_TEXT.diagnostic(`refused to update automatically because ${packageRoot} could not be verified as an npm-managed ${PRODUCT_PACKAGE} installation; npm's active global package root is ${activeGlobalRoot}. Run npm install --global ${PRODUCT_PACKAGE} to install it manually.`)}\n`);
+}
 export async function runSelfUpdate(options) {
     const fileSystem = options.fileSystem ?? defaultFileSystem;
     const output = options.output ?? defaultOutput;
@@ -328,6 +429,8 @@ export async function runSelfUpdate(options) {
     try {
         const packageJson = JSON.parse(await measure("package-version", async () => await fileSystem.readFile(resolve(options.packageRoot, "package.json"))));
         const parsedVersion = typeof packageJson.version === "string" ? validSemver(packageJson.version) : null;
+        if (packageJson.name !== PRODUCT_PACKAGE)
+            throw new Error(`package.json does not identify ${PRODUCT_PACKAGE}`);
         if (parsedVersion === null)
             throw new Error("package.json does not contain a valid semantic version");
         runningVersion = parsedVersion;
@@ -347,26 +450,10 @@ export async function runSelfUpdate(options) {
     // and a trailing one reads as part of the version rather than as punctuation.
     output.stdout(`${PRODUCT_TEXT.commandName} update: ${runningVersion} → ${targetVersion}\n`);
     const progress = createUpdateProgress(output, options.progress ?? (options.output === undefined && process.stdout.isTTY === true));
-    const rootLookup = await measure("global-root", async () => await runNpm(runner, ["root", "--global"], true, output, "resolve npm's global package root"));
-    if (rootLookup.result === null)
-        return rootLookup.exitCode;
-    if (rootLookup.result.stdout.trim().length === 0) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic("could not verify its installation because npm returned an empty global package root.")}\n`);
-        return 1;
-    }
-    let packageRoot;
-    let globalRoot;
-    try {
-        [packageRoot, globalRoot] = await Promise.all([fileSystem.realpath(options.packageRoot), fileSystem.realpath(rootLookup.result.stdout.trim())]);
-    }
-    catch (error) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not canonicalize the running and global npm paths: ${errorMessage(error)}`)}\n`);
-        return 1;
-    }
-    if (!isContainedBy(globalRoot, packageRoot)) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`refused to update automatically because ${packageRoot} is not managed beneath npm's global package root ${globalRoot}.`)}\n`);
-        return 1;
-    }
+    const managed = await measure("global-root", async () => await resolveManagedNpmInstallation(options.packageRoot, fileSystem, runner, output));
+    if (managed.installation === null)
+        return managed.exitCode;
+    const { packageRoot, globalRoot, npmCliRoot } = managed.installation;
     const environment = options.environment ?? process.env;
     const paths = resolveProductPaths(environment);
     const lifecycle = options.lifecycle ?? createUpdateLifecycleCoordinator(environment, fileSystem, output);
@@ -427,6 +514,7 @@ export async function runSelfUpdate(options) {
                 const replacement = await measure("npm-install", async () => await (options.packageReplacement ?? runProtectedPackageReplacement)({
                     dataDir: paths.dataDir,
                     globalRoot,
+                    npmCliRoot,
                     packageRoot,
                     transaction: replacementTransaction,
                     priorRelease,
@@ -453,7 +541,7 @@ export async function runSelfUpdate(options) {
                 }
             }
             else {
-                const installation = await measure("npm-install", async () => await runNpm(runner, ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_PACKAGE}@${targetVersion}`], true, output, "start the global npm installation", false));
+                const installation = await measure("npm-install", async () => await runNpm(runner, updateNpmInstallArguments(globalRoot, targetVersion), true, output, "start the global npm installation", false));
                 if (installation.result === null)
                     throw new UpdateFailure(installation.exitCode, "npm process failed");
                 if (installation.result.code !== 0) {
@@ -624,6 +712,9 @@ async function canonicalImmutableRoot(dataDir, releaseRoot) {
         return false;
     }
 }
+function samePath(left, right) {
+    return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
+}
 function isContainedBy(parent, child) {
     const pathFromParent = relative(parent, child);
     return pathFromParent.length > 0 && pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent);

package/dist/integrations/pi/components/models-dialog.js

@@ -1,5 +1,5 @@
 import { Input, Key, getKeybindings, matchesKey, truncateToWidth, } from "@earendil-works/pi-tui";
-import { piTheme } from "./theme.js";
+import { piTheme, renderPiModalShortcutHints } from "./theme.js";
 const MAX_VISIBLE_ROWS = 10;
 const MODELS_TITLE = "Models";
 function fullModelId(model) {
@@ -228,7 +228,7 @@ export class ModelsDialogComponent {
         push();
         if (this.#refreshStatus !== undefined)
             push(theme.fg(this.#refreshStatus.kind, `  ${this.#refreshStatus.message}`));
-        push(theme.fg("dim", `  ${this.#hints().join(" · ")}`));
+        push(renderPiModalShortcutHints(this.#hints(), 2));
         push(border);
         return lines;
     }
@@ -237,13 +237,13 @@ export class ModelsDialogComponent {
         const confirm = keyLabel("tui.select.confirm");
         const save = keyLabel("app.models.save");
         return [
-            "type to search",
-            "↑↓ navigate",
-            ...(tab.length === 0 ? [] : [`${tab} filter`]),
-            ...(confirm.length === 0 ? [] : [`${confirm} switch`]),
-            "space scope",
-            ...(save.length === 0 ? [] : [`${save} save`]),
-            "esc close",
+            { action: "type to search" },
+            { key: "↑↓", action: "navigate" },
+            ...(tab.length === 0 ? [] : [{ key: tab, action: "filter" }]),
+            ...(confirm.length === 0 ? [] : [{ key: confirm, action: "switch" }]),
+            { key: "space", action: "scope" },
+            ...(save.length === 0 ? [] : [{ key: save, action: "save" }]),
+            { key: "esc", action: "close" },
         ];
     }
     #emptyText() {

package/dist/integrations/pi/components/shell-editor-autocomplete.js

@@ -132,9 +132,17 @@ export function createPiShellEditor(options) {
         const commands = collapsed.commands;
         const additions = new Map(commands.map(command => [command.name, command]));
         const builtInNames = new Set(builtInCatalog.map(command => command.name));
-        const builtIns = builtInCatalog.map(command => autocompleteCommand(command, additions.get(command.name)));
-        // Invariant: the engine's built-in additions only decorate this profile's catalog; they never surface as resources.
-        const resources = commands.filter(command => command.source !== "builtin" && !builtInNames.has(command.name)).map(command => autocompleteCommand(command));
+        const builtIns = builtInCatalog.flatMap(command => [
+            autocompleteCommand(command, additions.get(command.name)),
+            // Rationale: the collapsed browser is a primary bare-A1 command, not a resource after quit.
+            ...(command.name === "settings" && collapsed.collapsedCommand !== undefined
+                ? [autocompleteCommand(collapsed.collapsedCommand)]
+                : []),
+        ]);
+        // Invariant: built-in additions and the promoted collapsed browser never reappear as resources.
+        const resources = commands
+            .filter(command => command.name !== collapsed.collapsedCommand?.name && command.source !== "builtin" && !builtInNames.has(command.name))
+            .map(command => autocompleteCommand(command));
         const combined = new CombinedAutocompleteProvider([...builtIns, ...resources], options.cwd ?? process.cwd());
         autocompleteProvider = tunnelSkills.length === 0 ? combined : createSkillsTunnelProvider(combined, tunnelSkills);
         editor.setAutocompleteProvider(autocompleteProvider);
@@ -229,10 +237,26 @@ export function createPiShellEditor(options) {
             if (editorUx !== undefined && matchesKey(data, "shift+tab")
                 && !Object.values(keybindings.getEffectiveConfig()).some(keys => (Array.isArray(keys) ? keys : [keys]).some(key => key !== undefined && matchesKey(data, key))))
                 return;
+            const hadDraft = editor.getText().length > 0;
             if (editorUx === undefined)
                 editor.handleInput(data);
             else
                 editorUx.handleInput(data);
+            if (editorUx === undefined || !hadDraft || editor.getText().length > 0)
+                return;
+            // Invariant: Pi's deletion paths can leave a visible or debounced autocomplete request owned by
+            // the removed draft. Reapplying empty text cancels both forms without a duplicate change notice.
+            const onChange = editor.onChange;
+            delete editor.onChange;
+            try {
+                editor.setText("");
+            }
+            finally {
+                if (onChange === undefined)
+                    delete editor.onChange;
+                else
+                    editor.onChange = onChange;
+            }
         },
         invalidate: () => editor.invalidate(),
         setFocused: focused => {

package/dist/integrations/pi/components/shell-extension-ui.js

@@ -1,5 +1,7 @@
-import { ExtensionInputComponent, ExtensionSelectorComponent, getSelectListTheme, } from "../startup-public.js";
-import { ExtensionEditorComponent, } from "./upstream/components/extension-editor.js";
+import { getSelectListTheme, } from "../startup-public.js";
+import { ExtensionEditorComponent } from "./upstream/components/extension-editor.js";
+import { ExtensionInputComponent } from "./upstream/components/extension-input.js";
+import { ExtensionSelectorComponent } from "./upstream/components/extension-selector.js";
 import { setKeybindings, Text, } from "@earendil-works/pi-tui";
 import { KeybindingsManager, } from "./upstream/adjacent/core/keybindings.js";
 import { PINNED_PI_LAYOUT, applyPiTheme, applyPiThemeInstance, getAvailablePiThemes, loadPiTheme, piTheme, } from "./theme.js";

package/dist/integrations/pi/components/shell-footer-status.js

@@ -165,7 +165,7 @@ function liveWorkingText(view, workingOverride, progressPresentation) {
     const message = workingOverride ?? view.status.workingMessage ?? "Working";
     const progress = view.status.workingProgress;
     return workingOverride === undefined && progressPresentation === "custom-viewport" && typeof progress === "number"
-        ? `${message} (${progress}%)`
+        ? `${message}(${progress}%)`
         : message;
 }
 function statusComponent(view, ui, outputPad, liveStatusText, placement) {