pi-ui-extend 1.0.28 → 1.0.31

package/dist/app/app.d.ts

@@ -86,6 +86,7 @@ export declare class PiUiExtendApp {
     private setInput;
     private resetInputAfterProgrammaticEdit;
     private restoreTabInputState;
+    private restoreEditorSnapshot;
     private clearPersistedInputDraft;
     private insertVoiceTranscript;
     private pasteInternalClipboard;

package/dist/app/app.js

@@ -345,6 +345,13 @@ export class PiUiExtendApp {
             restoreSessionStatus: () => this.restoreSessionStatus(),
             setInput: (value) => this.setInput(value),
             getInput: () => this.input,
+            setInputState: (state) => this.restoreTabInputState(state),
+            getInputState: () => this.inputEditor.draftState,
+            setInputSnapshot: (snapshot) => this.restoreEditorSnapshot(snapshot),
+            getInputSnapshot: () => ({
+                text: this.inputEditor.expandedText,
+                images: this.inputEditor.images.map((image) => ({ ...image })),
+            }),
             get entries() { return app.entries; },
             deleteConversationEntry: (entryId) => this.conversationViewport.deleteEntry(entryId),
         });
@@ -982,6 +989,11 @@ export class PiUiExtendApp {
         this.inputEditor.restoreDraftState(state);
         this.autocompleteController.dispose();
     }
+    restoreEditorSnapshot(snapshot) {
+        this.restoreTabInputState({ text: snapshot.text, cursor: snapshot.text.length });
+        for (const image of snapshot.images)
+            this.inputEditor.attachImage(image.data, image.mimeType);
+    }
     async clearPersistedInputDraft() {
         await this.tabsController.setInputStateForTab(this.tabsController.activeInputTabId(), { text: "", cursor: 0 });
     }

package/dist/app/extensions/extension-ui-controller.d.ts

@@ -1,6 +1,7 @@
 import { type Theme } from "../../theme.js";
 import { type ToastKind, type ToastNotifier } from "../../ui.js";
-import type { Entry, ExtensionInputMouseEvent, ExtensionWidgetRegistration, ExtensionWidgetTheme, PixExtensionUIContext, PixMenuController, WidgetPlacement, WidgetTuiHandle } from "../types.js";
+import type { InputEditorDraftState } from "../../input-editor.js";
+import type { Entry, ExtensionInputMouseEvent, ExtensionWidgetRegistration, ExtensionWidgetTheme, PixExtensionUIContext, PixEditorSnapshot, PixMenuController, WidgetPlacement, WidgetTuiHandle } from "../types.js";
 export type ExtensionTerminalInputResult = {
     consume: boolean;
     data?: string;
@@ -21,6 +22,10 @@ export type ExtensionUiControllerHost = {
     restoreSessionStatus(): void;
     setInput(value: string): void;
     getInput(): string;
+    setInputState(state: InputEditorDraftState): void;
+    getInputState(): InputEditorDraftState;
+    setInputSnapshot(snapshot: PixEditorSnapshot): void;
+    getInputSnapshot(): PixEditorSnapshot;
     readonly entries: readonly Entry[];
     deleteConversationEntry(entryId: string): void;
 };

package/dist/app/extensions/extension-ui-controller.js

@@ -242,16 +242,25 @@ export class ExtensionUiController {
             pasteToEditor: (text) => {
                 if (!this.isScopeActive(contextScopeKey))
                     return;
-                this.host.setInput(text);
+                this.host.setInputState({ text, cursor: text.length });
                 renderIfRunning();
             },
             setEditorText: (text) => {
                 if (!this.isScopeActive(contextScopeKey))
                     return;
-                this.host.setInput(text);
+                this.host.setInputState({ text, cursor: text.length });
                 renderIfRunning();
             },
             getEditorText: () => this.isScopeActive(contextScopeKey) ? this.host.getInput() : "",
+            getEditorSnapshot: () => this.isScopeActive(contextScopeKey)
+                ? this.host.getInputSnapshot()
+                : { text: "", images: [] },
+            setEditorSnapshot: (snapshot) => {
+                if (!this.isScopeActive(contextScopeKey))
+                    return;
+                this.host.setInputSnapshot(snapshot);
+                renderIfRunning();
+            },
             editor: async (title, prefill) => await this.editorDialog(title, prefill, contextScopeKey),
             addAutocompleteProvider: () => undefined,
             setEditorComponent: () => undefined,
@@ -396,7 +405,7 @@ export class ExtensionUiController {
         const scopeKey = this.normalizeScopeKey(options.scopeKey);
         if (this.activeCustomUis.has(scopeKey))
             throw new Error("Another extension custom UI is already active.");
-        const savedInput = options.savedInput ?? (this.isScopeActive(scopeKey) ? this.host.getInput() : undefined);
+        const savedInput = options.savedInput ?? (this.isScopeActive(scopeKey) ? this.host.getInputState() : undefined);
         return await new Promise((resolve, reject) => {
             const active = {
                 key: CUSTOM_UI_WIDGET_KEY,
@@ -408,7 +417,7 @@ export class ExtensionUiController {
             };
             this.activeCustomUis.set(scopeKey, active);
             if (options.editorInput !== undefined)
-                this.host.setInput(options.editorInput);
+                this.host.setInputState({ text: options.editorInput, cursor: options.editorInput.length });
             const done = (value) => {
                 if (active.settled || this.activeCustomUis.get(scopeKey) !== active)
                     return;
@@ -449,8 +458,8 @@ export class ExtensionUiController {
             return;
         active.settled = true;
         this.activeCustomUis.delete(active.scopeKey);
-        if (this.isScopeActive(active.scopeKey) && active.savedInput !== undefined && this.host.getInput() !== active.savedInput) {
-            this.host.setInput(active.savedInput);
+        if (this.isScopeActive(active.scopeKey) && active.savedInput !== undefined) {
+            this.host.setInputState(active.savedInput);
         }
         try {
             active.component?.dispose?.();
@@ -477,7 +486,7 @@ export class ExtensionUiController {
             return undefined;
         const active = this.activeCustomUis.get(scopeKey);
         if (active && active.savedInput === undefined)
-            active.savedInput = this.host.getInput();
+            active.savedInput = this.host.getInputState();
         return active;
     }
     isScopeActive(scopeKey) {

package/dist/app/types.d.ts

@@ -437,6 +437,11 @@ export type AboveInputRenderer = {
     set(key: string, content: ExtensionWidgetContent): void;
     clear(key: string): void;
 };
+/** Attachment-aware editor content with virtual paste/image tags resolved. */
+export type PixEditorSnapshot = {
+    text: string;
+    images: readonly ImageContent[];
+};
 export type PixExtensionUIContext = Omit<ExtensionUIContext, "notify"> & {
     notify(message: string, type?: ToastKind): void;
     toast: ToastNotifier;
@@ -444,6 +449,8 @@ export type PixExtensionUIContext = Omit<ExtensionUIContext, "notify"> & {
     renderAboveInput(key: string, content: ExtensionWidgetContent): void;
     showMenu<T>(items: readonly PixMenuItem<T>[], options: PixMenuOptions): Promise<T | undefined>;
     menu: PixMenuController;
+    getEditorSnapshot(): PixEditorSnapshot;
+    setEditorSnapshot(snapshot: PixEditorSnapshot): void;
 };
 export type WidgetTuiHandle = {
     requestRender(force?: boolean): void;

package/dist/bundled-extensions/question/index.js

@@ -20,7 +20,8 @@ export default function questionExtension(pi) {
             const selections = await runQuestionnaire(questions, ctx);
             if (selections == null)
                 return createQuestionToolResult(createCanceledQuestionResult("user_canceled"), questions);
-            return createQuestionToolResult(createSuccessfulQuestionResult(questions, selections), questions);
+            const images = selections.flatMap((selection) => "customText" in selection ? selection.images ?? [] : []);
+            return createQuestionToolResult(createSuccessfulQuestionResult(questions, selections), questions, images);
         },
     });
 }

package/dist/bundled-extensions/question/result.d.ts

@@ -1,6 +1,6 @@
-import type { CanceledQuestionResult, NormalizedQuestion, QuestionResultDetails, QuestionSelection, QuestionToolResult, SuccessfulQuestionResult } from "./types.js";
+import type { CanceledQuestionResult, NormalizedQuestion, QuestionImageContent, QuestionResultDetails, QuestionSelection, QuestionToolResult, SuccessfulQuestionResult } from "./types.js";
 export declare function createSuccessfulQuestionResult(questions: NormalizedQuestion[], selections: QuestionSelection[]): SuccessfulQuestionResult;
 export declare function createCanceledQuestionResult(reason: CanceledQuestionResult["reason"], questions?: NormalizedQuestion[]): CanceledQuestionResult;
 export declare function createFallbackPrompt(questions: NormalizedQuestion[]): string;
 export declare function summarizeQuestionResult(result: QuestionResultDetails, questions?: NormalizedQuestion[]): string;
-export declare function createQuestionToolResult(details: QuestionResultDetails, questions?: NormalizedQuestion[]): QuestionToolResult;
+export declare function createQuestionToolResult(details: QuestionResultDetails, questions?: NormalizedQuestion[], images?: QuestionImageContent[]): QuestionToolResult;

package/dist/bundled-extensions/question/result.js

@@ -1,4 +1,7 @@
 import { throwInvalid } from "./contract.js";
+function formatAttachedImages(count) {
+    return `${count} image${count === 1 ? "" : "s"} attached`;
+}
 export function createSuccessfulQuestionResult(questions, selections) {
     const selectionsById = new Map(selections.map((selection) => [selection.id, selection]));
     return {
@@ -8,13 +11,16 @@ export function createSuccessfulQuestionResult(questions, selections) {
                 throwInvalid(`Missing answer for question "${question.id}".`, "Retry after collecting one answer for each normalized question.");
             if ("customText" in selection) {
                 const customText = selection.customText.trim();
-                if (!customText)
-                    throwInvalid(`Custom Answer for question "${question.id}" is empty after trimming.`, "Retry with non-empty Custom Answer text or choose a predefined Choice.");
+                const imageCount = selection.images?.length ?? 0;
+                if (!customText && imageCount === 0)
+                    throwInvalid(`Custom Answer for question "${question.id}" is empty after trimming.`, "Retry with non-empty Custom Answer text, an image, or choose a predefined Choice.");
+                const label = customText || formatAttachedImages(imageCount);
                 return {
                     id: question.id,
-                    value: customText,
-                    label: customText,
+                    value: customText || label,
+                    label,
                     wasCustom: true,
+                    ...(imageCount > 0 ? { imageCount } : {}),
                 };
             }
             const choiceIndex = question.choices.findIndex((choice) => choice.value === selection.choiceValue);
@@ -68,17 +74,23 @@ export function summarizeQuestionResult(result, questions = []) {
     const questionLabels = new Map(questions.map((question) => [question.id, question.label]));
     return `question answers: ${result.answers.map((answer) => {
         const questionLabel = questionLabels.get(answer.id) ?? answer.id;
-        if (answer.wasCustom)
-            return `${questionLabel}: ${answer.label} (custom answer)`;
+        if (answer.wasCustom) {
+            const imageLabel = answer.imageCount ? formatAttachedImages(answer.imageCount) : undefined;
+            const imageSuffix = imageLabel && answer.label !== imageLabel ? `; ${imageLabel}` : "";
+            return `${questionLabel}: ${answer.label} (custom answer${imageSuffix})`;
+        }
         return `${questionLabel}: ${answer.label} (choice ${answer.index})`;
     }).join("; ")}.`;
 }
-export function createQuestionToolResult(details, questions = []) {
+export function createQuestionToolResult(details, questions = [], images = []) {
     return {
-        content: [{
+        content: [
+            {
                 type: "text",
                 text: summarizeQuestionResult(details, questions),
-            }],
+            },
+            ...images.map((image) => ({ ...image })),
+        ],
         details,
     };
 }

package/dist/bundled-extensions/question/tui.js

@@ -97,6 +97,9 @@ function formatHeader(title, width) {
 function clampIndex(index, length) {
     return Math.max(0, Math.min(Math.max(0, length - 1), index));
 }
+function formatAttachedImages(count) {
+    return `${count} image${count === 1 ? "" : "s"} attached`;
+}
 export async function runQuestionnaire(questions, ctx) {
     return ctx.ui.custom((tui, theme, _keybindings, done) => {
         const selections = new Map();
@@ -104,6 +107,7 @@ export async function runQuestionnaire(questions, ctx) {
         const reviewSubmitIndex = questions.length;
         const pixCapabilities = tui.pix;
         const usesSharedEditor = Boolean(pixCapabilities?.delegatedEditorInput && ctx.ui.setEditorText && ctx.ui.getEditorText);
+        const usesEditorSnapshots = Boolean(usesSharedEditor && ctx.ui.setEditorSnapshot && ctx.ui.getEditorSnapshot);
         let questionIndex = 0;
         let selectedChoiceIndex = 0;
         let selectedReviewIndex = reviewSubmitIndex;
@@ -129,21 +133,45 @@ export async function runQuestionnaire(questions, ctx) {
         function sharedEditorText() {
             if (usesSharedEditor)
                 return ctx.ui.getEditorText?.() ?? "";
-            return customDrafts.get(currentQuestion().id) ?? "";
+            return customDrafts.get(currentQuestion().id)?.text ?? "";
+        }
+        function sharedEditorSnapshot() {
+            if (usesEditorSnapshots) {
+                const snapshot = ctx.ui.getEditorSnapshot?.();
+                if (snapshot)
+                    return cloneEditorSnapshot(snapshot);
+            }
+            return { text: sharedEditorText(), images: [] };
+        }
+        function cloneEditorSnapshot(snapshot) {
+            return {
+                text: snapshot.text,
+                images: snapshot.images.map((image) => ({ ...image })),
+            };
+        }
+        function setSharedEditorSnapshot(snapshot) {
+            const cloned = cloneEditorSnapshot(snapshot);
+            customDrafts.set(currentQuestion().id, cloned);
+            if (usesEditorSnapshots)
+                ctx.ui.setEditorSnapshot?.(cloned);
+            else if (usesSharedEditor)
+                ctx.ui.setEditorText?.(cloned.text);
         }
         function setSharedEditorText(text) {
-            customDrafts.set(currentQuestion().id, text);
+            customDrafts.set(currentQuestion().id, { text, images: [] });
             if (usesSharedEditor)
                 ctx.ui.setEditorText?.(text);
         }
         function clearSharedEditorText() {
-            if (usesSharedEditor)
+            if (usesEditorSnapshots)
+                ctx.ui.setEditorSnapshot?.({ text: "", images: [] });
+            else if (usesSharedEditor)
                 ctx.ui.setEditorText?.("");
         }
         function captureCustomDraft() {
             if (mode !== "custom")
                 return;
-            customDrafts.set(currentQuestion().id, sharedEditorText());
+            customDrafts.set(currentQuestion().id, sharedEditorSnapshot());
         }
         function getCompleteSelections() {
             const orderedSelections = [];
@@ -172,8 +200,12 @@ export async function runQuestionnaire(questions, ctx) {
             submitCompleteSelections();
         }
         function formatReviewAnswerLabel(question, selection) {
-            if ("customText" in selection)
-                return `${CUSTOM_ANSWER_LABEL}: ${selection.customText}`;
+            if ("customText" in selection) {
+                const imageCount = selection.images?.length ?? 0;
+                const text = selection.customText || formatAttachedImages(imageCount);
+                const imageSuffix = selection.customText && imageCount > 0 ? ` (+${formatAttachedImages(imageCount)})` : "";
+                return `${CUSTOM_ANSWER_LABEL}: ${text}${imageSuffix}`;
+            }
             return question.choices.find((choice) => choice.value === selection.choiceValue)?.label ?? "Unknown";
         }
         function selectionIndexForQuestion(question) {
@@ -250,11 +282,13 @@ export async function runQuestionnaire(questions, ctx) {
         function enterCustomMode() {
             const question = currentQuestion();
             const existing = selections.get(question.id);
-            const prefill = existing && "customText" in existing ? existing.customText : customDrafts.get(question.id) ?? "";
+            const prefill = existing && "customText" in existing
+                ? { text: existing.customText, images: existing.images ?? [] }
+                : customDrafts.get(question.id) ?? { text: "", images: [] };
             mode = "custom";
             selectedChoiceIndex = customAnswerIndex(question);
             customError = undefined;
-            setSharedEditorText(prefill);
+            setSharedEditorSnapshot(prefill);
             refresh();
         }
         function selectChoice(index) {
@@ -271,15 +305,19 @@ export async function runQuestionnaire(questions, ctx) {
                 enterCustomMode();
         }
         function submitCustomAnswer() {
-            const text = sharedEditorText();
-            const trimmed = text.trim();
-            if (!trimmed) {
+            const snapshot = sharedEditorSnapshot();
+            const trimmed = snapshot.text.trim();
+            if (!trimmed && snapshot.images.length === 0) {
                 customError = "Custom Answer cannot be empty.";
                 refresh();
                 return;
             }
             const question = currentQuestion();
-            selections.set(question.id, { id: question.id, customText: trimmed });
+            selections.set(question.id, {
+                id: question.id,
+                customText: trimmed,
+                ...(snapshot.images.length > 0 ? { images: snapshot.images } : {}),
+            });
             customDrafts.delete(question.id);
             clearSharedEditorText();
             advanceAfterAnswer();

package/dist/bundled-extensions/question/types.d.ts

@@ -30,6 +30,7 @@ export interface PredefinedQuestionSelection {
 export interface CustomQuestionSelection {
     id: string;
     customText: string;
+    images?: QuestionImageContent[];
 }
 export type QuestionSelection = PredefinedQuestionSelection | CustomQuestionSelection;
 export interface QuestionAnswer {
@@ -38,6 +39,7 @@ export interface QuestionAnswer {
     label: string;
     wasCustom: boolean;
     index?: number;
+    imageCount?: number;
 }
 export interface SuccessfulQuestionResult {
     answers: QuestionAnswer[];
@@ -54,8 +56,17 @@ export interface TextContent {
     type: "text";
     text: string;
 }
+export interface QuestionImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export interface QuestionEditorSnapshot {
+    text: string;
+    images: QuestionImageContent[];
+}
 export interface QuestionToolResult {
-    content: TextContent[];
+    content: Array<TextContent | QuestionImageContent>;
     details: QuestionResultDetails;
 }
 export interface QuestionUiContext {
@@ -64,6 +75,8 @@ export interface QuestionUiContext {
         custom<T>(factory: (tui: QuestionTui, theme: QuestionTheme, keybindings: unknown, done: (value: T) => void) => QuestionComponent): Promise<T | undefined>;
         setEditorText?(text: string): void;
         getEditorText?(): string;
+        setEditorSnapshot?(snapshot: QuestionEditorSnapshot): void;
+        getEditorSnapshot?(): QuestionEditorSnapshot;
         notify?(message: string, level: "info" | "warning" | "error"): void;
     };
 }

package/dist/sdk.d.ts

@@ -1,3 +1,3 @@
 export { isToastKind, Toast, TOAST_KINDS } from "./ui.js";
 export type { ToastEntry, ToastKind, ToastNotifier, ToastState } from "./ui.js";
-export type { AboveInputRenderer, ExtensionWidgetComponent, ExtensionWidgetContent, ExtensionWidgetFactory, PixMenuController, PixMenuItem, PixMenuOptions, PixMenuSelectOptions, PixMenuVariant, PixExtensionUIContext, WidgetPlacement, WidgetTuiHandle, } from "./app/types.js";
+export type { AboveInputRenderer, ExtensionWidgetComponent, ExtensionWidgetContent, ExtensionWidgetFactory, PixMenuController, PixMenuItem, PixMenuOptions, PixMenuSelectOptions, PixMenuVariant, PixExtensionUIContext, PixEditorSnapshot, WidgetPlacement, WidgetTuiHandle, } from "./app/types.js";

package/external/pi-tools-suite/README.md

@@ -370,7 +370,7 @@ The canonical use case is an **`oracle`** role that consults a flagship model fr
   "description": "Cross-provider second opinion: consult a flagship from a different provider than the parent to pressure-test a hard decision. Read-only; advise, do not edit.",
   "model": "openai-codex/gpt-5.6-sol",
   "fallbackModels": ["zai/glm-5.3"],
-  "thinking": "xhigh",
+  "thinking": "max",
   "modelByParent": {
     "zai/*":         { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] },
     "openai-codex/*": "zai/glm-5.3",

package/external/pi-tools-suite/src/async-subagents/async-subagents.sample.jsonc

@@ -244,7 +244,7 @@
       "description": "Oracle: cross-provider flagship second opinion for hard or high-stakes uncertainty. Use sparingly to pressure-test architecture, plans, root-cause hypotheses, risk/security calls, or final recommendations when independent disagreement is valuable. Read-only; advise, do not edit.",
       "model": "openai-codex/gpt-5.6-sol",
       "fallbackModels": ["zai/glm-5.3"],
-      "thinking": "xhigh",
+      "thinking": "max",
       "tools": ["read", "grep", "bash"],
       "modelByParent": {
         "zai/*": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] },

package/external/pi-tools-suite/src/async-subagents/core/config.ts

@@ -250,7 +250,7 @@ const BUILTIN_CONFIG: SubagentConfig = {
 				"antigravity/*": { model: "zai/glm-5.3", fallbackModels: ["openai-codex/gpt-5.6-sol"] },
 				"anthropic/*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
 			},
-			thinking: "xhigh",
+			thinking: "max",
 			tools: ["read", "grep", "bash"],
 			promptAppend: "You are an oracle: a flagship model from a different provider giving a second opinion to the parent agent. Give a concise, decisive recommendation with key tradeoffs and risks. Disagree when warranted; do not rubber-stamp. Do not edit unless explicitly asked.",
 		},

package/external/pi-tools-suite/src/async-subagents/private-skills/browser-qa/SKILL.md

@@ -35,7 +35,9 @@ source reading, server polling, capability probing, or retries.
    list without creating `.pi/qa_auth.jsonc`. Otherwise skip profile discovery
    and use public mode. Choose an auth profile only when the task names its id,
    safe profile traits make the choice unambiguous, or a public run proves that
-   the requested page requires login.
+   the requested page requires login. If form authentication is required but
+   there is no usable profile, follow **Form-auth scaffolding** below instead of
+   asking the user to discover selectors.
 5. Inspect the target code and write a declarative JSONC flow under
    `$PI_SUBAGENT_AGENT_DIR/browser-qa/flows/`. Never put credentials or raw
    executable JavaScript in it. The `evaluate` action exposes only the safe
@@ -208,11 +210,43 @@ after login succeeds so credentials are not captured in the trace.
 
 ## Credentials and blocked runs
 
+### Form-auth scaffolding
+
+When a public HTTPS login page (or loopback HTTP page for local development) is
+known and there is no usable profile, invoke the trusted runner once:
+
+```sh
+node <runner> auth scaffold \
+  --profile <safe-id> \
+  --login-url <public-login-url>
+```
+
+The runner discovers the login form and privately writes a target-specific
+`.pi/qa_auth.jsonc` containing `__PI_QA_SECRET_n__` values. It may create the
+file or replace only the runner's own empty generated template; it refuses to
+overwrite invalid or non-empty auth configuration. Never inspect the result.
+Relay `QA_AUTH_SCAFFOLD_CREATED`, the reported file, profile, placeholder count,
+and action, then ask the user to replace only those placeholder values. Browser
+QA must resume in a new run after the user confirms that edit.
+
+By default, login succeeds when the discovered form becomes hidden. A form-less
+page therefore requires an explicit deterministic signal using either
+`--success-url <glob>` or `--success-selector <selector>` with optional
+`--success-state attached|detached|visible|hidden`. Use `--base-url <url>` only
+to override the profile's same-origin application root. These are public
+metadata; never put credential values in command arguments or environment
+variables.
+
+Do not scaffold cookie, bearer, storage, storage-state, MFA, CAPTCHA, or
+federated login. For those modes, use the generic empty-template flow below and
+ask the user to configure the profile themselves.
+
 Do not request credentials merely because `.pi/qa_auth.jsonc` is absent. If the
 task explicitly requires authenticated behavior, or a public run reaches the
 flow's `authRejectedIf` check, and `profiles` returned no usable profile, run
-`node <runner> profiles --require-auth`. Only this explicit authenticated path
-may create the private empty template.
+form-auth scaffolding when supported. Otherwise run
+`node <runner> profiles --require-auth`. Only these explicit authenticated paths
+may create the private auth file.
 
 If that command or an authenticated run returns `QA_AUTH_UPDATE_REQUIRED`, stop
 and explicitly report that authenticated browser QA requires credentials or an
@@ -220,7 +254,9 @@ auth-config update. Ask the user to fill the reported file and rerun QA. If
 `templateCreated` is true, say that a private empty template was created at that
 path. Relay only the runner's profile, file, reason, action, and template-created
 state; never read the generated file or attempt to recover by exposing or
-replaying credentials.
+replaying credentials. If the action is `fill_credentials`, also relay the
+placeholder count and tell the user to replace only the generated placeholder
+values.
 
 For any other blocked run, report the runner status and redacted reason. Do not
 claim that browser QA passed based on source inspection, unit tests, or a build.
@@ -230,5 +266,5 @@ all non-empty `artifacts.screenshots`, `artifacts.videos`, and
 `artifacts.traces`, and `artifacts.downloads` groups in the final response.
 These links are mandatory so the user can open the evidence directly.
 
-See `references/qa-auth.example.jsonc`, `references/qa-flow.example.jsonc`, and
-`references/qa-design.md`.
+See `references/qa-auth.example.jsonc`, `references/qa-flow.example.jsonc`,
+`references/qa-design.md`, and `references/auth-scaffold-spec.md`.

package/external/pi-tools-suite/src/async-subagents/private-skills/browser-qa/references/auth-scaffold-spec.md

@@ -0,0 +1,78 @@
+# Spec: Browser QA form-auth scaffold
+
+## Type
+
+Change
+
+## Goal
+
+Let the browser-QA sub-agent prepare a target-specific form-auth configuration
+without reading, writing, receiving, or printing credential values. The user
+should only need to replace clearly marked secret placeholders.
+
+## Scope
+
+- Add a trusted runner command that inspects a public login form.
+- Generate `.pi/qa_auth.jsonc` with discovered field and submit selectors.
+- Keep generated values as non-secret placeholders until the user edits them.
+- Preserve the rule that agents never read or edit `.pi/qa_auth.jsonc`.
+
+## Non-goals
+
+- Collecting credentials interactively through the agent.
+- Guessing cookie, token, storage-state, MFA, or federated-login credentials.
+- Modifying an existing non-empty auth configuration.
+
+## Behavior
+
+- `auth scaffold` requires a project-local browser-QA sub-agent workspace, an
+  HTTPS login URL (or loopback HTTP for local development), and a safe profile
+  id.
+- The trusted runner opens the unauthenticated login page with fail-closed
+  origin routing and discovers the most likely login form, fillable fields,
+  submit control, and form container.
+- It writes a private `0600` `.pi/qa_auth.jsonc` containing only generated
+  selectors and `__PI_QA_SECRET_n__` placeholders. It may replace the runner's
+  empty generated template, but never a non-empty profiles object.
+- By default, successful login means that the discovered form becomes hidden.
+  A form-less page requires an explicit success URL pattern or selector/state.
+- A run cannot use a profile while generated placeholders remain. The runner
+  returns `QA_AUTH_UPDATE_REQUIRED` without exposing selectors or values.
+
+## Invariants
+
+- No credential value is accepted through command arguments or environment
+  variables.
+- Scaffold status output contains only path, profile id, counts, and action.
+- The command never prints inspected DOM text, input values, URLs, or selectors.
+- Agents continue to treat `.pi/qa_auth.jsonc` as opaque and user-owned.
+
+## Edge cases
+
+- Reject pages without a discoverable fillable field or submit control, and
+  form-less pages without an explicit success condition.
+- Reject remote plain-HTTP login pages.
+- Reject cross-origin base URLs and malformed success options.
+- Reject symlinked or permissive auth paths.
+- Refuse to overwrite invalid or non-empty auth configuration.
+
+## Related files
+
+- `scripts/browser-qa-runner.mjs`
+- `../SKILL.md`
+- `../../../../../test/async-subagents/browser-qa-runner.test.ts`
+
+## Verification
+
+- Unit tests for discovery output, placeholder blocking, private permissions,
+  empty-template replacement, and non-empty-config refusal.
+- Existing browser-QA runner tests and repository checks continue to pass.
+
+## Evidence
+
+- Confirmed by code: current runner owns Playwright, origin isolation, private
+  auth-file creation, validation, and redacted status output.
+- Confirmed by tests: current runner rejects permissive/symlinked auth files and
+  creates its empty template with private permissions.
+- Confirmed by docs: the private skill forbids agents from reading or editing
+  `.pi/qa_auth.jsonc`.

package/external/pi-tools-suite/src/async-subagents/private-skills/browser-qa/scripts/browser-qa-runner.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -10,6 +11,7 @@ import { parse as parseJsonc, printParseErrorCode } from "jsonc-parser";
 import { strFromU8, strToU8, unzipSync, zipSync } from "../vendor/fflate.mjs";
 
 const CONFIG_RELATIVE = ".pi/qa_auth.jsonc";
+const AUTH_SECRET_PLACEHOLDER = /^__PI_QA_SECRET_[1-9][0-9]*__$/;
 const SUBAGENT_AGENT_DIR_ENV = "PI_SUBAGENT_AGENT_DIR";
 const QA_WORKSPACE_RELATIVE = "browser-qa";
 const EVIDENCE_RELATIVE = "evidence";
@@ -109,6 +111,12 @@ if (!isMainThread && workerData?.operation === "sanitize_trace") {
 async function main() {
 	const [command = "profiles", ...rawArgs] = process.argv.slice(2);
 	const cwd = fs.realpathSync(process.cwd());
+	if (command === "auth") {
+		const [authCommand, ...authArgs] = rawArgs;
+		if (authCommand !== "scaffold") throw new QaStatusError("QA_RUN_FAILED", `unknown auth command: ${authCommand ?? "(missing)"}`, 1);
+		await runAuthScaffold(cwd, parseAuthScaffoldArgs(authArgs));
+		return;
+	}
 	if (command === "profiles") {
 		const requireAuth = rawArgs.length === 1 && rawArgs[0] === "--require-auth";
 		if (rawArgs.length > 0 && !requireAuth) {
@@ -122,7 +130,7 @@ async function main() {
 
 	const args = parseArgs(rawArgs);
 	const selected = args.profile
-		? selectProfile(readAuthConfig(cwd, true).profiles, args.profile)
+		? selectProfile(readAuthConfig(cwd, true, true).profiles, args.profile)
 		: createPublicProfile(args.baseUrl);
 	const profileId = selected.id;
 	const profile = selected.profile;
@@ -290,7 +298,189 @@ async function runQa({ cwd, agentDir, args, profileId, profile, deadline, progre
 	writeStatus({ status: "QA_PASSED", profile: profileId, ...evidenceDetails });
 }
 
-function readAuthConfig(cwd, required = false) {
+async function runAuthScaffold(cwd, args) {
+	const profileId = args.profile;
+	if (!isSafeName(profileId) || profileId.length > 128) throw new QaStatusError("QA_RUN_FAILED", "--profile must be a safe profile id no longer than 128 characters", 1);
+	const loginUrl = normalizeScaffoldUrl(args.loginUrl, "--login-url");
+	const login = new URL(loginUrl);
+	const baseUrl = normalizeScaffoldUrl(args.baseUrl ?? `${login.origin}/`, "--base-url", login.origin);
+	const success = scaffoldSuccess(args);
+	const agentDir = resolveBrowserQaAgentDirectory(cwd, process.env[SUBAGENT_AGENT_DIR_ENV]);
+	const progress = createRunnerProgress(path.join(agentDir, QA_WORKSPACE_RELATIVE));
+	assertAuthScaffoldWritable(cwd);
+	const timeout = Math.min(parseRunnerTimeout(args.runnerTimeoutMs, profileId), 60_000);
+	const deadline = Date.now() + timeout;
+	let browser;
+	let context;
+	try {
+		progress("auth_scaffold_started", { timeoutMs: timeout });
+		const playwright = loadPlaywright(cwd);
+		browser = await runStage(progress, "auth_scaffold_browser_launch", deadline, () => playwright.chromium.launch({ headless: true }), profileId);
+		context = await runStage(progress, "auth_scaffold_context_create", deadline, () => browser.newContext({
+			...DEFAULT_ENVIRONMENT,
+			serviceWorkers: "block",
+			viewport: DEFAULT_VIEWPORT,
+		}), profileId);
+		await runStage(progress, "auth_scaffold_origin_guard", deadline, () => installOriginGuard(context, [login.origin], { type: "none" }), profileId);
+		const page = await runStage(progress, "auth_scaffold_page_create", deadline, () => context.newPage(), profileId);
+		await runStage(progress, "auth_scaffold_login_load", deadline, () => page.goto(loginUrl, { waitUntil: "domcontentloaded", timeout }), profileId);
+		const discovered = await runStage(progress, "auth_scaffold_form_discovery", deadline, () => discoverLoginForm(page), profileId);
+		if (!success && !discovered.formSelector) {
+			throw new QaStatusError("QA_RUN_FAILED", "no login form was found; provide an explicit success condition for a form-less login page", 1, profileId);
+		}
+		const profile = {
+			description: args.description ?? `Browser QA form login (${profileId})`,
+			traits: ["auth:form"],
+			baseUrl,
+			allowedOrigins: [login.origin],
+			auth: {
+				type: "form",
+				loginUrl,
+				fields: discovered.fields.map((selector, index) => ({ selector, value: `__PI_QA_SECRET_${index + 1}__` })),
+				submitSelector: discovered.submitSelector,
+				success: success ?? { selector: discovered.formSelector, state: "hidden" },
+			},
+		};
+		const replacedEmptyTemplate = writeAuthScaffold(cwd, profileId, profile);
+		writeStatus({
+			status: "QA_AUTH_SCAFFOLD_CREATED",
+			file: CONFIG_RELATIVE,
+			profile: profileId,
+			action: "fill_credentials",
+			placeholderCount: discovered.fields.length,
+			replacedEmptyTemplate,
+		});
+	} catch (error) {
+		if (error instanceof QaStatusError) {
+			if (error.details?.timedOut) terminateRunnerDescendants();
+			throw error;
+		}
+		if (error instanceof RunnerStageTimeoutError) {
+			terminateRunnerDescendants();
+			throw new QaStatusError("QA_RUN_FAILED", "auth scaffold timed out; verify the public login page and retry", EXIT_RUNNER_TIMEOUT, profileId, { timedOut: true });
+		}
+		throw new QaStatusError("QA_RUN_FAILED", "auth scaffold failed; verify the public login page and retry", 1, profileId);
+	} finally {
+		if (context) await runCleanupStage(progress, "auth_scaffold_context_close", () => context.close()).catch(terminateOnCleanupTimeout);
+		if (browser) await runCleanupStage(progress, "auth_scaffold_browser_close", () => browser.close()).catch(terminateOnCleanupTimeout);
+		progress("auth_scaffold_finished");
+	}
+}
+
+function terminateOnCleanupTimeout(error) {
+	if (error instanceof RunnerStageTimeoutError) terminateRunnerDescendants();
+}
+
+function normalizeScaffoldUrl(raw, flag, expectedOrigin) {
+	if (typeof raw !== "string") throw new QaStatusError("QA_RUN_FAILED", `${flag} is required`, 1);
+	try {
+		const url = new URL(raw);
+		if (!isSecureScaffoldUrl(url) || url.username || url.password || (expectedOrigin && url.origin !== expectedOrigin)) throw new Error();
+		return url.href;
+	} catch {
+		throw new QaStatusError("QA_RUN_FAILED", `${flag} must use HTTPS or loopback HTTP without credentials${expectedOrigin ? " on the login origin" : ""}`, 1);
+	}
+}
+
+function isSecureScaffoldUrl(url) {
+	if (url.protocol === "https:") return true;
+	if (url.protocol !== "http:") return false;
+	const hostname = url.hostname.toLowerCase();
+	return hostname === "localhost"
+		|| hostname.endsWith(".localhost")
+		|| /^127(?:\.[0-9]{1,3}){3}$/.test(hostname)
+		|| hostname === "[::1]"
+		|| hostname === "::1";
+}
+
+function scaffoldSuccess(args) {
+	if (args.successUrl && args.successSelector) throw new QaStatusError("QA_RUN_FAILED", "use only one of --success-url or --success-selector", 1);
+	if (args.successState && !args.successSelector) throw new QaStatusError("QA_RUN_FAILED", "--success-state requires --success-selector", 1);
+	if (args.successUrl) return { url: boundedScaffoldString(args.successUrl, "--success-url") };
+	if (!args.successSelector) return undefined;
+	const state = args.successState ?? "visible";
+	if (validLocatorState(state) !== state) throw new QaStatusError("QA_RUN_FAILED", "--success-state is invalid", 1);
+	return { selector: boundedScaffoldString(args.successSelector, "--success-selector"), state };
+}
+
+function boundedScaffoldString(value, flag) {
+	if (typeof value !== "string" || !value.trim() || value.length > 1024 || /[\r\n\0]/.test(value)) {
+		throw new QaStatusError("QA_RUN_FAILED", `${flag} must be a non-empty single-line string no longer than 1024 characters`, 1);
+	}
+	return value;
+}
+
+async function discoverLoginForm(page) {
+	const discovered = await page.evaluate(() => {
+		const quoteAttribute = (value) => value.replace(/[\0-\x1f\x7f"\\]/g, (character) => {
+			if (character === "\0") return "�";
+			if (character === '"') return '\\"';
+			if (character === "\\") return "\\\\";
+			return `\\${character.codePointAt(0).toString(16)} `;
+		});
+		const unique = (selector) => {
+			try { return document.querySelectorAll(selector).length === 1; } catch { return false; }
+		};
+		const selectorFor = (element) => {
+			if (element.id) {
+				const selector = `[id="${quoteAttribute(element.id)}"]`;
+				if (unique(selector)) return selector;
+			}
+			for (const attribute of ["data-testid", "data-test", "name", "aria-label"]) {
+				const value = element.getAttribute(attribute);
+				if (!value) continue;
+				const selector = `${element.tagName.toLowerCase()}[${attribute}="${quoteAttribute(value)}"]`;
+				if (unique(selector)) return selector;
+			}
+			const parts = [];
+			let current = element;
+			while (current && current.nodeType === Node.ELEMENT_NODE && current !== document.documentElement) {
+				const tag = current.tagName.toLowerCase();
+				const siblings = [...current.parentElement.children].filter((item) => item.tagName === current.tagName);
+				parts.unshift(`${tag}:nth-of-type(${siblings.indexOf(current) + 1})`);
+				const selector = parts.join(" > ");
+				if (unique(selector)) return selector;
+				current = current.parentElement;
+			}
+			return parts.join(" > ");
+		};
+		const fillable = (element) => {
+			if (element.disabled || element.getAttribute("aria-hidden") === "true") return false;
+			if (element instanceof HTMLTextAreaElement) return true;
+			if (!(element instanceof HTMLInputElement)) return false;
+			return ["email", "password", "text", "tel", "url", "search", "number"].includes((element.type || "text").toLowerCase());
+		};
+		const visible = (element) => Boolean(element.getClientRects().length) && getComputedStyle(element).visibility !== "hidden";
+		const forms = [...document.querySelectorAll("form")];
+		const ranked = forms.map((form) => {
+			const fields = [...form.querySelectorAll("input, textarea")].filter((element) => fillable(element) && visible(element));
+			const passwordCount = fields.filter((element) => element instanceof HTMLInputElement && element.type === "password").length;
+			return { form, fields, score: passwordCount * 100 + fields.length };
+		}).filter((entry) => entry.fields.length > 0).sort((left, right) => right.score - left.score);
+		const selected = ranked[0];
+		const root = selected?.form ?? document;
+		const fields = selected?.fields ?? [...document.querySelectorAll("input, textarea")].filter((element) => fillable(element) && visible(element));
+		const submit = [...root.querySelectorAll('button[type="submit"], input[type="submit"], button:not([type])')].find(visible);
+		return {
+			fields: fields.map(selectorFor),
+			submitSelector: submit ? selectorFor(submit) : undefined,
+			formSelector: selected ? selectorFor(selected.form) : undefined,
+		};
+	});
+	if (!isObject(discovered) || !Array.isArray(discovered.fields) || discovered.fields.length === 0
+		|| discovered.fields.length > 10 || !discovered.fields.every(isBoundedSelector)
+		|| !isBoundedSelector(discovered.submitSelector)
+		|| (discovered.formSelector !== undefined && !isBoundedSelector(discovered.formSelector))) {
+		throw new Error("no supported login form with fillable fields and a submit control was found");
+	}
+	return discovered;
+}
+
+function isBoundedSelector(value) {
+	return typeof value === "string" && value.length > 0 && value.length <= 1024 && !/[\0-\x1f\x7f]/.test(value);
+}
+
+function readAuthConfig(cwd, required = false, allowPlaceholders = false) {
 	const candidate = path.join(cwd, CONFIG_RELATIVE);
 	if (!fs.existsSync(candidate)) {
 		if (!required) return { present: false, profiles: {} };
@@ -333,6 +523,18 @@ function readAuthConfig(cwd, required = false) {
 			{ action: "provide_credentials", templateCreated: false },
 		);
 	}
+	const profileValues = Object.values(value.profiles);
+	if (required && !allowPlaceholders && profileValues.length > 0
+		&& profileValues.every((profile) => authPlaceholderCount(profile) > 0)) {
+		const placeholderCount = profileValues.reduce((count, profile) => count + authPlaceholderCount(profile), 0);
+		throw new QaStatusError(
+			"QA_AUTH_UPDATE_REQUIRED",
+			`credentials are required; replace ${placeholderCount} generated credential placeholder${placeholderCount === 1 ? "" : "s"} in the auth config`,
+			EXIT_AUTH_UPDATE_REQUIRED,
+			undefined,
+			{ action: "fill_credentials", templateCreated: false, placeholderCount },
+		);
+	}
 	if (Object.keys(value.profiles).some((id) => !isSafeName(id))) {
 		throw new QaStatusError("QA_AUTH_UPDATE_REQUIRED", "auth profile ids may contain only letters, digits, dot, underscore, or dash", EXIT_AUTH_UPDATE_REQUIRED);
 	}
@@ -357,9 +559,28 @@ function selectProfile(profiles, requestedId) {
 	if (!isObject(profile.auth) || typeof profile.auth.type !== "string") {
 		throw new QaStatusError("QA_AUTH_UPDATE_REQUIRED", "profile auth configuration is missing or invalid", EXIT_AUTH_UPDATE_REQUIRED, requestedId);
 	}
+	const placeholderCount = authPlaceholderCount(profile);
+	if (placeholderCount > 0) {
+		throw new QaStatusError(
+			"QA_AUTH_UPDATE_REQUIRED",
+			`credentials are required; replace ${placeholderCount} generated credential placeholder${placeholderCount === 1 ? "" : "s"} in the auth config`,
+			EXIT_AUTH_UPDATE_REQUIRED,
+			requestedId,
+			{ action: "fill_credentials", templateCreated: false, placeholderCount },
+		);
+	}
 	return { id: requestedId, profile };
 }
 
+function authPlaceholderCount(profile) {
+	if (!isObject(profile) || !isObject(profile.auth) || profile.auth.type !== "form" || !Array.isArray(profile.auth.fields)) return 0;
+	return profile.auth.fields.filter((field) => (
+		isObject(field)
+		&& typeof field.value === "string"
+		&& AUTH_SECRET_PLACEHOLDER.test(field.value.trim())
+	)).length;
+}
+
 function createPublicProfile(rawBaseUrl) {
 	if (typeof rawBaseUrl !== "string") {
 		throw new QaStatusError("QA_RUN_FAILED", "--base-url is required when running without --profile", 1, "public");
@@ -436,6 +657,7 @@ function validateAuthConfiguration(cwd, auth, allowedOrigins, profileId) {
 			if (!Array.isArray(auth.fields) || auth.fields.length === 0 || auth.fields.some((field) => !isObject(field) || typeof field.selector !== "string" || !field.selector || typeof field.value !== "string" || !field.value)) throw authError(profileId, "form fields require non-empty selector/value strings");
 			if (typeof auth.submitSelector !== "string" || !auth.submitSelector) throw authError(profileId, "form submitSelector is missing");
 			if (!isObject(auth.success) || (typeof auth.success.url !== "string" && typeof auth.success.selector !== "string")) throw authError(profileId, "form success.url or success.selector is required");
+			if (auth.success.state !== undefined && (typeof auth.success.selector !== "string" || validLocatorState(auth.success.state) !== auth.success.state)) throw authError(profileId, "form success.state requires a selector and valid locator state");
 			break;
 		case "storageState":
 			if (typeof auth.path !== "string") throw authError(profileId, "storageState path is missing");
@@ -1211,7 +1433,9 @@ async function applyFormAuth(page, auth, allowedOrigins, profileId) {
 		}
 		await page.locator(auth.submitSelector).click();
 		if (isObject(auth.success) && typeof auth.success.url === "string") await page.waitForURL(auth.success.url, { timeout });
-		if (isObject(auth.success) && typeof auth.success.selector === "string") await page.locator(auth.success.selector).waitFor({ timeout });
+		if (isObject(auth.success) && typeof auth.success.selector === "string") {
+			await page.locator(auth.success.selector).waitFor({ timeout, state: validLocatorState(auth.success.state) });
+		}
 		if (!isObject(auth.success) || (typeof auth.success.url !== "string" && typeof auth.success.selector !== "string")) {
 			throw authError(profileId, "form success.url or success.selector is required");
 		}
@@ -1354,6 +1578,26 @@ function parseArgs(values) {
 	return result;
 }
 
+function parseAuthScaffoldArgs(values) {
+	const result = {};
+	for (let index = 0; index < values.length; index += 2) {
+		const flag = values[index];
+		const value = values[index + 1];
+		if (!flag?.startsWith("--") || value === undefined) throw new QaStatusError("QA_RUN_FAILED", `invalid argument: ${flag ?? "(missing)"}`, 1);
+		const key = flag.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+		if (!["profile", "loginUrl", "baseUrl", "description", "successUrl", "successSelector", "successState", "runnerTimeoutMs"].includes(key)) {
+			throw new QaStatusError("QA_RUN_FAILED", `unknown option: ${flag}`, 1);
+		}
+		if (result[key] !== undefined) throw new QaStatusError("QA_RUN_FAILED", `duplicate option: ${flag}`, 1);
+		result[key] = value;
+	}
+	if (result.description !== undefined) {
+		result.description = boundedScaffoldString(result.description, "--description");
+		if (result.description.length > 200) throw new QaStatusError("QA_RUN_FAILED", "--description must be no longer than 200 characters", 1);
+	}
+	return result;
+}
+
 function parseRunnerTimeout(value, profileId) {
 	if (value === undefined) return DEFAULT_RUNNER_TIMEOUT_MS;
 	const parsed = Number(value);
@@ -1764,6 +2008,67 @@ function createAuthTemplate(cwd) {
 	return true;
 }
 
+function writeAuthScaffold(cwd, profileId, profile) {
+	const initialTarget = assertAuthScaffoldWritable(cwd);
+	const content = `// Generated by the trusted browser QA runner from the public login form.\n// Replace only __PI_QA_SECRET_n__ values yourself; agents must not read or edit this file.\n${JSON.stringify({ profiles: { [profileId]: profile } }, null, 2)}\n`;
+	const temporaryFile = `${initialTarget.file}.scaffold-${randomUUID()}.tmp`;
+	try {
+		fs.writeFileSync(temporaryFile, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+		const descriptor = fs.openSync(temporaryFile, "r+");
+		try { fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); }
+
+		const currentTarget = assertAuthScaffoldWritable(cwd);
+		if (currentTarget.replacedEmptyTemplate !== initialTarget.replacedEmptyTemplate) {
+			throw new QaStatusError("QA_RUN_FAILED", "auth config changed during scaffold creation; no file was overwritten", 1);
+		}
+		if (currentTarget.replacedEmptyTemplate) {
+			fs.renameSync(temporaryFile, currentTarget.file);
+		} else {
+			try {
+				fs.linkSync(temporaryFile, currentTarget.file);
+			} catch (error) {
+				if (isAlreadyExistsError(error)) throw new QaStatusError("QA_RUN_FAILED", "auth config changed during scaffold creation; no file was overwritten", 1);
+				throw error;
+			}
+			fs.unlinkSync(temporaryFile);
+		}
+		return currentTarget.replacedEmptyTemplate;
+	} finally {
+		if (fs.existsSync(temporaryFile)) fs.unlinkSync(temporaryFile);
+	}
+}
+
+function assertAuthScaffoldWritable(cwd) {
+	const root = fs.realpathSync(cwd);
+	const directory = path.join(root, path.dirname(CONFIG_RELATIVE));
+	const file = path.join(root, CONFIG_RELATIVE);
+	assertInside(root, directory, "auth config directory");
+	if (!fs.existsSync(directory)) fs.mkdirSync(directory, { mode: 0o700 });
+	const directoryStat = fs.lstatSync(directory);
+	if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+		throw new QaStatusError("QA_RUN_FAILED", "auth config directory must be a real project-local directory", 1);
+	}
+
+	let replacedEmptyTemplate = false;
+	if (fs.existsSync(file)) {
+		const existing = resolveExistingPrivateFile(root, CONFIG_RELATIVE, "auth config");
+		const existingContent = fs.readFileSync(existing, "utf8");
+		const errors = [];
+		const value = parseJsonc(existingContent, errors, { allowTrailingComma: true });
+		if (errors.length > 0 || !isObject(value) || !isObject(value.profiles)) {
+			throw new QaStatusError("QA_RUN_FAILED", "existing auth config is invalid; scaffold creation will not overwrite it", 1);
+		}
+		if (Object.keys(value.profiles).length > 0) {
+			throw new QaStatusError("QA_RUN_FAILED", "existing auth config has profiles; scaffold creation will not overwrite it", 1);
+		}
+		if (existingContent !== AUTH_TEMPLATE) {
+			throw new QaStatusError("QA_RUN_FAILED", "existing empty auth config was not generated by the trusted runner; scaffold creation will not overwrite it", 1);
+		}
+		replacedEmptyTemplate = true;
+	}
+	return { file, replacedEmptyTemplate };
+}
+
 function isAlreadyExistsError(error) {
 	return error !== null && typeof error === "object" && error.code === "EEXIST";
 }

package/external/pi-tools-suite/src/default-pi-tools-suite-config.ts

@@ -341,7 +341,7 @@ export const DEFAULT_PI_TOOLS_SUITE_CONFIG_JSONC = String.raw`{
         "description": "Oracle: cross-provider flagship second opinion for hard or high-stakes uncertainty. Use sparingly to pressure-test architecture, plans, root-cause hypotheses, risk/security calls, or final recommendations when independent disagreement is valuable. Read-only; advise, do not edit.",
         "model": "openai-codex/gpt-5.6-sol",
         "fallbackModels": ["zai/glm-5.3"],
-        "thinking": "xhigh",
+        "thinking": "max",
         "tools": ["read", "grep", "bash"],
         "modelByParent": {
           "zai/*": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "1.0.28",
+  "version": "1.0.31",
   "description": "Pix: a workspace-first terminal UI for Pi with tabs, readable tool activity, voice input, and bundled agent tools.",
   "private": false,
   "repository": {