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

package/dist/features/owned-ui/project-trust-prompt.js

@@ -42,7 +42,7 @@ export function createConsoleProjectTrustPrompt(options = {}) {
                 optionRow("Trust", selected === 0),
                 optionRow("Do not trust", selected === 1),
                 "",
-                `${DIM}  ↑/↓${MUTED} to navigate  ${DIM}Enter${MUTED} to select  ${DIM}Esc${MUTED} to cancel${RESET_FG}`,
+                `${DIM}↑/↓${MUTED} to navigate  ${DIM}Enter${MUTED} to select  ${DIM}Esc${MUTED} to cancel${RESET_FG}`,
             ];
             output.write(`${CLEAR_HOME}${lines.map(line => clipAnsiSafe(line, width)).join("\n")}`);
         };

package/dist/features/owned-ui/reference-screen-app.js

@@ -134,11 +134,11 @@ export class ReferenceScreenApp {
             : null;
         const withRail = withScrollbarRail(body.slice(0, bodyHeight), geometry, contentWidth, theme, { presentation });
         const hint = this.#interruptArmed
-            ? theme.fg("dim", "press ctrl+c again to exit a1")
-            : renderShortcutHints(REFERENCE_SCREEN_SHORTCUTS.hintEntries(SCOPE), theme);
+            ? theme.fg("dim", " press ctrl+c again to exit a1")
+            : renderShortcutHints(REFERENCE_SCREEN_SHORTCUTS.hintEntries(SCOPE), theme, 1);
         // Compatibility: the v2 reference screen frames its document between two border-coloured rules.
         const rule = theme.fg("border", "─".repeat(rect.width));
-        // Compatibility: the footer remains against the left edge, unlike the settings status line.
+        // Invariant: dialog chrome shares the title's one-cell inset; document content keeps its own layout.
         const frame = [rule, ...withRail, rule, padToWidth(hint, rect.width)];
         // Invariant: a rectangle too small for the chrome still gets exactly its rows, top first.
         return frame.slice(0, rect.height).concat(Array(Math.max(0, rect.height - frame.length)).fill(""));

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

@@ -20,8 +20,8 @@ export { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDoc
 export type { RestartSeal, RestartValidationEvent } from "./restart-certification.js";
 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, UpdateFileMetadata, UpdateFileSystem, UpdateLifecycleCoordinator, UpdateMaterializationProgress, UpdateMeasuredPhase, UpdateOutput, UpdateOwnershipAction, UpdatePackageReplacementInput, UpdatePerformanceEvidence, UpdatePhaseTimingEvent, UpdateProcessRunner, UpdateTransactionJournal, } from "./update.js";
+export { PACKAGE_UNLOCK_PATIENCE_MS, PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, isPackageLockError, lockedPackageDiagnostic, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
+export type { ProcessRequest, ProcessResult, SelfUpdateOptions, UpdateActivationPhase, UpdateChannel, UpdateFileMetadata, UpdateFileSystem, UpdateLifecycleCoordinator, UpdateMaterializationProgress, UpdateMeasuredPhase, UpdateOutput, UpdateOwnershipAction, UpdatePackageReplacementInput, UpdatePerformanceEvidence, UpdatePhaseTimingEvent, UpdateProcessRunner, UpdateTransactionJournal, UpdateUnlockPatience, } 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";

package/dist/foundation/release/index.js

@@ -9,7 +9,7 @@ export { collectRelease, prepareReleaseCleanup, runBoundedReleaseCleanup, runRel
 export { RELEASE_MANIFEST_FILENAME, assertImmutableExecutionRoot, consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease, } from "./release-store.js";
 export { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument, restartSealDigest } from "./restart-certification.js";
 export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistry } from "./stable-release.js";
-export { PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
+export { PACKAGE_UNLOCK_PATIENCE_MS, PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, isPackageLockError, lockedPackageDiagnostic, 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, npmPrefixForGlobalRoot, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";

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

@@ -23,6 +23,16 @@ export interface UpdateFileSystem {
     realpath(path: string): Promise<string>;
     lstat?(path: string): Promise<UpdateFileMetadata>;
     access?(path: string): Promise<void>;
+    rename?(from: string, to: string): Promise<void>;
+}
+/**
+ * How long the update keeps checking that nothing holds the package tree, and the clock it
+ * checks with. Tests inject a clock; the product waits in real time.
+ */
+export interface UpdateUnlockPatience {
+    readonly windowMs?: number;
+    readonly sleep?: (durationMs: number) => Promise<void>;
+    readonly now?: () => number;
 }
 export interface UpdateOutput {
     stdout(message: string): void;
@@ -103,6 +113,17 @@ export interface UpdatePackageReplacementInput {
     readonly environment: NodeJS.ProcessEnv;
     readonly onRecoveryState: (state: UpdateRecoveryState) => Promise<void>;
 }
+/**
+ * The package tree is checked for holders by renaming it and renaming it back, because on
+ * Windows that is the one operation that fails while any file under it is open. A holder is
+ * usually brief: a scanner, an indexer, a file browser, or a session still shutting down.
+ * The update therefore keeps checking for this long before it calls the package locked.
+ */
+export declare const PACKAGE_UNLOCK_PATIENCE_MS = 15000;
+/** Whether a rename failure means something holds the tree, as opposed to the tree being wrong. */
+export declare function isPackageLockError(error: unknown): boolean;
+/** What the user reads when the package stayed held for the whole patience window. */
+export declare function lockedPackageDiagnostic(packageRoot: string, waitedMs: number, attempts: number, error: unknown): string;
 /** Bound on the child diagnostics an update keeps: enough for npm's failure reason, never a log. */
 export declare const CHILD_DIAGNOSTIC_LIMIT = 8000;
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
@@ -114,7 +135,7 @@ export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end
  * because that installation is exactly what is about to be replaced under it.
  */
 export declare function planUpdateOwnership(ownership: "live-verified" | "dead", runsFromRetainedRelease: boolean): UpdateOwnershipAction;
-export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput): UpdateLifecycleCoordinator;
+export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput, patience?: UpdateUnlockPatience): UpdateLifecycleCoordinator;
 /** Renders the terminal-only update meter; the visual preview shares this exact frame. */
 export declare function renderUpdateProgressBar(percent: number): string;
 export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;

package/dist/foundation/release/update.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { access, lstat, readFile, realpath } from "node:fs/promises";
+import { access, lstat, readFile, realpath, rename } from "node:fs/promises";
 import { connect } from "node:net";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import crossSpawn from "cross-spawn";
@@ -23,7 +23,32 @@ const defaultFileSystem = {
     realpath,
     lstat,
     access,
+    rename,
 };
+/**
+ * The package tree is checked for holders by renaming it and renaming it back, because on
+ * Windows that is the one operation that fails while any file under it is open. A holder is
+ * usually brief: a scanner, an indexer, a file browser, or a session still shutting down.
+ * The update therefore keeps checking for this long before it calls the package locked.
+ */
+export const PACKAGE_UNLOCK_PATIENCE_MS = 15_000;
+const PACKAGE_UNLOCK_INITIAL_DELAY_MS = 100;
+const PACKAGE_UNLOCK_MAX_DELAY_MS = 1_000;
+// Platform: Windows reports a held directory as EPERM or EBUSY; EACCES and ENOTEMPTY are the other
+// spellings a rename gives to a tree something is using. Anything else is not a lock.
+const PACKAGE_LOCK_CODES = new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY"]);
+const defaultSleep = async (durationMs) => await new Promise(resolvePromise => setTimeout(resolvePromise, durationMs));
+/** Whether a rename failure means something holds the tree, as opposed to the tree being wrong. */
+export function isPackageLockError(error) {
+    return error instanceof Error && "code" in error && typeof error.code === "string" && PACKAGE_LOCK_CODES.has(error.code);
+}
+/** What the user reads when the package stayed held for the whole patience window. */
+export function lockedPackageDiagnostic(packageRoot, waitedMs, attempts, error) {
+    const seconds = Math.max(1, Math.round(waitedMs / 1_000));
+    return PRODUCT_TEXT.diagnostic(`package remained locked for ${seconds}s after verified shutdown (${attempts} checks): ${errorMessage(error)}. `
+        + `Another program is holding a file under ${packageRoot}: an antivirus scan, a file browser or terminal open inside it, `
+        + `or a session still shutting down. Close it and run the update again; nothing was changed.`);
+}
 const defaultOutput = {
     stdout(message) { process.stdout.write(message); },
     stderr(message) { process.stderr.write(message); },
@@ -79,7 +104,7 @@ async function readActiveEndpoint(paths, activeReleaseId, environment) {
     const legacy = await readEndpointMetadata(legacyPaths.endpointMetadataPath);
     return legacy ? { metadata: legacy, paths: legacyPaths } : null;
 }
-export function createUpdateLifecycleCoordinator(environment = process.env, fileSystem = defaultFileSystem, output = defaultOutput) {
+export function createUpdateLifecycleCoordinator(environment = process.env, fileSystem = defaultFileSystem, output = defaultOutput, patience = {}) {
     const paths = resolveProductPaths(environment);
     const stateStore = new CohortStateStore(paths.dataDir);
     return {
@@ -139,16 +164,40 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             if (fileSystem.access)
                 await fileSystem.access(packageRoot);
             const probe = `${packageRoot}.${PRODUCT_IDENTITY.filesystem.slug}-unlock-probe`;
-            const { rename } = await import("node:fs/promises");
-            try {
-                await rename(packageRoot, probe);
-                await rename(probe, packageRoot);
-            }
-            catch (error) {
-                // Invariant: best-effort rollback runs if the first rename succeeded and the second did not.
-                await rename(probe, packageRoot).catch(() => { });
-                throw new Error(PRODUCT_TEXT.diagnostic(`package remains locked after verified shutdown: ${errorMessage(error)}`));
-            }
+            const renameTree = fileSystem.rename ?? rename;
+            const windowMs = patience.windowMs ?? PACKAGE_UNLOCK_PATIENCE_MS;
+            const now = patience.now ?? Date.now;
+            const sleep = patience.sleep ?? defaultSleep;
+            const startedAt = now();
+            let delay = PACKAGE_UNLOCK_INITIAL_DELAY_MS;
+            let attempts = 0;
+            // Rationale: a holder found right after ownership was released is almost always transient,
+            // so one failed rename is a reason to look again, not to abandon an update that has not
+            // yet changed anything. The wait is bounded so a genuine lock still fails clearly.
+            const withPatience = async (from, to, describeFailure) => {
+                while (true) {
+                    attempts += 1;
+                    try {
+                        await renameTree(from, to);
+                        return;
+                    }
+                    catch (error) {
+                        const elapsed = now() - startedAt;
+                        if (!isPackageLockError(error) || elapsed >= windowMs)
+                            throw describeFailure(error);
+                        // Rationale: the last pause is cut to the window's edge so the wait ends when promised.
+                        await sleep(Math.min(delay, windowMs - elapsed));
+                        delay = Math.min(PACKAGE_UNLOCK_MAX_DELAY_MS, delay * 2);
+                    }
+                }
+            };
+            await withPatience(packageRoot, probe, error => isPackageLockError(error)
+                ? new Error(lockedPackageDiagnostic(packageRoot, now() - startedAt, attempts, error))
+                : new Error(PRODUCT_TEXT.diagnostic(`could not verify that the package is unlocked: ${errorMessage(error)}`)));
+            // Invariant: the package tree is put back under its own name before this returns; a holder
+            // that appears while it wears the probe name is waited out the same way, and if it never
+            // lets go the diagnostic names where the tree is so the user can restore it.
+            await withPatience(probe, packageRoot, error => new Error(PRODUCT_TEXT.diagnostic(`could not restore the package after checking it was unlocked: ${errorMessage(error)}. The package is at ${probe}; rename it back to ${packageRoot} before running the update again.`)));
         },
         async activateInstalled(packageRoot, targetVersion, phase, onMaterializing, onWarmup) {
             const request = { packageRoot, dataDir: paths.dataDir, targetVersion, environment };

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

@@ -228,7 +228,7 @@ export class ModelsDialogComponent {
         push();
         if (this.#refreshStatus !== undefined)
             push(theme.fg(this.#refreshStatus.kind, `  ${this.#refreshStatus.message}`));
-        push(renderPiModalShortcutHints(this.#hints(), 2));
+        push(renderPiModalShortcutHints(this.#hints()));
         push(border);
         return lines;
     }

package/dist/integrations/pi/components/shell-editor-autocomplete.d.ts

@@ -16,14 +16,8 @@ export declare const PINNED_PI_BUILTIN_SLASH_COMMANDS: ({
 export declare const OWNED_BUILTIN_SLASH_COMMANDS: ({
     readonly name: "thinking";
     readonly description: "Set thinking level";
-    readonly argumentHint: "<level>";
-} | {
-    name: string;
-    description: string;
-    argumentHint?: never;
 } | {
     name: string;
     description: string;
-    argumentHint: string;
 })[];
 export declare function createPiShellEditor(options: PiShellEditorOptions): PiShellEditorPort;

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

@@ -9,12 +9,14 @@ import { createTuiFacade, ensureTheme, isAutocompleteProvider, } from "./shell-s
 import { SKILLS_COMMAND_NAME, collapseSkillCommands, createSkillsTunnelProvider, } from "./skills-command.js";
 /** A selected autocomplete row: the accent primary column, then the aligned description. */
 const SELECTED_DESCRIBED_ROW = /^(→ .*?\S)(\s{2,}.*)$/u;
-const THINKING_SLASH_COMMAND = { name: "thinking", description: "Set thinking level", argumentHint: "<level>" };
+const PINNED_THINKING_SLASH_COMMAND = { name: "thinking", description: "Set thinking level", argumentHint: "<level>" };
+const OWNED_THINKING_SLASH_COMMAND = { name: "thinking", description: "Set thinking level" };
+const OWNED_LOGIN_SLASH_COMMAND = { name: "login", description: "Configure provider authentication" };
 export const PINNED_PI_BUILTIN_SLASH_COMMANDS = [
     { name: "settings", description: "Open settings menu" },
     { name: "model", description: "Select model (opens selector UI)", argumentHint: "<provider/model>" },
     { name: "tree", description: "Navigate session tree (switch branches)" },
-    THINKING_SLASH_COMMAND,
+    PINNED_THINKING_SLASH_COMMAND,
     { name: "scoped-models", description: "Enable/disable models for Ctrl+P cycling" },
     { name: "export", description: "Export session (HTML default, or specify path: .html/.jsonl)" },
     { name: "import", description: "Import and resume a session from a JSONL file" },
@@ -36,9 +38,16 @@ export const PINNED_PI_BUILTIN_SLASH_COMMANDS = [
     { name: "quit", description: "Quit" },
 ];
 /** Bare A1's built-in catalog: `models` replaces the pinned pair and is followed by `thinking`. */
-export const OWNED_BUILTIN_SLASH_COMMANDS = PINNED_PI_BUILTIN_SLASH_COMMANDS.flatMap(command => command.name === "model"
-    ? [{ name: "models", description: "Switch models and manage scoped model cycling" }, THINKING_SLASH_COMMAND]
-    : command.name === "thinking" || command.name === "scoped-models" ? [] : [command]);
+export const OWNED_BUILTIN_SLASH_COMMANDS = PINNED_PI_BUILTIN_SLASH_COMMANDS.flatMap(command => {
+    if (command.name === "model") {
+        return [{ name: "models", description: "Switch models and manage scoped model cycling" }, OWNED_THINKING_SLASH_COMMAND];
+    }
+    if (command.name === "thinking" || command.name === "scoped-models")
+        return [];
+    if (command.name === "login")
+        return [OWNED_LOGIN_SLASH_COMMAND];
+    return [command];
+});
 export function createPiShellEditor(options) {
     ensureTheme();
     const tui = createTuiFacade(options);

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

@@ -49,7 +49,7 @@ class SkillsSelectorComponent extends Container {
             { key: "↑↓", action: "navigate" },
             { key: bindings.getKeys("tui.select.confirm").join("/"), action: "select" },
             { key: bindings.getKeys("tui.select.cancel").join("/"), action: "cancel" },
-        ], 2), 0, 0));
+        ]), 0, 0));
         this.addChild(new DynamicBorder());
         this.#updateList();
     }

package/dist/integrations/pi/components/upstream/components/scoped-models-selector.js

@@ -179,7 +179,7 @@ export class ScopedModelsSelectorComponent extends Container {
             { key: reorderKeys, action: "reorder" },
             { key: keyDisplayText("app.models.save"), action: "save" },
             { action: countText },
-        ], 2);
+        ]);
         return this.isDirty ? `${hint} ${theme.fg("warning", "(unsaved)")}` : hint;
     }
     refresh() {

package/dist/integrations/pi/components/upstream/components/thinking-selector.js

@@ -74,7 +74,7 @@ export class OwnedThinkingSelectorComponent extends Container {
             { key: this.keyDisplayText("tui.select.confirm"), action: "to select" },
             { key: this.keyDisplayText("app.thinking.save"), action: "to set as default" },
             { key: this.keyDisplayText("tui.select.cancel"), action: "to cancel" },
-        ], 2), 0, 0));
+        ]), 0, 0));
         this.addChild(new DynamicBorder((text) => piTheme().fg("border", text)));
     }
     keyDisplayText(keybinding) {

package/dist/integrations/pi/components/upstream/components/tree-selector.js

@@ -1080,7 +1080,8 @@ class TreeHelp {
             return renderPiModalShortcutHints([key ? { key, action: label, ...(labelFirst === undefined ? {} : { actionFirst: labelFirst }) } : { action: label }]);
         });
         const availableWidth = Math.max(1, width);
-        const indent = "  ";
+        // Match the title's Text padding plus its two-cell authored inset.
+        const indent = "   ";
         const separator = "  ";
         const lines = [];
         let currentLine = "";

package/dist/integrations/pi/engine/resource-catalog.js

@@ -178,7 +178,7 @@ export class PiResourceCatalog {
             {
                 name: "login",
                 description: "Configure provider authentication",
-                argumentHint: "<provider>",
+                ...(this.#productMode === "comparison" ? { argumentHint: "<provider>" } : {}),
                 argumentOptions: this.#contexts.loginOptions().map(option => ({ ...option, id: option.id.split(":").at(-1) ?? option.id })),
                 source: "builtin",
             },

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-09-22T23:31:15.773Z",
+  "builtAt": "2026-09-23T10:26:02.976Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "9db1726bbe3fc2e8292f2ead1e7e9d0fd4d7d0dc9217b372582bf354b0f565dc",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-22T23:30:53.377Z",
+  "builtAt": "2026-09-23T10:25:44.532Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "d8cda6b0c7cb36c0cc41e90802aceebf6c02eaebbc08a83d7d963d2e918dbd7a",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-22T23:31:43.770Z",
+  "builtAt": "2026-09-23T10:26:28.697Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "57ed4829927f81b1cb638ffafa7a5b3832537284aa343c0eb0ef70592ed671d3",
+    "sha256": "3350a8cef128cf5a794ff0f9bb46eb6c99dd10f390f40a9083f4b5c13f0e7d62",
     "size": 177664
   },
   "provenance": {

package/dist/ui/components/dialog-panel.js

@@ -27,9 +27,9 @@ export function renderDialogPanel(state, width, theme) {
     });
     const description = state.rows[state.index]?.description ?? "";
     const hint = typeof state.hint === "string"
-        ? theme.fg("dim", `  ${state.hint}`)
-        : renderShortcutHints(state.hint, theme, 2);
-    const plainHint = typeof state.hint === "string" ? `  ${state.hint}` : shortcutHintsText(state.hint, 2);
+        ? theme.fg("dim", ` ${state.hint}`)
+        : renderShortcutHints(state.hint, theme, 1);
+    const plainHint = typeof state.hint === "string" ? ` ${state.hint}` : shortcutHintsText(state.hint, 1);
     return [
         rule,
         ...rows,

package/docs/architecture/project-structure.md

@@ -92,15 +92,18 @@ Build output mirrors the production namespaces directly under ignored `dist/`, w
 
 Every task worktree must be created at `{working-dir}/.worktrees/<task-id>`, where `{working-dir}` is the agent session's initial working directory. The `.worktrees` directory is inside that working directory, not beside it. For working directory `D:/Git/a1`, `D:/Git/a1/.worktrees/<task-id>` is correct and `D:/Git/a1-<task-id>` is forbidden.
 
-From the initial working directory, create and address a task worktree explicitly:
+From the initial working directory, create the task branch and worktree, run `a1 session link-worktree <absolute-worktree>` from the owning A1 session, and continue to address it explicitly:
 
 ```sh
 git fetch origin develop
-git worktree add --detach .worktrees/<task-id> origin/develop
+git worktree add -b <type>/<short-description> .worktrees/<task-id> origin/develop
+a1 session link-worktree <absolute-worktree>
 git -C .worktrees/<task-id> status
 ```
 
-The primary worktree stays on `develop` for integration and must not be used for task edits. Do not edit, move, or remove another session's worktree.
+A successful link response confirming the exact canonical worktree is required before planning, implementation, test, or delivery-documentation edits. If linking fails or confirms another path, stop task edits and report the blocker instead of continuing with primary-checkout footer metadata. A session resuming an existing delivery or switching streams links the exact owned worktree before editing it.
+
+The association switches bare A1's footer repository context and pull-request discovery; it does not change process or tool cwd and does not register, claim, release, or authorize cleanup of the worktree. Repository commands therefore keep an explicit worktree path. The primary worktree stays on `develop` for integration and must not be used for task edits. Do not edit, adopt, move, or remove another session's worktree.
 
 ## Documentation and comments
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.546",
+  "version": "0.1.8-dev.558",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",