@junheep/gwt 0.4.0 → 0.5.0

package/README.md

@@ -29,10 +29,11 @@ gwt shell install zsh
 ```
 
 The installer shows the line it will add to `~/.zshrc` and asks for
-confirmation. The integration also provides Zsh completion and automatically
-loads assigned ports and configured environment variables when Zsh enters a
-managed worktree. Previous values are restored when Zsh leaves it. Normal
-environment synchronization produces no output.
+confirmation. The integration also provides Zsh completion, which lists one
+row per worktree and completes worktree IDs as well as the branch names it
+shows. It also automatically loads assigned ports and configured environment
+variables when Zsh enters a managed worktree. Previous values are restored
+when Zsh leaves it. Normal environment synchronization produces no output.
 
 ## Coding agents
 
@@ -57,14 +58,10 @@ the installed skill is identical:
 `--project` writes into the primary worktree so the skill can be committed for
 the team.
 
-The skill covers what `gwt --help` does not: that gwt is preferred over native
-`git worktree`, that project hooks need `gwt trust`, that a failed setup is
-retried rather than recreated, that ports come from `gwt info`, and that
-removal is destructive. It points at `gwt <command> --help` for command
-details instead of repeating them, so it does not go stale as gwt changes.
-Reinstall after upgrading to pick up a revised skill; an unchanged file is
-reported as already installed, and a modified one is replaced only after
-confirmation.
+The skill covers what the help does not: when to prefer gwt over native
+`git worktree`, which commands are destructive, and the traps worth knowing. It
+points at `gwt <command> --help` for command details rather than repeating
+them. Reinstall after upgrading gwt to pick up a revised skill.
 
 ## Configuration
 
@@ -208,17 +205,21 @@ approval because they execute code:
 gwt trust
 ```
 
-Approval is invalidated when `.gwt.json` or either hook changes.
+Approval is invalidated when `.gwt.json` or either hook changes. `gwt remove`
+asks for approval only when `preRemove` is configured, because removal applies
+nothing else from the configuration.
 
 ## Commands
 
 ```sh
-gwt new [branch] [--base <ref>] [--no-hooks]
-gwt setup [id|branch|path] [--no-hooks]
+gwt new [branch] [--base <ref>] [--no-hooks] [--background]
+gwt setup [id|branch|path] [--no-hooks] [--background]
 gwt list
-gwt switch [primary|id|branch|path]
+gwt ls
+gwt switch [primary|id|branch|path] [--create]
 gwt info [primary|id|branch|path]
 gwt remove [id|branch|path] [--keep-branch|--discard] [--yes] [--no-hooks]
+gwt prune [--dry-run] [--yes]
 gwt trust [--revoke]
 gwt config create [--project]
 gwt config show
@@ -226,26 +227,25 @@ gwt shell install zsh [--dry-run] [--yes]
 gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
 ```
 
-Run `gwt --help` for the command overview, or `gwt <command> --help` for
-behavior, options, and practical examples. Nested commands such as
-`gwt config create --help` have their own help as well.
-
-`gwt new` creates `scratch/<id>` when no branch is provided. The immutable ID,
-assigned ports, and setup status are stored under the repository's common Git
-directory at `.git/gwt/worktrees/`.
-
-Setup failures retain the worktree and record the failure. Retry with
-`gwt setup <id>` or remove it explicitly.
-
-Run `gwt switch` without a target to open the interactive picker. Use the
-arrow keys, `j`/`k`, or Ctrl-n/Ctrl-p to move; press `/` to filter by branch,
-ID, or path. Enter switches to the selected worktree. Escape leaves filter
-mode or cancels the picker. `primary` is a reserved ID for the repository's
-primary worktree, so `gwt switch primary` returns to it from any linked
-worktree.
-
-`gwt remove` refuses dirty worktrees and first tries to delete the branch with
-`git branch -d`. If Git rejects safe deletion, an interactive terminal asks
-whether to force-delete the branch; non-interactive use keeps it and prints a
-command for deleting it later. `--discard --yes` explicitly allows dirty
-worktree removal and forced branch deletion.
+Run `gwt --help` for the overview, or `gwt <command> --help` for arguments,
+options, behavior, and examples. Nested commands such as `gwt config create
+--help` have their own help.
+
+What the listing does not show:
+
+- **Branches.** `gwt new` without an argument creates `scratch/<id>`. With one,
+  it reuses an existing local branch, or creates a branch tracking the remote
+  when the name exists on exactly one remote; `--base` always means "new
+  branch". `gwt switch <branch>` offers to create a worktree for a branch that
+  has none, and `--create` skips the question when running non-interactively.
+- **Background setup.** `--background` detaches `postCreate` and returns once
+  files are copied and ports assigned, logging to `.git/gwt/logs/<id>.log`.
+  `gwt list` reports the worktree as `running`, or `interrupted` if the process
+  disappears.
+- **Cleanup.** `gwt remove` also deletes the `scratch/<id>` branch a worktree
+  moved off, but only when the branch it moved to already contains those
+  commits. `gwt prune` clears records left by worktrees removed outside gwt,
+  including their scratch branches; it reports what it found and asks first.
+- **State.** IDs, assigned ports, and setup status live in
+  `.git/gwt/worktrees/`. `gwt info` prints a worktree's ports and environment
+  exactly as the shell integration loads them.

package/bin/gwt.mjs

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 
-import { spawnSync } from "node:child_process"
+import { spawn, spawnSync } from "node:child_process"
 import { createHash, randomBytes } from "node:crypto"
 import {
   accessSync,
   chmodSync,
+  closeSync,
   constants,
   copyFileSync,
   existsSync,
   mkdirSync,
+  openSync,
   readFileSync,
   readdirSync,
   realpathSync,
@@ -27,6 +29,7 @@ const PROJECT_CONFIG_FILE = ".gwt.json"
 const PORT_MIN = 20_000
 const PORT_MAX = 39_999
 const PICKER_ESCAPE_CODE_TIMEOUT_MS = 50
+const JOB_START_GRACE_MS = 30_000
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const SHELL_ENV_STATE = "GWT_SHELL_ENV_STATE"
 const DEFAULT_CONFIG = { copyFiles: [], ports: [], env: {} }
@@ -348,6 +351,25 @@ function metadataPath(repository, id) {
   return join(metadataDirectory(repository), `${id}.json`)
 }
 
+function setupLogPath(repository, id) {
+  return join(repository.commonDir, "gwt", "logs", `${id}.log`)
+}
+
+function jobStatus(metadata) {
+  if (metadata?.setup !== "running") return metadata?.setup
+  const pid = metadata.job?.pid
+  if (!pid) {
+    const startedAt = Date.parse(metadata.job?.startedAt ?? "")
+    return Number.isNaN(startedAt) || Date.now() - startedAt < JOB_START_GRACE_MS ? "running" : "interrupted"
+  }
+  try {
+    process.kill(pid, 0)
+    return "running"
+  } catch (error) {
+    return error.code === "EPERM" ? "running" : "interrupted"
+  }
+}
+
 function readJson(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"))
@@ -382,11 +404,11 @@ function metadataForWorktree(repository, worktree) {
 function currentWorktree(repository, cwd = process.cwd()) {
   const resolvedCwd = canonical(cwd)
   return repository.worktrees
-    .filter((worktree) => isInside(canonical(worktree.path), resolvedCwd))
+    .filter((worktree) => pathExists(worktree.path) && isInside(canonical(worktree.path), resolvedCwd))
     .sort((left, right) => right.path.length - left.path.length)[0] ?? null
 }
 
-function resolveWorktree(repository, selector, options = {}) {
+function findWorktree(repository, selector, options = {}) {
   if (!selector) {
     const current = currentWorktree(repository)
     if (!current) throw new CliError("The current directory is not inside a registered worktree")
@@ -407,10 +429,13 @@ function resolveWorktree(repository, selector, options = {}) {
   if (branchMatch) return branchMatch
 
   const candidatePath = resolve(options.cwd ?? process.cwd(), selector)
-  const pathMatch = repository.worktrees.find((worktree) => resolve(worktree.path) === candidatePath)
-  if (pathMatch) return pathMatch
+  return repository.worktrees.find((worktree) => resolve(worktree.path) === candidatePath) ?? null
+}
 
-  throw new CliError(`No worktree matches '${selector}'`)
+function resolveWorktree(repository, selector, options = {}) {
+  const worktree = findWorktree(repository, selector, options)
+  if (!worktree) throw new CliError(`No worktree matches '${selector}'`)
+  return worktree
 }
 
 function generateId(repository, config) {
@@ -621,6 +646,33 @@ function updateMetadata(repository, metadata, update) {
   return next
 }
 
+function startBackgroundHook(repository, metadata) {
+  const path = setupLogPath(repository, metadata.id)
+  mkdirSync(dirname(path), { recursive: true })
+
+  const started = updateMetadata(repository, metadata, {
+    setup: "running",
+    setupError: undefined,
+    job: { logPath: path, startedAt: new Date().toISOString() },
+  })
+
+  const descriptor = openSync(path, "w")
+  const environment = { ...process.env }
+  delete environment.GWT_CD_FILE
+  try {
+    const child = spawn(process.execPath, [import.meta.filename, "__run-hook", "postCreate", started.id], {
+      cwd: repository.primaryPath,
+      detached: true,
+      env: environment,
+      stdio: ["ignore", descriptor, descriptor],
+    })
+    child.unref()
+  } finally {
+    closeSync(descriptor)
+  }
+  return started
+}
+
 async function setupWorktree(repository, configDocument, worktree, options = {}) {
   if (resolve(worktree.path) === resolve(repository.primaryPath)) throw new CliError("The primary worktree does not need setup")
   const targetPath = canonical(worktree.path)
@@ -638,6 +690,7 @@ async function setupWorktree(repository, configDocument, worktree, options = {})
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     }
+    if (options.scratchBranch) metadata.scratchBranch = options.scratchBranch
     writeJson(metadataPath(repository, id), metadata)
   }
 
@@ -648,11 +701,12 @@ async function setupWorktree(repository, configDocument, worktree, options = {})
       return metadata
     }
     await ensureTrusted(repository, configDocument, targetPath)
+    if (options.background && configDocument.value.postCreate) return startBackgroundHook(repository, metadata)
     runHook("postCreate", repository, configDocument, worktree, metadata)
-    metadata = updateMetadata(repository, metadata, { setup: "complete" })
+    metadata = updateMetadata(repository, metadata, { setup: "complete", setupError: undefined, job: undefined })
     return metadata
   } catch (error) {
-    updateMetadata(repository, metadata, { setup: "failed", setupError: error.message })
+    updateMetadata(repository, metadata, { setup: "failed", setupError: error.message, job: undefined })
     throw error
   }
 }
@@ -677,11 +731,73 @@ function ensureLocalExclude(repository, directory) {
   writeFileSync(infoExclude, `${current}${separator}${pattern}\n`)
 }
 
-function validateBranch(branch, cwd) {
+function isBranchName(branch, cwd) {
   const result = git(["check-ref-format", "--branch", branch], cwd, { allowFailure: true })
-  if (result.status !== 0) throw new CliError(`Invalid branch name: ${branch}`)
-  const exists = git(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], cwd, { allowFailure: true }).status === 0
-  if (exists) throw new CliError(`Branch already exists: ${branch}`)
+  return result.status === 0 && result.stdout.trim() === branch
+}
+
+function validateBranchName(branch, cwd) {
+  if (!isBranchName(branch, cwd)) throw new CliError(`Invalid branch name: ${branch}`)
+}
+
+function branchState(repository, branch) {
+  const remoteNames = git(["remote"], repository.primaryPath).stdout.split("\n").filter(Boolean)
+  const localRef = `refs/heads/${branch}`
+  const remoteRefs = new Map(remoteNames.map((name) => [`refs/remotes/${name}/${branch}`, name]))
+  const raw = git([
+    "for-each-ref",
+    "--format=%(refname)%09%(worktreepath)",
+    localRef,
+    ...remoteRefs.keys(),
+  ], repository.primaryPath).stdout
+
+  let local = null
+  const remotes = []
+  for (const line of raw.split("\n").filter(Boolean)) {
+    const [refname, worktreePath = ""] = line.split("\t")
+    if (refname === localRef) local = { branch, worktreePath: worktreePath || null }
+    else if (remoteRefs.has(refname)) remotes.push(remoteRefs.get(refname))
+  }
+  return { local, remotes: [...new Set(remotes)].sort() }
+}
+
+function localBranch(repository, branch) {
+  return branchState(repository, branch).local
+}
+
+function resolveBranchTarget(repository, branch, explicitBase) {
+  validateBranchName(branch, repository.primaryPath)
+  const { local, remotes } = branchState(repository, branch)
+
+  if (local) {
+    if (local.worktreePath) {
+      throw new CliError(`Branch '${branch}' is already checked out at ${local.worktreePath}\nSwitch to it with: gwt switch ${branch}`)
+    }
+    if (explicitBase) {
+      throw new CliError(`Branch '${branch}' already exists, so --base would be ignored\nDrop --base to create a worktree for the existing branch`)
+    }
+    return { origin: "existing", branch }
+  }
+
+  if (explicitBase) return { origin: "new", branch }
+
+  if (remotes.length === 1) return { origin: "remote", branch, remoteRef: `${remotes[0]}/${branch}` }
+  if (remotes.length > 1) {
+    throw new CliError(`Branch '${branch}' exists on several remotes: ${remotes.join(", ")}\nChoose one with: gwt new ${branch} --base ${remotes[0]}/${branch}`)
+  }
+  return { origin: "new", branch }
+}
+
+function worktreeAddArguments(target, resolution, base) {
+  if (resolution.origin === "existing") return ["worktree", "add", target, resolution.branch]
+  if (resolution.origin === "remote") return ["worktree", "add", "--track", "-b", resolution.branch, target, resolution.remoteRef]
+  return ["worktree", "add", "-b", resolution.branch, target, base]
+}
+
+function branchSummary(resolution) {
+  if (resolution.origin === "existing") return `Branch: ${resolution.branch} (existing)`
+  if (resolution.origin === "remote") return `Branch: ${resolution.branch} (new, tracking ${resolution.remoteRef})`
+  return `Branch: ${resolution.branch}`
 }
 
 function writeCdDirective(path) {
@@ -709,25 +825,35 @@ function parseOptions(args, definitions = {}) {
   return { options, positionals }
 }
 
-async function commandNew(args) {
-  const { options, positionals } = parseOptions(args, { "--base": "value", "--no-hooks": "boolean" })
-  if (positionals.length > 1) throw new CliError("Usage: gwt new [branch] [--base <ref>] [--no-hooks]")
-  const repository = discoverRepository()
-  const configDocument = loadConfig(repository)
+async function createWorktree(repository, configDocument, options = {}) {
   ensureCopySources(repository, configDocument.value)
   const id = generateId(repository, configDocument.value)
-  const branch = positionals[0] ?? `scratch/${id}`
-  validateBranch(branch, repository.primaryPath)
-  const requestedBase = options.base ?? configDocument.value.base
-  const base = requestedBase
-    ? gitOutput(["rev-parse", "--verify", `${requestedBase}^{commit}`], repository.primaryPath)
-    : gitOutput(["rev-parse", "HEAD"], repository.primaryPath)
+  const scratch = !options.branch
+  const branch = options.branch ?? `scratch/${id}`
+
+  let resolution
+  if (scratch) {
+    validateBranchName(branch, repository.primaryPath)
+    if (localBranch(repository, branch)) throw new CliError(`Branch already exists: ${branch}`)
+    resolution = { origin: "new", branch }
+  } else {
+    resolution = resolveBranchTarget(repository, branch, options.base)
+  }
+
+  let base = null
+  if (resolution.origin === "new") {
+    const requestedBase = options.base ?? configDocument.value.base
+    base = requestedBase
+      ? gitOutput(["rev-parse", "--verify", `${requestedBase}^{commit}`], repository.primaryPath)
+      : gitOutput(["rev-parse", "HEAD"], repository.primaryPath)
+  }
+
   const target = join(resolveWorktreeDirectory(repository, configDocument.value), id)
   if (configDocument.value.worktreeDirectory) {
     ensureLocalExclude(repository, configDocument.value.worktreeDirectory)
   }
 
-  git(["worktree", "add", "-b", branch, target, base], repository.primaryPath, { stdio: "inherit" })
+  git(worktreeAddArguments(target, resolution, base), repository.primaryPath, { stdio: "inherit" })
   const targetPath = canonical(target)
   const refreshed = discoverRepository(repository.primaryPath)
   const worktree = refreshed.worktrees.find((item) => resolve(item.path) === targetPath)
@@ -735,12 +861,11 @@ async function commandNew(args) {
   try {
     const metadata = await setupWorktree(refreshed, configDocument, worktree, {
       id,
-      noHooks: options["no-hooks"],
+      noHooks: options.noHooks,
+      background: options.background,
+      scratchBranch: scratch ? branch : undefined,
     })
-    console.log(`Worktree ${metadata.id} is ready at ${targetPath}`)
-    console.log(`Branch: ${branch}`)
-    for (const [name, port] of Object.entries(metadata.ports)) console.log(`${name}: ${port}`)
-    writeCdDirective(targetPath)
+    return { metadata, targetPath, resolution }
   } catch (error) {
     console.error(`Setup failed; worktree retained at ${targetPath}`)
     console.error(`Retry: gwt setup ${id}`)
@@ -749,6 +874,35 @@ async function commandNew(args) {
   }
 }
 
+function reportWorktree({ metadata, targetPath, resolution }) {
+  console.log(`Worktree ${metadata.id} is ready at ${targetPath}`)
+  console.log(branchSummary(resolution))
+  for (const [name, port] of Object.entries(metadata.ports)) console.log(`${name}: ${port}`)
+  if (metadata.setup === "running") {
+    console.log(`Setup is running in the background; log: ${metadata.job.logPath}`)
+  }
+  writeCdDirective(targetPath)
+}
+
+async function commandNew(args) {
+  const { options, positionals } = parseOptions(args, {
+    "--base": "value",
+    "--no-hooks": "boolean",
+    "--background": "boolean",
+  })
+  if (positionals.length > 1) throw new CliError("Usage: gwt new [branch] [--base <ref>] [--no-hooks] [--background]")
+  if (options.background && options["no-hooks"]) throw new CliError("--background and --no-hooks cannot be combined")
+  const repository = discoverRepository()
+  const configDocument = loadConfig(repository)
+
+  reportWorktree(await createWorktree(repository, configDocument, {
+    branch: positionals[0],
+    base: options.base,
+    noHooks: options["no-hooks"],
+    background: options.background,
+  }))
+}
+
 function linkedWorktreeRows(repository, metadata = loadMetadata(repository)) {
   const current = currentWorktree(repository)
   return repository.worktrees.map((worktree, index) => {
@@ -758,7 +912,7 @@ function linkedWorktreeRows(repository, metadata = loadMetadata(repository)) {
       current: current && resolve(current.path) === resolve(worktree.path),
       id: item?.id ?? (index === 0 ? "primary" : "-"),
       branch: worktree.branch ?? "(detached)",
-      setup: item?.setup ?? (index === 0 ? "-" : "unmanaged"),
+      setup: jobStatus(item) ?? (index === 0 ? "-" : "unmanaged"),
       path: worktree.path,
     }
   })
@@ -898,10 +1052,40 @@ async function chooseWorktree(repository) {
   })
 }
 
+function looksLikePath(selector) {
+  return isAbsolute(selector) || selector.startsWith(".")
+}
+
+async function createMissingWorktree(repository, selector, force) {
+  const unmatched = new CliError(`No worktree matches '${selector}'`)
+  if (looksLikePath(selector) || !isBranchName(selector, repository.primaryPath)) throw unmatched
+
+  const resolution = resolveBranchTarget(repository, selector, undefined)
+  if (!force) {
+    const question = resolution.origin === "new"
+      ? `Branch '${selector}' does not exist. Create it and a worktree? [y/N] `
+      : `No worktree for branch '${selector}'. Create one? [y/N] `
+    if (!(await ask(question))) {
+      throw new CliError(`No worktree matches '${selector}'\nCreate one with: gwt new ${selector}`)
+    }
+  }
+
+  return createWorktree(repository, loadConfig(repository), { branch: selector })
+}
+
 async function commandSwitch(args) {
-  if (args.length > 1) throw new CliError("Usage: gwt switch [primary|id|branch|path]")
+  const { options, positionals } = parseOptions(args, { "--create": "boolean" })
+  if (positionals.length > 1) throw new CliError("Usage: gwt switch [primary|id|branch|path] [--create]")
   const repository = discoverRepository()
-  const worktree = args[0] ? resolveWorktree(repository, args[0]) : await chooseWorktree(repository)
+  const selector = positionals[0]
+  if (!selector && options.create) throw new CliError("--create requires a branch name")
+
+  const worktree = selector ? findWorktree(repository, selector) : await chooseWorktree(repository)
+  if (!worktree) {
+    reportWorktree(await createMissingWorktree(repository, selector, options.create))
+    return
+  }
+
   writeCdDirective(canonical(worktree.path))
   console.log(canonical(worktree.path))
 }
@@ -1009,23 +1193,45 @@ function commandInfo(args) {
   const worktree = resolveWorktree(repository, args[0])
   const metadata = metadataForWorktree(repository, worktree)
   console.log(`ID: ${metadata?.id ?? (resolve(worktree.path) === resolve(repository.primaryPath) ? "primary" : "unmanaged")}`)
-  console.log(`Path: ${canonical(worktree.path)}`)
+  console.log(`Path: ${pathExists(worktree.path) ? canonical(worktree.path) : resolve(worktree.path)}`)
   console.log(`Branch: ${worktree.branch ?? "(detached)"}`)
   console.log(`HEAD: ${worktree.head}`)
-  console.log(`Setup: ${metadata?.setup ?? "unmanaged"}`)
+  console.log(`Setup: ${jobStatus(metadata) ?? "unmanaged"}`)
   for (const [name, port] of Object.entries(metadata?.ports ?? {})) console.log(`${name}: ${port}`)
+  if (metadata) {
+    try {
+      const environment = worktreeEnvironment(repository, worktree)
+      for (const [name, value] of Object.entries(environment.values)) {
+        if (!Object.hasOwn(metadata.ports ?? {}, name)) console.log(`${name}: ${value}`)
+      }
+      if (environment.reason) console.log(`Environment: ${environment.reason}`)
+    } catch (error) {
+      console.log(`Environment: ${error.message}`)
+    }
+  }
   if (metadata?.setupError) console.log(`Setup error: ${metadata.setupError}`)
 }
 
 async function commandSetup(args) {
-  const { options, positionals } = parseOptions(args, { "--no-hooks": "boolean" })
-  if (positionals.length > 1) throw new CliError("Usage: gwt setup [id|branch|path] [--no-hooks]")
+  const { options, positionals } = parseOptions(args, { "--no-hooks": "boolean", "--background": "boolean" })
+  if (positionals.length > 1) throw new CliError("Usage: gwt setup [id|branch|path] [--no-hooks] [--background]")
+  if (options.background && options["no-hooks"]) throw new CliError("--background and --no-hooks cannot be combined")
   const repository = discoverRepository()
   const configDocument = loadConfig(repository)
   const worktree = resolveWorktree(repository, positionals[0])
-  const metadata = await setupWorktree(repository, configDocument, worktree, { noHooks: options["no-hooks"] })
+
+  const existing = metadataForWorktree(repository, worktree)
+  if (jobStatus(existing) === "running") {
+    throw new CliError(`Setup is already running for ${existing.id} (pid ${existing.job?.pid ?? "starting"})`)
+  }
+
+  const metadata = await setupWorktree(repository, configDocument, worktree, {
+    noHooks: options["no-hooks"],
+    background: options.background,
+  })
   console.log(`Setup ${metadata.setup}: ${metadata.id}`)
   for (const [name, port] of Object.entries(metadata.ports)) console.log(`${name}: ${port}`)
+  if (metadata.setup === "running") console.log(`Log: ${metadata.job.logPath}`)
 }
 
 async function confirmDiscard(worktree) {
@@ -1033,6 +1239,31 @@ async function confirmDiscard(worktree) {
   return ask("Type yes to continue [y/N] ")
 }
 
+function scratchBranchIsContained(repository, metadata, worktree) {
+  const scratch = metadata?.scratchBranch
+  if (!scratch || scratch === worktree.branch || !worktree.head) return false
+  return git(["merge-base", "--is-ancestor", scratch, worktree.head], repository.primaryPath, { allowFailure: true }).status === 0
+}
+
+async function removeScratchBranch(repository, metadata, worktree, options, contained) {
+  const scratch = metadata?.scratchBranch
+  if (!scratch || scratch === worktree.branch || options["keep-branch"]) return null
+  if (!localBranch(repository, scratch)) return null
+
+  const deleteArgs = ["branch", options.discard || contained ? "-D" : "-d", "--", scratch]
+  if (git(deleteArgs, repository.primaryPath, { allowFailure: true }).status === 0) {
+    return `Deleted scratch branch: ${scratch}`
+  }
+  if (!options.discard && !options.yes) {
+    console.log(`Scratch branch '${scratch}' could not be deleted safely.`)
+    if (await ask("Force-delete the scratch branch? [y/N] ")) {
+      git(["branch", "-D", "--", scratch], repository.primaryPath)
+      return `Deleted scratch branch: ${scratch}`
+    }
+  }
+  return `Kept scratch branch: ${scratch}\nDelete later: git branch -D -- ${scratch}`
+}
+
 async function commandRemove(args) {
   const { options, positionals } = parseOptions(args, {
     "--keep-branch": "boolean",
@@ -1047,6 +1278,10 @@ async function commandRemove(args) {
   if (resolve(worktree.path) === resolve(repository.primaryPath)) throw new CliError("The primary worktree cannot be removed")
   const targetPath = canonical(worktree.path)
   const metadata = metadataForWorktree(repository, worktree)
+  if (jobStatus(metadata) === "running" && !options.discard) {
+    throw new CliError(`Setup is still running for ${metadata.id} (pid ${metadata.job?.pid ?? "starting"})\nWait for it to finish, or force removal with --discard`)
+  }
+  const scratchContained = scratchBranchIsContained(repository, metadata, worktree)
   const dirty = git(["status", "--porcelain"], worktree.path).stdout.length > 0
   if (dirty && !options.discard) throw new CliError("Worktree has uncommitted changes; commit them or use --discard")
   if (options.discard && !options.yes && !(await confirmDiscard(worktree))) throw new CliError("Removal cancelled")
@@ -1054,8 +1289,10 @@ async function commandRemove(args) {
 
   if (!options["no-hooks"]) {
     const configDocument = loadConfig(repository)
-    await ensureTrusted(repository, configDocument, targetPath)
-    runHook("preRemove", repository, configDocument, worktree, metadata)
+    if (configDocument.value.preRemove) {
+      await ensureTrusted(repository, configDocument, targetPath)
+      runHook("preRemove", repository, configDocument, worktree, metadata)
+    }
   }
 
   const removeArgs = ["worktree", "remove"]
@@ -1064,6 +1301,10 @@ async function commandRemove(args) {
   console.log(`Removing worktree ${metadata?.id ?? targetPath}...`)
   git(removeArgs, repository.primaryPath)
   if (metadata?.metadataPath && existsSync(metadata.metadataPath)) unlinkSync(metadata.metadataPath)
+  if (metadata?.id) {
+    const log = setupLogPath(repository, metadata.id)
+    if (existsSync(log)) unlinkSync(log)
+  }
 
   let branchMessage = "No branch to delete"
   if (worktree.branch && !options["keep-branch"]) {
@@ -1087,9 +1328,87 @@ async function commandRemove(args) {
 
   console.log(`Removed worktree: ${metadata?.id ?? targetPath}`)
   console.log(branchMessage)
+  const scratchMessage = await removeScratchBranch(repository, metadata, worktree, options, scratchContained)
+  if (scratchMessage) console.log(scratchMessage)
   if (wasCurrent) writeCdDirective(repository.primaryPath)
 }
 
+function branchContainedElsewhere(repository, branch) {
+  const result = git([
+    "for-each-ref",
+    "--format=%(refname:short)",
+    "--contains",
+    `refs/heads/${branch}`,
+    "refs/heads",
+    "refs/remotes",
+  ], repository.primaryPath, { allowFailure: true })
+  if (result.status !== 0) return []
+  return result.stdout.split("\n").filter(Boolean).filter((reference) => reference !== branch)
+}
+
+function pruneCandidates(repository) {
+  const metadata = loadMetadata(repository)
+  const prunable = repository.worktrees.filter((worktree) => worktree.prunable)
+  const live = new Set(repository.worktrees
+    .filter((worktree) => !worktree.prunable)
+    .map((worktree) => resolve(worktree.path)))
+
+  const stale = []
+  const running = []
+  for (const item of metadata) {
+    if (live.has(resolve(item.path))) continue
+    if (jobStatus(item) === "running") running.push(item)
+    else stale.push(item)
+  }
+
+  const branches = stale
+    .filter((item) => item.scratchBranch && localBranch(repository, item.scratchBranch))
+    .map((item) => ({ branch: item.scratchBranch, containedIn: branchContainedElsewhere(repository, item.scratchBranch) }))
+
+  const retained = new Set(metadata.filter((item) => !stale.includes(item)).map((item) => item.id))
+  const directory = join(repository.commonDir, "gwt", "logs")
+  const logs = existsSync(directory)
+    ? readdirSync(directory)
+      .filter((name) => name.endsWith(".log") && !retained.has(basename(name, ".log")))
+      .map((name) => join(directory, name))
+    : []
+
+  return { prunable, stale, running, branches, logs }
+}
+
+async function commandPrune(args) {
+  const { options, positionals } = parseOptions(args, { "--dry-run": "boolean", "--yes": "boolean" })
+  if (positionals.length > 0) throw new CliError("Usage: gwt prune [--dry-run] [--yes]")
+  const repository = discoverRepository()
+  const { prunable, stale, running, branches, logs } = pruneCandidates(repository)
+  const removable = branches.filter((item) => item.containedIn.length > 0)
+  const retained = branches.filter((item) => item.containedIn.length === 0)
+  const total = prunable.length + stale.length + removable.length + logs.length
+
+  for (const item of retained) {
+    console.log(`Keeping scratch branch ${item.branch}: no other branch contains its commits`)
+  }
+  for (const item of running) console.log(`Keeping metadata ${item.id}: setup is still running`)
+  if (total === 0) {
+    console.log("Nothing to prune")
+    return
+  }
+
+  for (const worktree of prunable) console.log(`Worktree registration: ${worktree.path}`)
+  for (const item of stale) console.log(`Metadata: ${item.id}`)
+  for (const item of removable) console.log(`Scratch branch: ${item.branch} (contained in ${item.containedIn[0]})`)
+  for (const path of logs) console.log(`Setup log: ${basename(path)}`)
+
+  if (options["dry-run"]) return
+  if (!options.yes && !(await ask("Prune? [y/N] "))) throw new CliError("Prune cancelled")
+
+  if (prunable.length > 0) git(["worktree", "prune"], repository.primaryPath)
+  for (const item of stale) if (existsSync(item.metadataPath)) unlinkSync(item.metadataPath)
+  for (const item of removable) git(["branch", "-D", "--", item.branch], repository.primaryPath)
+  for (const path of logs) if (existsSync(path)) unlinkSync(path)
+  console.log(`Pruned ${total} item${total === 1 ? "" : "s"}`)
+}
+
 function commandTrust(args) {
   const { options, positionals } = parseOptions(args, { "--revoke": "boolean" })
   if (positionals.length > 0) throw new CliError("Usage: gwt trust [--revoke]")
@@ -1182,21 +1501,21 @@ function commandConfig(args) {
   throw new CliError("Usage: gwt config <create [--project]|show>")
 }
 
-function configuredShellEnvironment() {
-  const insideRepository = git(["rev-parse", "--is-inside-work-tree"], process.cwd(), { allowFailure: true })
-  if (insideRepository.status !== 0) return {}
-
-  const repository = discoverRepository()
-  const worktree = currentWorktree(repository)
-  if (!worktree || resolve(worktree.path) === resolve(repository.primaryPath)) return {}
+function worktreeEnvironment(repository, worktree) {
+  if (resolve(worktree.path) === resolve(repository.primaryPath)) return { applied: false, reason: null, values: {} }
 
   const metadata = metadataForWorktree(repository, worktree)
-  if (!metadata) return {}
+  if (!metadata) return { applied: false, reason: null, values: {} }
 
   const configDocument = loadConfig(repository)
+  if (configDocument.value.ports.length === 0 && Object.keys(configDocument.value.env).length === 0) {
+    return { applied: true, reason: null, values: {} }
+  }
   if (configDocument.requiresTrust) {
     const fingerprint = trustFingerprint(repository, configDocument, canonical(worktree.path))
-    if (!isTrusted(repository, fingerprint)) return {}
+    if (!isTrusted(repository, fingerprint)) {
+      return { applied: false, reason: "not applied until 'gwt trust' approves this repository's configuration", values: {} }
+    }
   }
 
   const ports = Object.fromEntries(configDocument.value.ports.map((name) => {
@@ -1205,7 +1524,17 @@ function configuredShellEnvironment() {
     }
     return [name, String(metadata.ports[name])]
   }))
-  return { ...ports, ...resolveConfiguredEnv(configDocument.value, metadata.ports ?? {}) }
+  return { applied: true, reason: null, values: { ...ports, ...resolveConfiguredEnv(configDocument.value, metadata.ports ?? {}) } }
+}
+
+function configuredShellEnvironment() {
+  const insideRepository = git(["rev-parse", "--is-inside-work-tree"], process.cwd(), { allowFailure: true })
+  if (insideRepository.status !== 0) return {}
+
+  const repository = discoverRepository()
+  const worktree = currentWorktree(repository)
+  if (!worktree) return {}
+  return worktreeEnvironment(repository, worktree).values
 }
 
 function readShellEnvironmentState() {
@@ -1294,9 +1623,21 @@ if command -v gwt >/dev/null 2>&1; then
   }
 
   _gwt_worktrees() {
-    local -a targets
-    targets=("\${(@f)$(command gwt __complete worktrees 2>/dev/null)}")
-    compadd -a targets
+    local -a lines selectors aliases
+    local line id branch tab=$'\\t'
+    lines=("\${(@f)$(command gwt __complete worktrees 2>/dev/null)}")
+    for line in $lines; do
+      id="\${line%%\${tab}*}"
+      branch="\${line#*\${tab}}"
+      if [[ -n "$branch" ]]; then
+        selectors+=("\${branch}:\${id:-unmanaged}")
+        [[ -n "$id" ]] && aliases+=("$id")
+      elif [[ -n "$id" ]]; then
+        selectors+=("\${id}:detached")
+      fi
+    done
+    (( $#selectors )) && _describe -t worktrees 'worktree' selectors
+    [[ -n "$PREFIX" ]] && (( $#aliases )) && compadd -n -a aliases
   }
 
   _gwt_refs() {
@@ -1311,9 +1652,11 @@ if command -v gwt >/dev/null 2>&1; then
       'new:Create and set up a worktree'
       'setup:Set up an existing worktree'
       'list:List worktrees'
+      'ls:List worktrees'
       'switch:Switch to a worktree'
       'info:Show worktree details'
       'remove:Remove a worktree'
+      'prune:Clean up records of removed worktrees'
       'trust:Approve project hooks'
       'config:Manage user and project configuration'
       'shell:Install shell integration'
@@ -1328,21 +1671,29 @@ if command -v gwt >/dev/null 2>&1; then
     case "$words[2]" in
       new)
         _arguments \
-          '2:branch name:' \
+          '2:branch name:_gwt_refs' \
           '--base[base Git revision]:revision:_gwt_refs' \
           '--no-hooks[skip project hooks]' \
+          '--background[run postCreate in the background]' \
           '(-h --help)'{-h,--help}'[show help]'
         ;;
       setup)
         _arguments \
           '2:worktree:_gwt_worktrees' \
           '--no-hooks[skip project hooks]' \
+          '--background[run postCreate in the background]' \
           '(-h --help)'{-h,--help}'[show help]'
         ;;
-      list)
+      list|ls)
         _arguments '(-h --help)'{-h,--help}'[show help]'
         ;;
-      switch|info)
+      switch)
+        _arguments \
+          '2:worktree:_gwt_worktrees' \
+          '--create[create a worktree for a branch without one]' \
+          '(-h --help)'{-h,--help}'[show help]'
+        ;;
+      info)
         _arguments \
           '2:worktree:_gwt_worktrees' \
           '(-h --help)'{-h,--help}'[show help]'
@@ -1356,6 +1707,12 @@ if command -v gwt >/dev/null 2>&1; then
           '--no-hooks[skip project hooks]' \
           '(-h --help)'{-h,--help}'[show help]'
         ;;
+      prune)
+        _arguments \
+          '--dry-run[show what would be pruned]' \
+          '--yes[skip the confirmation]' \
+          '(-h --help)'{-h,--help}'[show help]'
+        ;;
       trust)
         _arguments \
           '--revoke[revoke project hook approval]' \
@@ -1428,22 +1785,37 @@ stay accurate across versions.
   are not applied until the repository is approved with \`gwt trust\`. Approval
   is invalidated whenever the config or a hook changes, so a repository that
   worked before can start asking again.
+- \`gwt new <branch>\` reuses a branch that already exists locally, or creates one
+  tracking the remote when the name exists on exactly one remote, so there is no
+  need to check first. It refuses only a branch already checked out in another
+  worktree, which means switching to that worktree instead.
 - A failed setup keeps the worktree and records the failure. Retry it with
   \`gwt setup <id>\` rather than removing and recreating the worktree.
 - Ports are assigned per worktree. With shell integration installed, assigned
-  ports and configured environment variables load automatically. Read ports
-  from \`gwt info\` instead of assuming a project default; two worktrees of the
-  same project never share a port.
+  ports and configured environment variables load automatically. Read both from
+  \`gwt info\` instead of assuming a project default; two worktrees of the same
+  project never share a port.
+- \`--background\` returns before \`postCreate\` finishes, so the worktree is not
+  ready yet. Do not use it when the next step needs installed dependencies;
+  without it, setup is complete when the command returns.
 - \`gwt switch\` changes the shell's directory only when the shell integration is
   installed. Otherwise it just prints the path.
 - \`gwt switch\` with no target opens an interactive picker, so always pass an
   explicit target when running non-interactively.
+- \`gwt switch <branch>\` offers to create a worktree when that branch has none,
+  and needs \`--create\` to do it without asking. Only pass \`--create\` for a
+  branch name the user gave you: a typo silently becomes a new branch.
 
-## Removal is destructive
+## Removal and pruning are destructive
 
 \`gwt remove\` deletes the worktree and, by default, its branch. Confirm with the
 user before running it, and never pass \`--discard --yes\` on your own: together
 they discard uncommitted changes and force-delete an unmerged branch.
+
+\`gwt prune\` deletes records of worktrees that are already gone, including the
+scratch branch such a worktree recorded. Bare, it reports what it found and
+asks first, which is the only form to run unprompted; \`--yes\` skips that
+question, so leave it to the user.
 `
 }
 
@@ -1527,19 +1899,53 @@ async function commandShell(args) {
   throw new CliError("Usage: gwt shell install zsh [--dry-run] [--yes]")
 }
 
+function commandRunHook(args) {
+  if (args.length !== 2 || args[0] !== "postCreate") throw new CliError("Invalid hook request")
+  const repository = discoverRepository()
+  const metadata = loadMetadata(repository).find((item) => item.id === args[1])
+  if (!metadata) throw new CliError(`No worktree metadata for ${args[1]}`)
+  const worktree = repository.worktrees.find((item) => resolve(item.path) === resolve(metadata.path))
+  if (!worktree) throw new CliError(`Worktree ${metadata.id} is no longer registered with Git`)
+
+  const configDocument = loadConfig(repository)
+  const claimed = updateMetadata(repository, metadata, { job: { ...metadata.job, pid: process.pid } })
+  const finish = (update) => {
+    if (!existsSync(metadataPath(repository, claimed.id))) return
+    updateMetadata(repository, claimed, {
+      ...update,
+      job: { ...claimed.job, finishedAt: new Date().toISOString() },
+    })
+  }
+
+  try {
+    if (configDocument.requiresTrust) {
+      const fingerprint = trustFingerprint(repository, configDocument, canonical(worktree.path))
+      if (!isTrusted(repository, fingerprint)) {
+        throw new CliError("Project configuration is not trusted. Run 'gwt trust' to approve it")
+      }
+    }
+    runHook("postCreate", repository, configDocument, worktree, claimed)
+    finish({ setup: "complete", setupError: undefined })
+  } catch (error) {
+    finish({ setup: "failed", setupError: error.message })
+    throw error
+  }
+}
+
 function commandComplete(args) {
   if (args.length !== 1) throw new CliError("Invalid completion request")
 
   if (args[0] === "worktrees") {
     const repository = discoverRepository()
-    const values = ["primary"]
+    const lines = [`primary\t${repository.primary.branch ?? ""}`]
     for (const worktree of repository.worktrees) {
       if (resolve(worktree.path) === resolve(repository.primaryPath)) continue
       const metadata = metadataForWorktree(repository, worktree)
-      const selector = worktree.branch ?? metadata?.id
-      if (selector) values.push(selector)
+      const id = metadata?.id ?? ""
+      const branch = worktree.branch ?? ""
+      if (id || branch) lines.push(`${id}\t${branch}`)
     }
-    console.log(values.join("\n"))
+    console.log(lines.join("\n"))
     return
   }
 
@@ -1564,7 +1970,9 @@ function version() {
 }
 
 function help(command, subcommand) {
-  const topic = [command, subcommand].filter(Boolean).join(" ")
+  const aliases = { ls: "list" }
+  const requested = [command, subcommand].filter(Boolean).join(" ")
+  const topic = aliases[requested] ?? requested
   const texts = {
     "": `gwt ${version()} - lightweight native Git worktree workflows
 
@@ -1574,10 +1982,11 @@ Usage:
 Commands:
   new       Create and set up a worktree
   setup     Set up an existing worktree
-  list      List registered worktrees
+  list      List registered worktrees (alias: ls)
   switch    Switch the current shell to a worktree
-  info      Show worktree details and assigned ports
+  info      Show worktree details, ports, and environment
   remove    Safely remove a worktree and optionally its branch
+  prune     Clean up leftovers from worktrees that are already gone
   trust     Approve or revoke repository project configuration
   config    Create or inspect configuration
   shell     Install shell integration
@@ -1591,6 +2000,7 @@ Examples:
   gwt new feature/auth
   gwt switch
   gwt remove
+  gwt prune
   gwt config create
   gwt shell install zsh
   gwt skill install claude
@@ -1599,15 +2009,20 @@ Run 'gwt <command> --help' for command behavior and more examples.`,
     new: `Create a worktree, prepare its development environment, and switch to it.
 
 Usage:
-  gwt new [branch] [--base <ref>] [--no-hooks]
+  gwt new [branch] [--base <ref>] [--no-hooks] [--background]
 
 Arguments:
-  branch          New local branch name. Defaults to scratch/<id>.
+  branch          Branch to check out. An existing local branch is reused, a
+                  branch that exists on exactly one remote is checked out with
+                  tracking, and anything else is created. Defaults to
+                  scratch/<id>.
 
 Options:
-  --base <ref>    Start from this Git revision instead of the configured base
-                  or the primary worktree's current commit.
+  --base <ref>    Create the branch from this Git revision instead of the
+                  configured base or the primary worktree's current commit.
+                  Rejected when the branch already exists locally.
   --no-hooks      Copy files and allocate ports, but skip postCreate.
+  --background    Run postCreate detached so the shell returns immediately.
   -h, --help      Show help for this command.
 
 Behavior:
@@ -1620,53 +2035,68 @@ Behavior:
   repository hash is added to the directory name only when needed to avoid a
   name collision.
 
+  A branch already checked out in another worktree is refused; switch to that
+  worktree instead. With --background, files are copied, ports are assigned,
+  and project configuration is approved before postCreate is detached, so the
+  worktree is usable right away. 'gwt list' shows it as running until the
+  hook finishes, and its output is written to .git/gwt/logs/<id>.log.
+
 Examples:
   gwt new feature/auth
   gwt new
   gwt new hotfix/login --base origin/main
-  gwt new experiment --no-hooks`,
+  gwt new feature/from-remote
+  gwt new heavy-project --background`,
     setup: `Prepare an existing linked worktree using the active gwt configuration.
 
 Usage:
-  gwt setup [id|branch|path] [--no-hooks]
+  gwt setup [id|branch|path] [--no-hooks] [--background]
 
 Arguments:
   id|branch|path  Worktree to set up. Defaults to the current worktree.
 
 Options:
   --no-hooks      Copy files and allocate ports, but skip postCreate.
+  --background    Run postCreate detached so the shell returns immediately.
   -h, --help      Show help for this command.
 
 Behavior:
   Use this to adopt a worktree created with native 'git worktree add' or to
   retry a failed setup. Existing copied files and assigned ports are preserved.
+  Setup refuses to start while a background setup is already running for the
+  same worktree.
 
 Examples:
   gwt setup
   gwt setup feature/auth
-  gwt setup a1b2c3d4 --no-hooks`,
+  gwt setup a1b2c3d4 --no-hooks
+  gwt setup a1b2c3d4 --background`,
     list: `List Git worktrees together with gwt IDs and setup status.
 
 Usage:
   gwt list
+  gwt ls
 
 Options:
   -h, --help      Show help for this command.
 
 The current worktree is marked with '*'. Native worktrees that have not been
-set up by gwt are shown as unmanaged.
+set up by gwt are shown as unmanaged. 'gwt ls' is an alias for 'gwt list'.
 
-Example:
-  gwt list`,
+Examples:
+  gwt list
+  gwt ls`,
     switch: `Switch the current shell to another worktree.
 
 Usage:
-  gwt switch [primary|id|branch|path]
+  gwt switch [primary|id|branch|path] [--create]
 
 Arguments:
   selector        Worktree to switch to. Opens the picker when omitted.
 
 Options:
+  --create        Create the worktree without asking when the selector names a
+                  branch that has none.
   -h, --help      Show help for this command.
 
 Behavior:
@@ -1675,12 +2105,18 @@ Behavior:
   j/k, Ctrl-n/Ctrl-p, and '/' filtering. Shell integration must be installed for
   gwt to change the parent shell's directory; otherwise the path is only printed.
 
+  When nothing matches and the selector is a valid branch name, gwt offers to
+  create the worktree, reusing an existing branch or tracking a remote one just
+  like 'gwt new'. Selectors that look like paths are never treated as branch
+  names. Non-interactive use requires --create.
+
 Examples:
   gwt switch
   gwt switch primary
   gwt switch feature/auth
-  gwt switch a1b2c3d4`,
-    info: `Show a worktree's identity, Git state, setup status, and assigned ports.
+  gwt switch a1b2c3d4
+  gwt switch feature/review --create`,
+    info: `Show a worktree's identity, Git state, setup status, and environment.
 
 Usage:
   gwt info [primary|id|branch|path]
@@ -1692,6 +2128,13 @@ Arguments:
 Options:
   -h, --help      Show help for this command.
 
+Behavior:
+  Assigned ports and configured environment variables are listed exactly as an
+  integrated shell loads them, so what is printed is what the worktree gets.
+  Values declared by a repository .gwt.json are withheld until 'gwt trust'
+  approves the configuration, and a variable that cannot be resolved is
+  reported instead of failing the command.
+
 Examples:
   gwt info
   gwt info primary
@@ -1719,10 +2162,46 @@ Behavior:
   use keeps it. The primary worktree cannot be removed. Removing the current
   worktree returns an integrated shell to the primary worktree.
 
+  A worktree created without a branch argument records its scratch/<id> branch.
+  If the worktree later moved to another branch, removal deletes that leftover
+  scratch branch when the branch it moved to already contains every scratch
+  commit, so nothing is lost. A scratch branch holding commits that were left
+  behind is kept and reported instead. --keep-branch keeps it either way.
+  Removal refuses to run while a background setup is still in progress; use
+  --discard to force it. Configuration approval is requested only when
+  preRemove is configured, because removal applies nothing else from the
+  configuration.
+
 Examples:
   gwt remove
   gwt remove feature/auth --keep-branch
   gwt remove a1b2c3d4 --discard --yes`,
+    prune: `Clean up records left behind by worktrees that are already gone.
+
+Usage:
+  gwt prune [--dry-run] [--yes]
+
+Options:
+  --dry-run       Print what would be pruned without changing anything.
+  --yes           Prune without asking for confirmation.
+  -h, --help      Show help for this command.
+
+Behavior:
+  Prune reports what it would remove and asks before touching anything, so
+  running it with no options is safe. It unregisters worktrees whose directory
+  is gone, deletes metadata and setup logs with no worktree left, and deletes
+  the scratch branch such a worktree recorded.
+
+  A scratch branch is deleted only when another local or remote branch already
+  contains its commits, so nothing is lost. One holding commits no other branch
+  contains is reported and kept. Only branches gwt recorded at creation are
+  considered; other branches are never touched. Metadata for a setup that is
+  still running is left alone.
+
+Examples:
+  gwt prune
+  gwt prune --dry-run
+  gwt prune --yes`,
     trust: `Approve or revoke active configuration declared by the repository's .gwt.json.
 
 Usage:
@@ -1888,15 +2367,17 @@ async function main() {
   }
   if (command === "new") return commandNew(args)
   if (command === "setup") return commandSetup(args)
-  if (command === "list") return commandList(args)
+  if (command === "list" || command === "ls") return commandList(args)
   if (command === "switch") return commandSwitch(args)
   if (command === "info") return commandInfo(args)
   if (command === "remove") return commandRemove(args)
+  if (command === "prune") return commandPrune(args)
   if (command === "trust") return commandTrust(args)
   if (command === "config") return commandConfig(args)
   if (command === "shell") return commandShell(args)
   if (command === "skill") return commandSkill(args)
   if (command === "__complete") return commandComplete(args)
+  if (command === "__run-hook") return commandRunHook(args)
   if (command === "__shell_env") return commandShellEnvironment(args)
   throw new CliError(`Unknown command: ${command}`)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junheep/gwt",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Lightweight native Git worktree workflows",
   "license": "MIT",
   "author": "Junhee Park",