pantheon-opencode 1.6.0-beta.10 → 1.6.0-beta.12

package/src/pantheon/v2-model-overrides.ts

@@ -0,0 +1,275 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { KNOWN_AGENTS } from './model-agents.ts'
+import { capabilityEntry, normalizeCapability } from './presets.mjs'
+
+export interface V2ModelOverride {
+  model: string
+  variant?: 'low' | 'medium' | 'high'
+}
+
+export interface V2ModelConfiguration {
+  overrides: Record<string, V2ModelOverride>
+  legacyPresetMarker: { source: 'env' | 'file' } | null
+  warnings: string[]
+}
+
+export interface V2AgentDraftLike {
+  list(): readonly { id: string }[]
+  update(id: string, update: (agent: { id: string; model?: unknown }) => void): void
+}
+
+interface AgentModelLike {
+  id: string
+  model?: unknown
+}
+
+const MODEL_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._:+-]*$/
+const VARIANTS = new Set(['low', 'medium', 'high'])
+const KNOWN_AGENTS_SET = new Set<string>(KNOWN_AGENTS)
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isVariant(value: unknown): value is NonNullable<V2ModelOverride['variant']> {
+  return typeof value === 'string' && VARIANTS.has(value)
+}
+
+function isSupportedModelChoice(model: unknown, variant: unknown): model is string {
+  if (typeof model !== 'string' || !MODEL_REF_PATTERN.test(model)) return false
+  if (variant !== undefined && !isVariant(variant)) return false
+  try {
+    capabilityEntry(model)
+    if (variant === undefined) return true
+    const normalized = normalizeCapability(model, variant)
+    return !normalized.clamped && normalized.variant === variant
+  } catch {
+    return false
+  }
+}
+
+interface PresetFileSystem {
+  openSync(path: string, flags: number): number
+  fstatSync(fileDescriptor: number): { isFile(): boolean }
+  readFileSync(fileDescriptor: number, encoding: 'utf8'): string
+  closeSync(fileDescriptor: number): void
+}
+
+class SecurePresetReadUnavailableError extends Error {
+  constructor() {
+    super('Secure preset-file opening is unavailable')
+  }
+}
+
+class NonRegularPresetFileError extends Error {
+  constructor() {
+    super('Preset file is not a regular file')
+  }
+}
+
+/** Open and read a regular preset file without following links or blocking on special files. */
+export function readV2PresetFile(
+  candidate: string,
+  fileSystem: PresetFileSystem = { openSync, fstatSync, readFileSync, closeSync },
+): string {
+  const noFollowFlag = constants.O_NOFOLLOW
+  const nonBlockFlag = constants.O_NONBLOCK
+  if (
+    noFollowFlag === undefined ||
+    noFollowFlag === 0 ||
+    nonBlockFlag === undefined ||
+    nonBlockFlag === 0
+  ) {
+    throw new SecurePresetReadUnavailableError()
+  }
+
+  let fileDescriptor: number | undefined
+  try {
+    fileDescriptor = fileSystem.openSync(
+      candidate,
+      constants.O_RDONLY | noFollowFlag | nonBlockFlag,
+    )
+    if (!fileSystem.fstatSync(fileDescriptor).isFile()) {
+      throw new NonRegularPresetFileError()
+    }
+    return fileSystem.readFileSync(fileDescriptor, 'utf8')
+  } finally {
+    if (fileDescriptor !== undefined) fileSystem.closeSync(fileDescriptor)
+  }
+}
+
+function parseOverrides(
+  value: Record<string, unknown>,
+  warnings: string[],
+): Record<string, V2ModelOverride> {
+  const parsed: Record<string, V2ModelOverride> = {}
+  for (const [agent, raw] of Object.entries(value)) {
+    if (!KNOWN_AGENTS_SET.has(agent)) {
+      warnings.push(
+        'Override entry ignored for an unsupported agent; use one of the canonical Pantheon agent IDs.',
+      )
+      continue
+    }
+    const entry = isRecord(raw) ? raw : undefined
+    const hasVariant = entry !== undefined && Object.hasOwn(entry, 'variant')
+    const variant = hasVariant ? entry?.variant : entry?.reasoning_effort
+    const model = entry?.model
+    if (!entry || (hasVariant && !isVariant(variant)) || !isSupportedModelChoice(model, variant)) {
+      warnings.push(
+        'Override entry ignored because its model or variant is unsupported; choose a supported model and reasoning variant.',
+      )
+      continue
+    }
+    const override: V2ModelOverride = { model }
+    if (isVariant(variant)) override.variant = variant
+    parsed[agent] = override
+  }
+  return parsed
+}
+
+function defaultCandidates(): string[] {
+  return [join(process.cwd(), '.pantheon', 'active-preset.json')]
+}
+
+/** Read explicit per-agent project overrides only; global files are ignored in V2. */
+export function readV2ModelConfiguration(
+  options: { candidates?: string[]; env?: NodeJS.ProcessEnv } = {},
+): V2ModelConfiguration {
+  const env = options.env ?? process.env
+  const envName = env.PANTHEON_MODEL_PRESET?.trim()
+  let fileMarkerPresent = false
+  const configurations: Array<Record<string, V2ModelOverride>> = []
+  const warnings: string[] = []
+  let readFailure = false
+
+  // `model-command` passes project before global candidates. Keep this reader
+  // project-only even if a caller supplies the legacy candidate list.
+  const candidates = options.candidates ?? defaultCandidates()
+  for (const candidate of candidates.slice(0, 1)) {
+    let rawContent: string
+    try {
+      rawContent = readV2PresetFile(candidate)
+    } catch (error: unknown) {
+      if (error instanceof Error && 'code' in error && error.code === 'ENOENT') continue
+      if (error instanceof SecurePresetReadUnavailableError) {
+        warnings.push(
+          'V2 project model configuration cannot be read securely on this platform; manual overrides were not applied.',
+        )
+        readFailure = true
+        break
+      }
+      if (
+        error instanceof NonRegularPresetFileError ||
+        (error instanceof Error && 'code' in error && error.code === 'ELOOP')
+      ) {
+        warnings.push(
+          'V2 project model configuration is not a regular file or is a symlink; check active-preset.json. Manual overrides were not applied.',
+        )
+        readFailure = true
+        break
+      }
+      warnings.push(
+        'V2 project model configuration could not be read; check active-preset.json file access. Manual overrides were not applied.',
+      )
+      readFailure = true
+      break
+    }
+
+    let raw: unknown
+    try {
+      raw = JSON.parse(rawContent)
+    } catch {
+      warnings.push(
+        'V2 project model configuration contains invalid JSON; correct active-preset.json. Manual overrides were not applied.',
+      )
+      readFailure = true
+      break
+    }
+    if (!isRecord(raw)) {
+      warnings.push(
+        'V2 project model configuration has an invalid shape; correct active-preset.json. Manual overrides were not applied.',
+      )
+      readFailure = true
+      break
+    }
+
+    if (Object.hasOwn(raw, 'preset')) fileMarkerPresent = true
+    let parsedOverrides: Record<string, V2ModelOverride> = {}
+    if (Object.hasOwn(raw, 'overrides')) {
+      if (!isRecord(raw.overrides)) {
+        warnings.push(
+          'V2 project model configuration has an invalid `overrides` object; expected an object in active-preset.json. The project file contributed no manual overrides.',
+        )
+      } else if (Object.hasOwn(raw.overrides, 'agents')) {
+        if (!isRecord(raw.overrides.agents)) {
+          warnings.push(
+            'V2 project model configuration has invalid `overrides.agents`; expected an object in active-preset.json. The project file contributed no manual overrides.',
+          )
+        } else {
+          parsedOverrides = parseOverrides(raw.overrides.agents, warnings)
+        }
+      }
+    }
+    configurations.push(parsedOverrides)
+  }
+
+  const envMarkerPresent = typeof envName === 'string' && envName.length > 0
+  const markerSource: 'env' | 'file' | null = envMarkerPresent
+    ? 'env'
+    : fileMarkerPresent
+      ? 'file'
+      : null
+
+  // A project-file read/parse failure fails closed. Malformed entries warn but
+  // leave other valid project entries available.
+  const overrides: Record<string, V2ModelOverride> = {}
+  if (!readFailure) {
+    Object.assign(overrides, configurations[0] ?? {})
+  }
+  return {
+    overrides,
+    legacyPresetMarker: markerSource === null ? null : { source: markerSource },
+    warnings,
+  }
+}
+
+/** Apply one explicit model override while leaving all other agent settings intact. */
+export function applyV2ModelOverride(
+  agent: AgentModelLike,
+  override: V2ModelOverride | undefined,
+): void {
+  if (
+    !KNOWN_AGENTS_SET.has(agent.id) ||
+    !override ||
+    !isSupportedModelChoice(override.model, override.variant)
+  ) {
+    return
+  }
+  const separator = override.model.indexOf('/')
+  const previous = isRecord(agent.model) ? agent.model : {}
+  const model: Record<string, unknown> = {
+    ...previous,
+    providerID: override.model.slice(0, separator),
+    id: override.model.slice(separator + 1),
+  }
+  if (override.variant !== undefined) {
+    model.variant = override.variant
+  } else {
+    delete model.variant
+  }
+  agent.model = model
+}
+
+/** Apply explicit overrides to matching agents and leave unmatched host defaults untouched. */
+export function applyV2ModelOverrides(
+  draft: V2AgentDraftLike,
+  overrides: Record<string, V2ModelOverride>,
+): void {
+  for (const agent of draft.list()) {
+    if (!KNOWN_AGENTS_SET.has(agent.id)) continue
+    const override = overrides[agent.id]
+    if (!override) continue
+    draft.update(agent.id, (current) => applyV2ModelOverride(current, override))
+  }
+}

package/src/pantheon/v2-tools.ts

@@ -311,7 +311,7 @@ async function executeCost(
 
 // ─── pantheon_model ─────────────────────────────────────────────────────
 
-/** JSON Schema for `pantheon_model`, mirroring the V1 zod args. */
+/** JSON Schema for V2 `pantheon_model`; global scope is intentionally absent. */
 const MODEL_INPUT: Record<string, unknown> = {
   type: 'object',
   additionalProperties: false,
@@ -330,39 +330,27 @@ const MODEL_INPUT: Record<string, unknown> = {
     },
     scope: {
       type: 'string',
-      enum: ['project', 'global'],
-      description: 'Scope for active-preset.json (default project).',
-    },
-    confirm: {
-      type: 'boolean',
-      description: 'Explicit confirmation for a mutating operation; required for global changes.',
-    },
-    authorize_global: {
-      type: 'boolean',
-      description: 'Separate authorization for global configuration; not implied by confirm.',
+      enum: ['project'],
+      description: 'Project scope only; global overrides are not supported in V2.',
     },
   },
 }
 
-const WIZARD_UNAVAILABLE =
-  'the interactive wizard has no user in the V2 tool surface — pass action="status" to read ' +
-  'the current overrides, or pass agent and model explicitly for action="set"'
-
-/**
- * The V1 command falls back to an interactive readline prompt when invoked
- * with no arguments. A tool call has no user at the terminal, so that fallback
- * would block the call until it timed out. `ask` is injected to refuse
- * deterministically instead, which routes through the command's own
- * `wizard canceled` error path rather than forking its logic.
- */
-const modelCommand = createModelCommand({
-  ask: () => Promise.reject(new Error(WIZARD_UNAVAILABLE)),
-})
+const modelCommand = createModelCommand({ v2Mode: true })
 
 async function executeModel(
   input: Record<string, unknown>,
   context: unknown,
 ): Promise<V2ToolResult> {
+  if (input.scope !== undefined && input.scope !== 'project') {
+    return { output: 'Error: V2 pantheon_model is project-only; global scope is not supported.' }
+  }
+  if (Object.hasOwn(input, 'confirm') || Object.hasOwn(input, 'authorize_global')) {
+    return {
+      output:
+        'Error: V2 pantheon_model does not accept authorization flags; global authorization is not supported by this tool.',
+    }
+  }
   // The V1 tool validates its own args (zod) and reports failures as text.
   const output = await modelCommand.pantheon_model.execute(
     input as Parameters<typeof modelCommand.pantheon_model.execute>[0],
@@ -415,10 +403,11 @@ export function createV2ToolDefinitions(visionRuntime?: V2VisionRuntime): V2Tool
     {
       name: 'pantheon_model',
       description:
-        'Show, set, or reset per-agent model overrides in active-preset.json (project or global). ' +
-        'Overrides win over preset; env preset wins over file. Never writes .env or top-level ' +
-        'model/small_model. Pass action="status" to read the current overrides; unlike the V1 ' +
-        'command there is no interactive wizard on this surface.',
+        'Show, set, or reset explicit per-agent project-scoped model overrides in active-preset.json. ' +
+        'V2 ignores static preset names and PANTHEON_MODEL_PRESET; no wizard or implicit model ' +
+        'selection. Global overrides are not read or written in V2; future global support requires ' +
+        'separate explicit authorization. Pass action="status" to read project-scoped overrides. ' +
+        'Never writes .env or top-level model/small_model.',
       input: MODEL_INPUT,
       output: {},
       execute: executeModel,

package/src/pantheon/v2-unsupported.mjs

@@ -21,9 +21,8 @@
  * So a `.mjs` import is the only form all three consumers can share, and it
  * matches the existing `src/pantheon/presets.mjs` + `.d.mts` precedent.
  *
- * NOT the reason: type-stripping. `package.json#engines` admits
- * `^22.22.2 || ^24.15.0 || >=26.0.0`, every admitted version already defaults to
- * unflagged type-stripping (it landed in 22.18.0), so that argument would not
+ * NOT the reason: type-stripping. `package.json#engines` admits Node >=26.4.0,
+ * which defaults to unflagged type-stripping (it landed in 22.18.0), so that argument would not
  * have held on any admitted version. The live hazard is that `engines` is not
  * ENFORCED: a Node 20 user can run `doctor` and would get no type-stripping,
  * which is an argument for a runtime version check, not for this file's shape.

package/src/plugin-v2.ts

@@ -110,6 +110,7 @@ import {
   v2ResourceTarget,
 } from './pantheon/v2-delegation-enforce.ts'
 import { createV2ExecuteAfter, resolveV2SandboxConfig } from './pantheon/v2-execute-after.ts'
+import { applyV2ModelOverrides, readV2ModelConfiguration } from './pantheon/v2-model-overrides.ts'
 import { createV2ToolDefinitions, type V2ToolResult } from './pantheon/v2-tools.ts'
 import { V2_UNSUPPORTED_FEATURE_SEED } from './pantheon/v2-unsupported.mjs'
 import { buildV2VisionPromptContext, type V2VisionRuntime } from './pantheon/v2-vision.ts'
@@ -351,6 +352,18 @@ function transformAgents(draft: AgentDraft): void {
     markUnsupported('agent-transform-list')
     return
   }
+  try {
+    const modelConfiguration = readV2ModelConfiguration()
+    if (modelConfiguration.warnings.length > 0) {
+      // The V2 server PluginContext has no documented user-visible notification
+      // or logging channel; preserve the degradation for status diagnostics.
+      markUnsupported('agent-model-overrides')
+    }
+    applyV2ModelOverrides(draft, modelConfiguration.overrides)
+  } catch {
+    // Model configuration is optional. Preserve host models if it cannot be read.
+    markUnsupported('agent-model-overrides')
+  }
   try {
     for (const agent of agents) {
       draft.update(agent.id, (current) => {

package/src/plugins/tui/dist/tui-v2.js

@@ -477,7 +477,7 @@ function Sidebar(props) {
 		setProp(_el$, "width", "100%");
 		setProp(_el$, "padding", 1);
 		setProp(_el$2, "attributes", 1);
-		insert(_el$2, `Pantheon v1.6.0-beta.10`);
+		insert(_el$2, `Pantheon v1.6.0-beta.12`);
 		insertNode(_el$3, createTextNode(`OpenCode V2 · plugin TUI ativo`));
 		insert(_el$, createComponent(Show, {
 			get when() {
@@ -623,7 +623,7 @@ function HomeStatus(props) {
 	const muted = () => props.context.theme?.text?.muted ?? props.context.theme?.text?.base;
 	return (() => {
 		var _el$20 = createElement("text");
-		insert(_el$20, () => `Pantheon v1.6.0-beta.10${preset().name ? ` ⚡ ${preset().name}` : ""}`);
+		insert(_el$20, () => `Pantheon v1.6.0-beta.12${preset().name ? ` ⚡ ${preset().name}` : ""}`);
 		effect((_$p) => setProp(_el$20, "fg", muted(), _$p));
 		return _el$20;
 	})();

package/src/plugins/tui/dist/tui.js

@@ -167,7 +167,7 @@ async function detectVersion(api) {
 			if (ver) return ver;
 		}
 	} catch {}
-	return "1.6.0-beta.10";
+	return "1.6.0-beta.12";
 }
 /**
 * usage-bar — AI subscription usage gauge for the opencode TUI.

package/src/plugins/tui/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pantheon-tui",
-  "version": "1.6.0-beta.10",
+  "version": "1.6.0-beta.12",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pantheon-tui",
-      "version": "1.6.0-beta.10",
+      "version": "1.6.0-beta.12",
       "license": "MIT",
       "dependencies": {
         "@opencode-ai/plugin": "1.18.33",
@@ -20,7 +20,7 @@
         "tsdown": "0.23.0"
       },
       "engines": {
-        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+        "node": ">=26.4.0"
       },
       "peerDependencies": {
         "@opencode-ai/plugin": "1.18.33",

package/src/plugins/tui/package.json

@@ -1,11 +1,11 @@
 {
   "name": "pantheon-tui",
   "type": "module",
-  "version": "1.6.0-beta.10",
+  "version": "1.6.0-beta.12",
   "description": "Pantheon TUI plugin — V1 rich sidebar and usage gauges; native V2 status, session and delegation sidebar",
   "license": "MIT",
   "engines": {
-    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+    "node": ">=26.4.0"
   },
   "exports": {
     "./tui": "./dist/tui.js",

package/src/skills/artifact-management/SKILL.md

@@ -23,12 +23,16 @@ All ephemeral artifacts live in `.pantheon/memory-bank/.tmp/` — gitignored and
 │   ├── IMPL-phase1-hermes.md
 │   ├── IMPL-phase1-aphrodite.md
 │   └── REVIEW-<feature>.md
-├── _notes/                ← COMMITTED — permanent ADRs
+├── _notes/                ← permanent ADRs; Git tracking follows repository policy
 │   └── ADR-<topic>.md
 ├── 01-active-context.md
 └── 02-progress-log.md
 ```
 
+Memory Bank files are not automatically versioned or shared across clones.
+Check the repository's ignore/commit policy before relying on `_tasks/` records
+or other files being tracked; `_tasks/` may be Git-ignored.
+
 ---
 
 ## Artifact Types

package/src/skills/auto-continue/SKILL.md

@@ -55,16 +55,16 @@ Full-auto may continue only within a task and scope the user explicitly authoriz
 ## Implementation Pattern
 
 ```
-1. Create todos only for multi-step work; a one-step fix needs no todo ceremony
-2. Mark first todo in_progress
-3. Complete work → mark completed immediately
-4. Mark next todo in_progress → repeat
+1. Create a checklist only for multi-step work; a one-step fix needs no todo ceremony
+2. Use native todo operations only when a todo-write tool is visible in the active session; otherwise keep the checklist explicit in the conversation
+3. Mark work complete in the available checklist as soon as it is done
+4. Do not claim that the native todo list was updated when no todo-write tool is exposed
 5. Do NOT ask "should I continue?" between clear steps
 6. Stop at any applicable risk gate; do not require a plan/review gate for a low-risk edit
 7. After gate approval, resume with next todo
 ```
 
-**Never batch-complete todos.** Mark each completed as soon as done.
+**Never batch-complete checklist items.** Mark each completed as soon as done; do not imply a tool call occurred unless it did.
 
 ---
 
@@ -107,6 +107,14 @@ Only expand to full cooldown when hitting a mandatory gate.
 
 ## Timeout & Retry Enforcement
 
+Delegate through the root `subagent` tool observed in the Beta 10 runtime. `task()` is
+host/API terminology, not an assumed root tool; call shape and background support are
+runtime-dependent. Prefer synchronous dispatch unless the active schema exposes background
+and the host provides an observable completion notification. Do not assume `task_status`,
+`cancel_task`, or board-based tracking/recovery tools are available. When no completion
+mechanism is observable, use synchronous dispatch or state the limitation; do not claim
+that jobs are being tracked or recovered.
+
 When a delegated agent does not respond in time, enforce the timeout policy defined in
 `src/instructions/zeus-timeout-retry.instructions.md`.
 
@@ -128,7 +136,7 @@ When dispatching, set the expectation explicitly:
 
 ### Timeout Tracking Table
 
-Maintain a mental table of in-flight delegations:
+Maintain an in-context (not persistent/native) checklist of delegations when needed:
 
 | Agent | Started | Timeout | Status | Partial OK? |
 |-------|---------|---------|--------|-------------|

package/src/skills/memory-bank/SKILL.md

@@ -16,7 +16,7 @@ Complete guide to Pantheon memory bank — structure, rules, optimization, and m
 
 | System | Where | Owner | Lifetime | Purpose |
 |--------|-------|-------|----------|---------|
-| **Memory Bank** | `.pantheon/memory-bank/` | Team | Permanent, versioned | Project context: architecture, patterns, progress |
+| **Memory Bank** | `.pantheon/memory-bank/` | Team | Files persist in the working tree; Git tracking depends on repository ignore/commit policy | Project context: architecture, patterns, progress |
 | **VS Code `/memories/`** | `.vscode/` or workspace | Agent | Session/repo scoped | Atomic facts, conversation plans |
 
 ---
@@ -39,6 +39,10 @@ Complete guide to Pantheon memory bank — structure, rules, optimization, and m
     └── NOTE0001-topic.md   ← Architectural decisions, findings
 ```
 
+Memory Bank files are not automatically synchronized across clones. In
+particular, `_tasks/` records may be Git-ignored; only files tracked and
+committed under the repository's policy are shared through Git.
+
 ### File Update Frequency
 
 | File | Fill when | Update frequency |

package/src/skills/worktrees/SKILL.md

@@ -16,28 +16,47 @@ Use git worktrees to create isolated working directories for parallel or experim
 
 ## Setup
 
+Use this persistent external default for new worktrees:
+
+```text
+<project-parent>/.pantheon-worktrees/<exact-repository-directory-basename>/<task>
+```
+
+Resolve the project directory to an absolute path, then use its exact final
+directory basename as the repository component; spaces are valid and must not
+be normalized into a potentially colliding slug. For example, a project at
+`/home/user/My Project` uses
+`/home/user/.pantheon-worktrees/My Project/feature-name`. Replace
+`<task>` with a short descriptive task name. This keeps worktrees outside
+the project and reuses the same location across agent sessions.
+
 ```bash
-# Create a worktree
-git worktree add ../project-feature-x feature-x
+# Create a worktree at the recommended external location
+git worktree add "/home/user/.pantheon-worktrees/My Project/feature-name" task-branch
+
+# List worktrees and their absolute paths
+git worktree list --porcelain
 
-# List worktrees
-git worktree list
+# Only after the user explicitly authorizes removal, remove that exact worktree
+git worktree remove "/home/user/.pantheon-worktrees/My Project/feature-name"
 
-# Remove a worktree
-git worktree remove ../project-feature-x
+# Only after the user explicitly authorizes branch deletion
+git branch -d task-branch
 ```
 
 ## Workflow
 
-1. Create worktree: `git worktree add ../<name> <branch>`
+1. Resolve the project directory to an absolute path and create the worktree at `<project-parent>/.pantheon-worktrees/<exact-repository-directory-basename>/<task>`.
 2. Work in the worktree directory
 3. Commit and push from within the worktree
-4. Clean up: `git worktree remove ../<name>`
-5. Delete branch if no longer needed
+4. Leave the worktree and branch in place when the task is done unless the user explicitly authorizes removal or deletion.
+5. If authorized, remove only the exact worktree path above; delete its branch only with separate explicit user authorization.
 
 ## Rules
 - Never create worktrees inside the main project directory
-- Name worktrees descriptively: `../project-auth-refactor`
-- Remove worktrees when done (they consume disk space)
+- Use the persistent external default `<project-parent>/.pantheon-worktrees/<exact-repository-directory-basename>/<task>`
+- Use the exact repository directory basename (spaces included); do not normalize it into a lossy slug
+- Name worktrees descriptively, for example `feature-name` or `auth-refactor`
+- Never remove a worktree or delete a branch unless the user explicitly authorizes that action
 - Worktrees share the same git history — pushing from a worktree is the same as pushing from main
 - Escalate to @iris for branch management if unsure