@timurproko/a1 0.2.7-dev.1287 → 0.2.7-dev.1290

package/dist/foundation/lifecycle/session-worktree-completion.js

@@ -0,0 +1,190 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { detachSessionRepositoryContextForCompletion, readActiveSessionRepositoryContext, readSessionStartupRoot, sessionWorktreeClaimState, sessionWorktreeCompletionPath, } from "./session-repository-context.js";
+const SCHEMA = "a1-session-worktree-completion-v1";
+const CLEANUP_DECLARATION = ".a1/worktree.json";
+const MAX_RECORD_BYTES = 16 * 1024;
+const MAX_REPORT_CHARACTERS = 4_000;
+/** A request the runtime did not settle promptly is dropped, never run later by surprise. */
+const REQUEST_LIFETIME_MS = 5 * 60_000;
+const CLEANUP_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Leave the attached checkout so its cleanup can run after the issuing shell has exited.
+ * Unpublished content, a Git lock, or uncertain ownership keeps the session attached.
+ */
+export async function requestSessionWorktreeCompletion(identity, selectors, options) {
+    if (selectors.change !== undefined && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(selectors.change)) {
+        throw failure("worktree-completion-selector", "the change selector must be a kebab-case change id");
+    }
+    if (selectors.pr !== undefined && (!Number.isSafeInteger(selectors.pr) || selectors.pr < 1)) {
+        throw failure("worktree-completion-selector", "the pull-request selector must be a positive number");
+    }
+    const attached = await readActiveSessionRepositoryContext(identity, options);
+    if (attached === null)
+        throw failure("worktree-not-attached", "no task worktree is attached");
+    const status = await execute("git", ["-c", "core.hooksPath=/dev/null", "status", "--porcelain", "--untracked-files=all"], attached.cwd, options.signal);
+    const changed = status.split(/\r?\n/u).filter(Boolean);
+    if (changed.length > 0) {
+        const listed = changed.slice(0, 5).map(line => line.slice(3)).join(", ");
+        throw failure("worktree-content", `the attached worktree holds uncommitted or untracked content (${listed}${changed.length > 5 ? ", ..." : ""})`);
+    }
+    const path = sessionWorktreeCompletionPath(identity, options);
+    const detached = await detachSessionRepositoryContextForCompletion(identity, options, async (left) => {
+        if (!samePath(left.worktreeRoot, attached.cwd))
+            throw failure("worktree-context-changed", "the attachment changed during completion");
+        const record = {
+            schema: SCHEMA, sessionId: identity.sessionId, startupRoot: left.startupRoot, commonDir: left.commonDir,
+            worktreeRoot: left.worktreeRoot, worktreeGitDir: left.worktreeGitDir, branch: left.branch,
+            ...(selectors.change === undefined ? {} : { change: selectors.change }),
+            ...(selectors.pr === undefined ? {} : { pr: selectors.pr }),
+            requestedAt: Date.now(),
+        };
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+            await rename(temporary, path);
+        }
+        finally {
+            await rm(temporary, { force: true }).catch(() => undefined);
+        }
+    });
+    return { startupRoot: detached.startupRoot, cwd: detached.worktreeRoot, branch: detached.branch };
+}
+/**
+ * Run a pending completion's repository cleanup from the startup checkout. The request is consumed
+ * before anything runs, so it executes at most once; null means nothing was pending.
+ */
+export async function settleSessionWorktreeCompletion(identity, options) {
+    const path = sessionWorktreeCompletionPath(identity, options);
+    const record = await readRecord(path);
+    await rm(path, { force: true });
+    if (record === null || record.sessionId !== identity.sessionId)
+        return null;
+    const request = { startupRoot: record.startupRoot, cwd: record.worktreeRoot, branch: record.branch };
+    const result = (kind, detail) => ({ ...request, kind, detail });
+    try {
+        if ((options.now ?? Date.now)() - record.requestedAt > REQUEST_LIFETIME_MS)
+            return result("cleanup-skipped", "the completion request expired before the runtime could settle it");
+        const startup = await realpath(await readSessionStartupRoot(identity));
+        if (!samePath(startup, record.startupRoot))
+            return result("cleanup-skipped", "the session's startup checkout is not the recorded primary checkout");
+        const claim = await sessionWorktreeClaimState(record.commonDir, record.worktreeGitDir, options);
+        if (claim === "live")
+            return result("cleanup-skipped", "a live session attached the checkout again");
+        if (claim === "unverifiable")
+            return result("cleanup-skipped", "the checkout's editing claim cannot be verified");
+        // Security: the command is the primary checkout's committed declaration, never a file of the task checkout being left.
+        const declared = await readCleanupDeclaration(join(startup, CLEANUP_DECLARATION));
+        if (declared === null)
+            return result("cleanup-unavailable", `this repository declares no cleanup command in ${CLEANUP_DECLARATION}; the checkout was retained`);
+        if (declared === "invalid")
+            return result("cleanup-unavailable", `${CLEANUP_DECLARATION} must hold {"cleanup": ["program", "argument", ...]}; the checkout was retained`);
+        const values = {
+            primary: startup, worktree: record.worktreeRoot, branch: record.branch,
+            change: record.change, pr: record.pr === undefined ? undefined : String(record.pr),
+        };
+        const missing = new Set();
+        const [command, ...arguments_] = declared.map(part => part.replace(/\{([a-z]+)\}/gu, (_match, name) => {
+            const value = values[name];
+            if (value === undefined)
+                missing.add(name);
+            return value ?? "";
+        }));
+        if (missing.size > 0 || command === undefined) {
+            return result("cleanup-unavailable", `the declared cleanup needs ${[...missing].map(name => `{${name}}`).join(" and ")}; run completion with the matching selector or the repository cleanup from primary`);
+        }
+        const run = options.run ?? execute;
+        try {
+            return result("cleanup-finished", bounded(await run(command, arguments_, startup, options.signal)));
+        }
+        catch (error) {
+            const output = isRecord(error) ? [error.stdout, error.stderr].filter(value => typeof value === "string" && value.length > 0).join("\n") : "";
+            return result("cleanup-failed", bounded(output || (error instanceof Error ? error.message : String(error))));
+        }
+    }
+    catch (error) {
+        return result("cleanup-skipped", error instanceof Error ? error.message : String(error));
+    }
+}
+/** The agent-facing account of a settled completion; the session is on the startup checkout in every case. */
+export function describeWorktreeCompletion(result) {
+    const headline = {
+        "cleanup-finished": "the repository cleanup command ran; its report below is authoritative",
+        "cleanup-failed": "the repository cleanup command failed; the checkout may remain and is retried with repository cleanup from primary",
+        "cleanup-unavailable": "cleanup is unavailable; the checkout was retained",
+        "cleanup-skipped": "cleanup was skipped; the checkout was retained",
+    };
+    return [
+        `Worktree completion (${result.kind}): ${headline[result.kind]}.`,
+        `Session uses ${result.startupRoot}; left ${result.cwd} (${result.branch}). Do not attach it again while cleanup is partial.`,
+        result.detail,
+    ].join("\n");
+}
+/** Null when the repository declares nothing; "invalid" when the declaration cannot be used as an argument list. */
+async function readCleanupDeclaration(path) {
+    const metadata = await lstat(path).catch(error => { if (isRecord(error) && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+        return null; throw error; });
+    if (metadata === null)
+        return null;
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size === 0 || metadata.size > MAX_RECORD_BYTES)
+        return "invalid";
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        const cleanup = isRecord(value) ? value.cleanup : undefined;
+        return Array.isArray(cleanup) && cleanup.length > 0 && cleanup.length <= 64
+            && cleanup.every(part => typeof part === "string" && part.length > 0 && part.length <= 2_048 && !part.includes("\0"))
+            // Compatibility: the element check above establishes the string array.
+            ? cleanup : "invalid";
+    }
+    catch {
+        return "invalid";
+    }
+}
+async function readRecord(path) {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size === 0 || metadata.size > MAX_RECORD_BYTES)
+            return null;
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (!isRecord(value) || value.schema !== SCHEMA)
+            return null;
+        const text = (name) => typeof value[name] === "string" && value[name].length > 0 && value[name].length <= 32_768;
+        if (!["sessionId", "startupRoot", "commonDir", "worktreeRoot", "worktreeGitDir", "branch"].every(text))
+            return null;
+        if (typeof value.requestedAt !== "number" || !Number.isFinite(value.requestedAt))
+            return null;
+        if (value.change !== undefined && typeof value.change !== "string")
+            return null;
+        if (value.pr !== undefined && (typeof value.pr !== "number" || !Number.isSafeInteger(value.pr) || value.pr < 1))
+            return null;
+        // Compatibility: the checks above establish every field of the stored shape.
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function execute(command, arguments_, cwd, signal) {
+    const { execFile } = await import("node:child_process");
+    const { stdout } = await promisify(execFile)(command, [...arguments_], {
+        cwd, encoding: "utf8", windowsHide: true, timeout: CLEANUP_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024, signal,
+    });
+    return stdout;
+}
+function bounded(text) {
+    const trimmed = text.trim();
+    return trimmed.length <= MAX_REPORT_CHARACTERS ? trimmed : `...${trimmed.slice(-MAX_REPORT_CHARACTERS)}`;
+}
+function samePath(left, right) {
+    const key = (value) => process.platform === "win32" ? resolve(value).toLowerCase() : resolve(value);
+    return key(left) === key(right);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function failure(code, message) {
+    return Object.assign(new Error(message), { code });
+}

package/dist/foundation/release/early-accent.d.ts

@@ -1,4 +1,5 @@
-type UiAccentColor = "blue" | "purple" | "cyan" | "green" | "orange" | "pink";
+import { SHARED_PROGRESS_PALETTE } from "../../contracts/presentation/index.js";
+type UiAccentColor = keyof typeof SHARED_PROGRESS_PALETTE;
 type EarlyAccentAppearance = "dark" | "light";
 type EarlyAccentMode = "truecolor" | "256color";
 /** Read only global profile data, never project settings or the interactive resource pipeline. */

package/dist/integrations/pi/components/upstream/theme/theme.js

@@ -45,6 +45,7 @@ const ACCENT_PALETTE = Object.freeze({
     green: Object.freeze({ dark: okhslColor(159, 0.59, 0.67), light: okhslColor(159, 0.75, 0.46) }),
     orange: Object.freeze({ dark: okhslColor(48, 0.75, 0.67), light: okhslColor(48, 0.90, 0.47) }),
     pink: Object.freeze({ dark: okhslColor(337, 0.72, 0.67), light: okhslColor(337, 0.75, 0.48) }),
+    grey: Object.freeze({ dark: okhslColor(0, 0, 0.67), light: okhslColor(0, 0, 0.47) }),
 });
 /** Canonical named color used by both the interactive theme and pre-load palette generation. */
 export function namedPiAccent(color, appearance) {
@@ -59,6 +60,7 @@ function wrapHue(hue) {
 /** Derive the complete semantic family from any primary accent, including future custom colors. */
 export function derivePiAccentProjection(accent, appearance) {
     const { h, s, l } = colorToOkhsl(accent);
+    const neutral = s < 0.001;
     const warm = h < 90 || h >= 270;
     const magenta = h >= 270 && h < 325;
     const blue = h >= 210 && h < 270;
@@ -69,10 +71,10 @@ export function derivePiAccentProjection(accent, appearance) {
     const selectedLightness = dark ? l * 0.37 : 1 - (1 - l) * 0.075;
     return Object.freeze({
         accent,
-        border: okhslColor(borderHue, clamp(s * 0.78, 0.30, 0.64), clamp(l - (dark ? 0.17 : 0.11), 0, 1)),
-        secondaryHeading: okhslColor(secondaryHue, clamp(s + 0.20, 0.62, 0.82), clamp(l + (dark ? 0.09 : -0.09), 0, 1)),
-        selectedBg: okhslColor(h, selectedSaturation, selectedLightness),
-        userMessageBg: okhslColor(h, selectedSaturation * 2 / 3, dark ? l * 0.34 : 1 - (1 - l) * 0.055),
+        border: okhslColor(borderHue, neutral ? 0 : clamp(s * 0.78, 0.30, 0.64), clamp(l - (dark ? 0.17 : 0.11), 0, 1)),
+        secondaryHeading: okhslColor(secondaryHue, neutral ? 0 : clamp(s + 0.20, 0.62, 0.82), clamp(l + (dark ? 0.09 : -0.09), 0, 1)),
+        selectedBg: okhslColor(h, neutral ? 0 : selectedSaturation, selectedLightness),
+        userMessageBg: okhslColor(h, neutral ? 0 : selectedSaturation * 2 / 3, dark ? l * 0.34 : 1 - (1 - l) * 0.055),
     });
 }
 let activeBaseTheme;
@@ -118,8 +120,8 @@ export function derivePiCanvasBackground(style, accent) {
         return null;
     if (style === "dark")
         return okhslColor(229, 0.03, 0.12);
-    const { h } = colorToOkhsl(accent);
-    return okhslColor(h, 0.12, 0.12);
+    const { h, s } = colorToOkhsl(accent);
+    return okhslColor(h, s < 0.001 ? 0 : 0.12, 0.12);
 }
 /** Resolves the selected canvas through the active accent and terminal color mode. */
 export function piCanvasBackgroundAnsi(style) {

package/dist/integrations/pi/engine/runtime-integration.js

@@ -142,7 +142,7 @@ export async function createPiRuntimeIntegration(options) {
                 services,
                 sessionManager: targetSessionManager,
                 ...(options.worktreeCwdReader === undefined ? {} : {
-                    customTools: createSessionWorktreeTools(cwd, signal => options.worktreeCwdReader(targetSessionManager.getSessionId(), targetSessionManager.getSessionFile(), signal ?? options.signal ?? new AbortController().signal)).filter(tool => !services.resourceLoader.getExtensions().extensions.some(extension => extension.tools.has(tool.name))),
+                    customTools: createSessionWorktreeTools(cwd, signal => options.worktreeCwdReader(targetSessionManager.getSessionId(), targetSessionManager.getSessionFile(), signal ?? options.signal ?? new AbortController().signal), options.worktreeCwdReader.settleShell === undefined ? undefined : signal => options.worktreeCwdReader.settleShell(targetSessionManager.getSessionId(), targetSessionManager.getSessionFile(), signal ?? options.signal ?? new AbortController().signal)).filter(tool => !services.resourceLoader.getExtensions().extensions.some(extension => extension.tools.has(tool.name))),
                 }),
                 ...(sessionStartEvent ? { sessionStartEvent } : {}),
                 ...(modelScope.model && !hasExistingSession ? { model: modelScope.model } : {}),

package/dist/integrations/pi/engine/worktree-tools.d.ts

@@ -1,4 +1,7 @@
 import { type ToolDefinition } from "../startup-public.js";
-export type PiWorktreeCwdReader = (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string>;
+export type PiWorktreeCwdReader = ((sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string>) & {
+    /** Settles work a finished shell command left for the runtime; the text is appended to that command's result. */
+    readonly settleShell?: (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string | null>;
+};
 /** Built-in tool definitions borrow the current attachment per call, without process-global chdir. */
-export declare function createSessionWorktreeTools(startupCwd: string, resolveCwd: (signal?: AbortSignal) => Promise<string>): ToolDefinition[];
+export declare function createSessionWorktreeTools(startupCwd: string, resolveCwd: (signal?: AbortSignal) => Promise<string>, settleShell?: (signal?: AbortSignal) => Promise<string | null>): ToolDefinition[];

package/dist/integrations/pi/engine/worktree-tools.js

@@ -1,20 +1,35 @@
 import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, defineTool, } from "../startup-public.js";
 /** Built-in tool definitions borrow the current attachment per call, without process-global chdir. */
-export function createSessionWorktreeTools(startupCwd, resolveCwd) {
+export function createSessionWorktreeTools(startupCwd, resolveCwd, settleShell) {
     function wrap(factory) {
         const definition = factory(startupCwd);
         return defineTool({
             ...definition,
             ...(definition.name === "bash" ? { promptGuidelines: [
                     ...(definition.promptGuidelines ?? []),
-                    "For task worktrees, use a1 worktree enter <branch> or a1 worktree attach <absolute-path>; success confirms attachment and subsequent built-in tools use that root. a1 worktree detach preserves files. Coordination and recovery are internal; no follow-up inventory check is required.",
+                    "For task worktrees, use a1 worktree enter <branch> or a1 worktree attach <absolute-path>; success confirms attachment and subsequent built-in tools use that root. a1 worktree detach preserves files. After a verified merge run a1 worktree complete instead of cleaning the attached checkout yourself; it returns this session to the startup checkout first and reports the repository cleanup result. Coordination and recovery are internal; no follow-up inventory check is required.",
                 ] } : {}),
             defaultActive: false,
             async execute(...args) {
                 const [id, params, signal, onUpdate, context] = args;
                 const cwd = await resolveCwd(signal);
                 signal?.throwIfAborted();
-                return await factory(cwd).execute(id, params, signal, onUpdate, { ...context, cwd });
+                if (definition.name !== "bash" || settleShell === undefined)
+                    return await factory(cwd).execute(id, params, signal, onUpdate, { ...context, cwd });
+                // Invariant: the shell has exited before settlement, so it no longer pins the checkout it was started in.
+                const settle = () => settleShell(signal).catch(error => `Worktree completion could not be settled: ${error instanceof Error ? error.message : String(error)}`);
+                let result;
+                try {
+                    result = await factory(cwd).execute(id, params, signal, onUpdate, { ...context, cwd });
+                }
+                catch (error) {
+                    const settled = await settle();
+                    if (settled !== null && error instanceof Error)
+                        error.message = `${error.message}\n\n${settled}`;
+                    throw error;
+                }
+                const settled = await settle();
+                return settled === null ? result : { ...result, content: [...result.content, { type: "text", text: settled }] };
             },
         });
     }

package/dist/ui/settings/declarations.d.ts

@@ -9,6 +9,8 @@ export interface OwnedUiSettingDeclaration {
     };
     readonly description: string;
     readonly application: OwnedUiSettingApplication;
+    readonly storage?: "session";
+    readonly initialValueFrom?: string;
     readonly defaultValue: OwnedUiSettingValue;
     readonly allowedValues: readonly OwnedUiSettingValue[];
     /**
@@ -34,9 +36,23 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
         defaultValue: "auto";
         allowedValues: readonly ["auto", "manual"];
     }>;
+    readonly defaultAccentColor: Readonly<{
+        id: "defaultAccentColor";
+        label: "Default color";
+        section: Readonly<{
+            id: "appearance";
+            title: "Appearance";
+        }>;
+        description: "Startup color for future sessions. Changing this does not recolor running sessions.";
+        application: "restart";
+        defaultValue: "blue";
+        allowedValues: readonly ["blue", "green", "orange", "pink", "purple", "cyan", "grey"];
+    }>;
     readonly accentColor: Readonly<{
         id: "accentColor";
-        label: "Accent color";
+        label: "Current color";
+        storage: "session";
+        initialValueFrom: "defaultAccentColor";
         section: Readonly<{
             id: "appearance";
             title: "Appearance";
@@ -44,7 +60,7 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
         description: "Color used by highlighted interface controls, list markers, and tonal interface surfaces.";
         application: "live";
         defaultValue: "blue";
-        allowedValues: readonly ["blue", "purple", "cyan", "green", "orange", "pink"];
+        allowedValues: readonly ["blue", "green", "orange", "pink", "purple", "cyan", "grey"];
     }>;
     readonly backgroundStyle: Readonly<{
         id: "backgroundStyle";

package/dist/ui/settings/declarations.js

@@ -1,6 +1,5 @@
-const UI_ACCENT_COLOR_CHOICES = Object.freeze([
-    "blue", "purple", "cyan", "green", "orange", "pink",
-]);
+import { UI_ACCENT_COLORS } from "../../contracts/owned-ui/index.js";
+const UI_ACCENT_COLOR_CHOICES = UI_ACCENT_COLORS;
 const MAX_ID_LENGTH = 64;
 const ID_PATTERN = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
 const GENERIC_SECTION = Object.freeze({ id: "generic", title: "Generic" });
@@ -17,9 +16,20 @@ export const OWNED_SETTING_DECLARATIONS = Object.freeze({
         defaultValue: "auto",
         allowedValues: Object.freeze(["auto", "manual"]),
     }),
+    defaultAccentColor: Object.freeze({
+        id: "defaultAccentColor",
+        label: "Default color",
+        section: APPEARANCE_SECTION,
+        description: "Startup color for future sessions. Changing this does not recolor running sessions.",
+        application: "restart",
+        defaultValue: "blue",
+        allowedValues: UI_ACCENT_COLOR_CHOICES,
+    }),
     accentColor: Object.freeze({
         id: "accentColor",
-        label: "Accent color",
+        label: "Current color",
+        storage: "session",
+        initialValueFrom: "defaultAccentColor",
         section: APPEARANCE_SECTION,
         description: "Color used by highlighted interface controls, list markers, and tonal interface surfaces.",
         application: "live",

package/dist/ui/settings/early-accent.d.ts

@@ -99,6 +99,22 @@ export declare function preTrustPalette(color: UiAccentColor, appearance: Appear
     accent: string;
     border: string;
     selectedBg: string;
+} | {
+    accent: string;
+    border: string;
+    selectedBg: string;
+} | {
+    accent: string;
+    border: string;
+    selectedBg: string;
+} | {
+    accent: string;
+    border: string;
+    selectedBg: string;
+} | {
+    accent: string;
+    border: string;
+    selectedBg: string;
 };
 export declare function preTrustTerminalAppearance(environment?: NodeJS.ProcessEnv): Appearance;
 export declare function preTrustTerminalColorMode(environment?: NodeJS.ProcessEnv): ColorMode;

package/dist/ui/settings/early-accent.js

@@ -21,9 +21,7 @@ export function readPreTrustAccent(environment = process.env) {
         const namespace = root[PRODUCT_IDENTITY.commandName];
         if (namespace === null || typeof namespace !== "object" || Array.isArray(namespace))
             return "blue";
-        const value = namespace.accentColor;
-        if (value === "default")
-            return "purple";
+        const value = namespace.defaultAccentColor;
         return typeof value === "string" && Object.hasOwn(SHARED_PROGRESS_PALETTE, value) ? value : "blue";
     }
     catch {

package/dist/ui/settings/manager.d.ts

@@ -30,8 +30,9 @@ export interface OwnedUiSettingsChangeOutcome {
 }
 export type OwnedUiSettingsListener = (manager: OwnedSettingsManager) => void;
 /**
- * One profile's A1 settings: resolves the declaration table against the stored document,
- * persists each accepted change atomically without discarding unknown keys, offers the
+ * Owns a profile's durable settings and this session's ephemeral overrides. Durable changes
+ * persist atomically without discarding unknown or legacy session keys; session changes stay local.
+ * Offers the
  * grouped sections a surface presents, and routes every accepted change only to its
  * owning backend, with agent settings reached through the engine settings port.
  */
@@ -42,6 +43,7 @@ export declare class OwnedSettingsManager {
     get resolution(): OwnedUiSettingsResolution;
     /** Reads and resolves the product namespace. Never throws: every failure becomes a notice. */
     read(): OwnedUiSettingsResolution;
+    startSession(): void;
     load(): Promise<void>;
     /**
      * Adopts values another process stored in the shared document. Notifies only when a

package/dist/ui/settings/manager.js

@@ -7,8 +7,9 @@ import { readProfileSettingsNamespace, repairProfileSettingsDocument, updateProf
 const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const MAX_DOCUMENT_BYTES = 256 * 1024;
 /**
- * One profile's A1 settings: resolves the declaration table against the stored document,
- * persists each accepted change atomically without discarding unknown keys, offers the
+ * Owns a profile's durable settings and this session's ephemeral overrides. Durable changes
+ * persist atomically without discarding unknown or legacy session keys; session changes stay local.
+ * Offers the
  * grouped sections a surface presents, and routes every accepted change only to its
  * owning backend, with agent settings reached through the engine settings port.
  */
@@ -26,6 +27,7 @@ export class OwnedSettingsManager {
     #agentSnapshot = null;
     #pending = new Map();
     #restartEffective = new Map();
+    #sessionValues = new Map();
     constructor(options) {
         if (!PROFILE_ID_PATTERN.test(options.profileId)) {
             throw new Error(`owned UI settings profile id is not a bounded slug: ${options.profileId}`);
@@ -42,6 +44,7 @@ export class OwnedSettingsManager {
         this.#hiddenAgentSettingIds = new Set(options.hiddenAgentSettingIds ?? []);
         this.#agentSettingLabelOverrides = { ...(options.agentSettingLabelOverrides ?? {}) };
         this.#resolution = this.read();
+        this.startSession();
         for (const setting of this.#resolution.settings) {
             if (setting.declaration.application === "restart")
                 this.#restartEffective.set(setting.declaration.id, setting.value);
@@ -71,11 +74,31 @@ export class OwnedSettingsManager {
         return this.#resolveNamespace(null, shared.status === "invalid" ? shared.detail : undefined);
     }
     #resolveNamespace(values, unreadableDetail) {
-        return resolveOwnedUiSettings({
+        const resolution = resolveOwnedUiSettings({
             declarations: this.#declarations,
             values,
             ...(unreadableDetail === undefined ? {} : { unreadableDetail }),
         });
+        return { ...resolution, settings: resolution.settings.map(setting => {
+                const value = this.#sessionValues.get(setting.declaration.id);
+                return setting.declaration.storage !== "session" || value === undefined ? setting : { ...setting, value };
+            }) };
+    }
+    startSession() {
+        this.#resolution = this.read();
+        for (const declaration of this.#declarations) {
+            if (declaration.storage !== "session")
+                continue;
+            const source = this.#resolution.settings.find(setting => setting.declaration.id === declaration.initialValueFrom);
+            const value = source !== undefined && declaration.allowedValues.includes(source.value) ? source.value : declaration.defaultValue;
+            this.#sessionValues.set(declaration.id, value);
+            if (source !== undefined && source.declaration.application === "restart") {
+                this.#restartEffective.set(source.declaration.id, source.value);
+                this.#pending.delete(source.declaration.id);
+            }
+        }
+        this.#resolution = this.read();
+        this.#notify();
     }
     async load() {
         this.#resolution = this.read();
@@ -159,6 +182,15 @@ export class OwnedSettingsManager {
         return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgentValue(id, value);
     }
     #changeOwned(id, value) {
+        const declaration = this.#declarations.find(candidate => candidate.id === id);
+        if (!declaration?.allowedValues.includes(value))
+            return failed(`value ${JSON.stringify(value)} is not allowed for ${id}`);
+        if (declaration.storage === "session") {
+            this.#sessionValues.set(id, value);
+            this.#resolution = this.read();
+            this.#notify();
+            return changed("applied", "live", value, value);
+        }
         const outcome = this.#write(id, value);
         if (!outcome.stored)
             return failed(outcome.failure ?? `${id} could not be stored`);
@@ -285,7 +317,7 @@ function fromAgentOutcome(result) {
 function compactValues(resolution) {
     const values = { ...resolution.preserved };
     for (const setting of resolution.settings) {
-        if (setting.value !== setting.declaration.defaultValue)
+        if (setting.declaration.storage !== "session" && setting.value !== setting.declaration.defaultValue)
             values[setting.declaration.id] = setting.value;
     }
     return values;

package/dist/ui/settings/resolution.js

@@ -11,7 +11,7 @@ export function resolveOwnedUiSettings(input) {
     const values = input.values ?? {};
     const settings = [];
     for (const declaration of input.declarations) {
-        if (!Object.hasOwn(values, declaration.id)) {
+        if (declaration.storage === "session" || !Object.hasOwn(values, declaration.id)) {
             settings.push({ declaration, value: declaration.defaultValue, source: "default" });
             continue;
         }
@@ -29,7 +29,8 @@ export function resolveOwnedUiSettings(input) {
     }
     const preserved = {};
     for (const [key, value] of Object.entries(values)) {
-        if (findOwnedUiSettingDeclaration(input.declarations, key) === null)
+        const declaration = findOwnedUiSettingDeclaration(input.declarations, key);
+        if (declaration === null || declaration.storage === "session")
             preserved[key] = value;
     }
     return {

package/docs/architecture/project-structure.md

@@ -119,7 +119,7 @@ A1 owns creation/attachment, bounded retries, and ordinary recovery behind its w
 
 Claude Code uses its established `EnterWorktree` tool by task name. The tracked `.claude/settings.json` wires `scripts/governance/claude-worktree-create.mjs` to create `.worktrees/<task-id>` detached at fresh `origin/develop`, or return an already registered path. The agent must still establish ownership before reusing that path and create the topic branch in a new detached worktree before editing. Passing an absolute `path` to `EnterWorktree` is reserved for a worktree created by hand, from primary before any shell command in that session. The matching `WorktreeRemove` hook declines removal: leave with `ExitWorktree` `keep` and use only the guarded cleanup tool for removal. Other agents do not need these tools or hooks.
 
-A1 attachment updates footer repository/PR discovery and subsequent built-in tool working directories without changing process-global cwd. Detach/disposal releases the runtime's claim and preserves Git data. An existing PR is not required. Explicit absolute paths retain their meaning; custom extensions and independent terminals keep their own cwd. Attachment never creates a Git lock, changes cleanup registration, or grants acceptance, finalization, merge, or deletion authority.
+A1 attachment updates footer repository/PR discovery and subsequent built-in tool working directories without changing process-global cwd. Detach/disposal releases the runtime's claim and preserves Git data. After a verified merge, `a1 worktree complete` detaches first and then runs the repository's configured cleanup from the startup checkout; an attachment whose checkout is gone is released automatically. An existing PR is not required. Explicit absolute paths retain their meaning; custom extensions and independent terminals keep their own cwd. Attachment never creates a Git lock, changes cleanup registration, or grants acceptance, finalization, merge, or deletion authority.
 
 An agent that directly chooses a transient file path for a PR/comment body, command payload, captured output, temporary patch/diff, or ad hoc log must place it beneath the verified task worktree's exact `.artifacts/` root, never the primary checkout, another worktree, OS temp, home/desktop, or a sibling path. Such scratch remains ignored, unstaged, uncommitted, disposable, non-authoritative, and secret-free. This repository path rule does not relocate storage internally selected by tools, product runtime code, or hermetic tests.
 

package/docs/features/session-colors.md

@@ -0,0 +1,66 @@
+# Session colors and local API
+
+Bare A1 offers two Settings → Appearance controls:
+
+- **Default color** is saved in the active profile as `defaultAccentColor`. It initially resolves to blue. It controls the next session start, not the running interface.
+- **Current color** applies immediately to this active session only. It is not saved to profile settings and does not propagate to other sessions on the same machine, profile, or project.
+
+Both menus offer **blue → green → orange → pink → purple → cyan → grey**, with color previews. There is no automatic/dashed option. Grey keeps the derived semantic family and accent canvas neutral; unrelated success/warning/error colors are unchanged.
+
+A fresh launch, resumed transcript, or successful new/resume/fork/import replacement initializes Current color from the latest saved Default color. Missing or invalid defaults resolve to blue. A failed replacement retains the old session and color. Changing the saved default does not recolor any running session. Cancel and undo respect each setting's storage scope.
+
+The legacy profile `accentColor` key is retained but ignored by interactive color resolution. Current colors never overwrite it. The comparison `a1 pi` profile is unchanged. Standalone installation/update progress keeps its existing saved-profile preference policy.
+
+## Integration commands
+
+External applications such as Herdr can invoke the installed CLI as a subprocess. These commands always return JSON without a `--json` switch:
+
+| Arguments after `a1` | Result |
+| --- | --- |
+| `session color list` | Available color identifiers in display order; no running session needed |
+| `session color get --session <id>` | One live session's Current color |
+| `session color set pink --session <id>` | Set only that session's Current color and acknowledge the applied value |
+
+The selector is a **complete session UUID**, shown by A1's Session Info workflow. It is not a PID, terminal index, abbreviated prefix, transcript path, or machine-wide current session. Get/set require one explicitly targeted live bare-A1 session outside an A1 shell. Within a shell launched by that exact session, omission uses the existing `PI_SESSION_ID`, `PI_SESSION_FILE`, and A1 runtime identity together; it never selects a different session implicitly. Keep the runtime-directory environment consistent when controlling a custom runtime root.
+
+Get/set do not change Default color. Configure the startup preference in Settings. An API write immediately updates the Current color value visible there, along with semantic colors and accent-derived backgrounds.
+
+### Responses
+
+Inventory returns only the color list, not a hard-coded default that could be confused with the configured startup preference:
+
+```json
+{"colors":["blue","green","orange","pink","purple","cyan","grey"]}
+```
+
+Get and successful set use the same shape:
+
+```json
+{"sessionId":"57e38e80-f348-4b28-b791-7cc080886a70","color":"pink"}
+```
+
+Failures return:
+
+```json
+{"error":{"code":"session-unavailable","message":"Select one running bare session by its complete session id."}}
+```
+
+Exactly one newline-terminated JSON object is written to stdout, without progress or human-readable prefixes. Error messages are explanatory text and can evolve; applications should branch on `error.code`. Exit statuses:
+
+- **0:** successful list/get/applied set.
+- **2:** invalid arguments, color, session format, or missing required selector.
+- **1:** unavailable/ambiguous target, timeout, or control failure.
+
+Error codes include `invalid-request`, `invalid-color`, `invalid-session`, `session-required`, `session-unavailable`, `ambiguous-session`, `request-expired`, `control-boundary`, `control-limit`, and `control-failed`. Hosts without a color command adapter return `control-unavailable`. Ordinary `session color help` and global help remain human-readable. CLI capability metadata advertises `sessionColors: true`.
+
+### Herdr integration
+
+Invoke `a1` with an argument array rather than interpolating a shell string. For example, pass `["session", "color", "set", "pink", "--session", sessionId]`, capture stdout, await process completion, and parse its one JSON object. On exit 0, update Herdr's local UI from the returned `sessionId` and `color`. On nonzero exit, display or handle the structured error; do not treat a queued write or process creation as successful application. No subscription/event feed or host-app icon recoloring is provided.
+
+## Lifetime and safety
+
+Control starts alongside the interactive shell and stops with it. It uses an in-process local IPC endpoint: a Windows named pipe or Unix-domain socket, with bounded private discovery records under the runtime directory. It does not introduce a separate resident service, TCP port, or HTTP server. Comparison-profile sessions do not publish endpoints.
+
+Requests have a three-second end-to-end budget, bounded payloads, process-liveness checks, runtime identity, a private endpoint nonce, session binding checks, and correlated acknowledgements. Concurrent requests serialize in the target runtime. Set reports success only after its live settings change path applies the color. Requests still queued after expiry, disconnect, stop, or session replacement cannot recolor a later session. A timeout means application was not acknowledged: a change already applied just before a lost response is not rolled back; get the current value before deciding whether to retry. No delayed request is persisted for future replay.
+
+Private runtime records are not a public file-editing API. Do not write settings files or edit endpoint records to control Current color. Unverifiable, ambiguous, replaced, stopped, malformed, and comparison-profile targets fail closed without choosing another session. An unavailable control directory or failed endpoint startup leaves the interactive session usable, but external control reports unavailable. Worktree attachment authority is unaffected.