@junheep/gwt 0.3.0 → 0.5.0

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,8 +29,10 @@ 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 DEFAULT_CONFIG = { copyFiles: [], ports: [] }
+const SHELL_ENV_STATE = "GWT_SHELL_ENV_STATE"
+const DEFAULT_CONFIG = { copyFiles: [], ports: [], env: {} }
 const SKILL_DIRECTORIES = { claude: ".claude", codex: ".agents" }
 const SKILL_USAGE = `Usage: gwt skill install <${Object.keys(SKILL_DIRECTORIES).join("|")}> [--project] [--dry-run] [--yes]`
 
@@ -127,7 +131,7 @@ function validateRelativePath(value, field) {
 
 function validateConfig(parsed, label) {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new CliError(`${label} must contain an object`)
-  const allowed = new Set(["base", "worktreeDirectory", "copyFiles", "ports", "postCreate", "preRemove"])
+  const allowed = new Set(["base", "worktreeDirectory", "copyFiles", "ports", "env", "postCreate", "preRemove"])
   for (const key of Object.keys(parsed)) {
     if (!allowed.has(key)) throw new CliError(`${label} contains an unknown field: ${key}`)
   }
@@ -150,11 +154,33 @@ function validateConfig(parsed, label) {
   if (!Array.isArray(parsed.ports ?? [])) throw new CliError("ports must be an array")
   const ports = (parsed.ports ?? []).map((name, index) => {
     if (typeof name !== "string" || !ENV_NAME.test(name)) throw new CliError(`ports[${index}] is not a valid environment variable name`)
+    if (name.startsWith("GWT_")) throw new CliError(`ports[${index}] cannot use the reserved GWT_ prefix`)
     return name
   })
   if (new Set(ports).size !== ports.length) throw new CliError("ports cannot contain duplicates")
   if (ports.length > 100) throw new CliError("ports cannot contain more than 100 entries")
 
+  if (!parsed.env || typeof parsed.env !== "object" || Array.isArray(parsed.env)) {
+    if (parsed.env !== undefined) throw new CliError("env must be an object")
+  }
+  const envEntries = Object.entries(parsed.env ?? {})
+  if (envEntries.length > 100) throw new CliError("env cannot contain more than 100 entries")
+  const env = Object.fromEntries(envEntries.map(([name, value]) => {
+    if (!ENV_NAME.test(name)) throw new CliError(`env.${name} is not a valid environment variable name`)
+    if (name.startsWith("GWT_")) throw new CliError(`env.${name} cannot use the reserved GWT_ prefix`)
+    if (ports.includes(name)) throw new CliError(`env.${name} conflicts with a configured port`)
+    if (typeof value !== "string") throw new CliError(`env.${name} must be a string`)
+
+    const remainder = value.replace(/\$\{([^}]*)\}/g, (_, reference) => {
+      if (!ENV_NAME.test(reference) || !ports.includes(reference)) {
+        throw new CliError(`env.${name} references unknown port ${reference || "(empty)"}`)
+      }
+      return ""
+    })
+    if (remainder.includes("${")) throw new CliError(`env.${name} contains an invalid port reference`)
+    return [name, value]
+  }))
+
   for (const hook of ["postCreate", "preRemove"]) {
     if (parsed[hook] !== undefined) validateRelativePath(parsed[hook], hook)
   }
@@ -163,11 +189,24 @@ function validateConfig(parsed, label) {
     ...parsed,
     copyFiles,
     ports,
+    env,
   }
   if (worktreeDirectory !== undefined) config.worktreeDirectory = worktreeDirectory
   return config
 }
 
+function resolveConfiguredEnv(config, ports) {
+  return Object.fromEntries(Object.entries(config.env).map(([name, template]) => [
+    name,
+    template.replace(/\$\{([^}]*)\}/g, (_, reference) => {
+      if (!Object.hasOwn(ports, reference)) {
+        throw new CliError(`Cannot resolve env.${name}: this worktree has no assigned ${reference}`)
+      }
+      return String(ports[reference])
+    }),
+  ]))
+}
+
 function configHome() {
   return process.env.XDG_CONFIG_HOME || join(homedir(), ".config")
 }
@@ -312,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"))
@@ -346,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")
@@ -371,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) {
@@ -447,7 +508,7 @@ function hookPaths(configDocument, worktreePath) {
 
 function trustFingerprint(repository, configDocument, worktreePath) {
   const hooks = hookPaths(configDocument, worktreePath)
-  if (hooks.length === 0) return null
+  if (hooks.length === 0 && configDocument.value.ports.length === 0 && Object.keys(configDocument.value.env).length === 0) return null
   const hash = createHash("sha256")
   hash.update(repository.primaryPath)
   hash.update("\0")
@@ -517,20 +578,24 @@ async function ensureTrusted(repository, configDocument, worktreePath) {
   if (!fingerprint || isTrusted(repository, fingerprint)) return
 
   const hooks = hookPaths(configDocument, worktreePath)
-  console.error("This repository wants to run:")
+  console.error("This repository wants to configure your development environment:")
   for (const hook of hooks) console.error(`  ${hook.name}: ${hook.configuredPath}`)
+  for (const name of configDocument.value.ports) console.error(`  port: ${name}`)
+  for (const name of Object.keys(configDocument.value.env)) console.error(`  env: ${name}`)
   const allowed = await ask("Allow and remember? [y/N] ")
-  if (!allowed) throw new CliError("Project hooks are not trusted. Run 'gwt trust' to approve them")
+  if (!allowed) throw new CliError("Project configuration is not trusted. Run 'gwt trust' to approve it")
   saveTrust(repository, fingerprint)
 }
 
-function hookContext(repository, worktree, metadata) {
+function hookContext(repository, config, worktree, metadata) {
+  const ports = metadata?.ports ?? {}
   return {
     id: metadata?.id ?? "",
     path: canonical(worktree.path),
     primaryPath: repository.primaryPath,
     branch: worktree.branch ?? "",
-    ports: metadata?.ports ?? {},
+    ports,
+    environment: resolveConfiguredEnv(config, ports),
   }
 }
 
@@ -538,7 +603,7 @@ function runHook(name, repository, configDocument, worktree, metadata) {
   const configuredPath = configDocument.value[name]
   if (!configuredPath) return
   const hook = hookPaths(configDocument, canonical(worktree.path)).find((item) => item.name === name)
-  const context = hookContext(repository, worktree, metadata)
+  const context = hookContext(repository, configDocument.value, worktree, metadata)
   const env = {
     ...process.env,
     GWT_ID: context.id,
@@ -546,6 +611,7 @@ function runHook(name, repository, configDocument, worktree, metadata) {
     GWT_PRIMARY_PATH: context.primaryPath,
     GWT_BRANCH: context.branch,
     ...Object.fromEntries(Object.entries(context.ports).map(([key, value]) => [key, String(value)])),
+    ...context.environment,
   }
   console.log(`Running ${name}...`)
   const result = run(hook.path, [], {
@@ -580,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)
@@ -597,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)
   }
 
@@ -607,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
   }
 }
@@ -636,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) {
@@ -668,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)
@@ -694,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}`)
@@ -708,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) => {
@@ -717,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,
     }
   })
@@ -857,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))
 }
@@ -968,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) {
@@ -992,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",
@@ -1006,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")
@@ -1013,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"]
@@ -1023,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"]) {
@@ -1046,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]")
@@ -1062,21 +1422,21 @@ function commandTrust(args) {
   const configDocument = loadConfig(repository)
   if (!configDocument.requiresTrust) {
     console.log(configDocument.source === "user"
-      ? "User config hooks are trusted automatically"
+      ? "User configuration is trusted automatically"
       : "This repository has no project config to approve")
     return
   }
   const fingerprint = trustFingerprint(repository, configDocument, canonical(current.path))
   if (!fingerprint) {
-    console.log("This repository has no project hooks to approve")
+    console.log("This repository has no project configuration that requires approval")
     return
   }
   saveTrust(repository, fingerprint)
-  console.log(`Trusted project hooks for ${repository.primaryPath}`)
+  console.log(`Trusted project configuration for ${repository.primaryPath}`)
 }
 
 function configScaffold() {
-  return { copyFiles: [], ports: [] }
+  return { copyFiles: [], ports: [], env: {} }
 }
 
 function commandConfigCreate(args) {
@@ -1141,6 +1501,104 @@ function commandConfig(args) {
   throw new CliError("Usage: gwt config <create [--project]|show>")
 }
 
+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 { 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 { applied: false, reason: "not applied until 'gwt trust' approves this repository's configuration", values: {} }
+    }
+  }
+
+  const ports = Object.fromEntries(configDocument.value.ports.map((name) => {
+    if (!Object.hasOwn(metadata.ports ?? {}, name)) {
+      throw new CliError(`This worktree has no assigned ${name}; recreate it after changing ports`)
+    }
+    return [name, String(metadata.ports[name])]
+  }))
+  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() {
+  const encoded = process.env[SHELL_ENV_STATE]
+  if (!encoded) return { originals: {} }
+
+  try {
+    const parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"))
+    if (!parsed || typeof parsed.originals !== "object" || Array.isArray(parsed.originals)) throw new Error()
+    const originals = Object.fromEntries(Object.entries(parsed.originals).map(([name, original]) => {
+      if (!ENV_NAME.test(name) || name.startsWith("GWT_")) throw new Error()
+      if (!original || typeof original !== "object" || typeof original.present !== "boolean") throw new Error()
+      if (original.present && typeof original.value !== "string") throw new Error()
+      return [name, original.present ? { present: true, value: original.value } : { present: false }]
+    }))
+    return { originals }
+  } catch {
+    return { originals: {} }
+  }
+}
+
+function quoteZsh(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`
+}
+
+function shellEnvironmentCommands(environment) {
+  const previous = readShellEnvironmentState()
+  const names = new Set([...Object.keys(previous.originals), ...Object.keys(environment)])
+  const originals = {}
+  const commands = []
+
+  for (const name of names) {
+    const original = previous.originals[name] ?? (Object.hasOwn(process.env, name)
+      ? { present: true, value: process.env[name] }
+      : { present: false })
+
+    if (Object.hasOwn(environment, name)) {
+      originals[name] = original
+      commands.push(`export ${name}=${quoteZsh(environment[name])}`)
+    } else if (original.present) {
+      commands.push(`export ${name}=${quoteZsh(original.value)}`)
+    } else {
+      commands.push(`unset ${name}`)
+    }
+  }
+
+  if (Object.keys(originals).length === 0) {
+    commands.push(`unset ${SHELL_ENV_STATE}`)
+  } else {
+    const state = Buffer.from(JSON.stringify({ originals })).toString("base64url")
+    commands.push(`export ${SHELL_ENV_STATE}=${quoteZsh(state)}`)
+  }
+  return commands.join("\n")
+}
+
+function commandShellEnvironment(args) {
+  if (args.length !== 1 || args[0] !== "zsh") throw new CliError("Invalid shell environment request")
+  let environment = {}
+  try {
+    environment = configuredShellEnvironment()
+  } catch {}
+  console.log(shellEnvironmentCommands(environment))
+}
+
 function zshIntegration() {
   return `# gwt shell integration for zsh
 if command -v gwt >/dev/null 2>&1; then
@@ -1152,13 +1610,34 @@ if command -v gwt >/dev/null 2>&1; then
       builtin cd -- "$(<"$cd_file")" || exit_code=$?
     fi
     rm -f -- "$cd_file"
+    if [[ $exit_code -eq 0 ]]; then
+      _gwt_sync_env
+    fi
     return $exit_code
   }
 
+  _gwt_sync_env() {
+    local commands
+    commands="$(command gwt __shell_env zsh 2>/dev/null)" || return 0
+    [[ -n "$commands" ]] && eval "$commands"
+  }
+
   _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() {
@@ -1173,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'
@@ -1190,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]'
@@ -1218,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]' \
@@ -1252,6 +1747,12 @@ if command -v gwt >/dev/null 2>&1; then
   if (( $+functions[compdef] )); then
     compdef _gwt gwt
   fi
+
+  typeset -ga chpwd_functions
+  if (( ! \${chpwd_functions[(I)_gwt_sync_env]} )); then
+    chpwd_functions+=(_gwt_sync_env)
+  fi
+  _gwt_sync_env
 fi`
 }
 
@@ -1280,23 +1781,41 @@ stay accurate across versions.
 
 ## What the help does not make obvious
 
-- Hooks declared by a committed \`.gwt.json\` do not run 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.
+- Ports, environment variables, and hooks declared by a committed \`.gwt.json\`
+  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. Read them from \`gwt info\` instead of assuming
-  a project default; two worktrees of the same project never share a port.
+- Ports are assigned per worktree. With shell integration installed, assigned
+  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.
 `
 }
 
@@ -1380,18 +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)
-      if (metadata?.id) values.push(metadata.id)
-      if (worktree.branch) values.push(worktree.branch)
+      const id = metadata?.id ?? ""
+      const branch = worktree.branch ?? ""
+      if (id || branch) lines.push(`${id}\t${branch}`)
     }
-    console.log([...new Set(values)].join("\n"))
+    console.log(lines.join("\n"))
     return
   }
 
@@ -1416,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
 
@@ -1426,11 +1982,12 @@ 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
-  trust     Approve or revoke repository project hooks
+  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
   skill     Install the gwt skill for coding agents
@@ -1443,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
@@ -1451,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:
@@ -1472,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:
@@ -1527,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]
@@ -1544,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
@@ -1571,11 +2162,47 @@ 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`,
-    trust: `Approve or revoke hooks declared by the repository's .gwt.json.
+    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:
   gwt trust [--revoke]
@@ -1584,9 +2211,10 @@ Options:
   --revoke        Remove the stored approval for this repository.
   -h, --help      Show help for this command.
 
-Approval is tied to the configuration and hook contents, so changing either
-requires approval again. Hooks declared in user configuration are trusted
-automatically.
+Approval is required before repository-defined ports or environment variables
+are applied, or repository hooks run. It is tied to the configuration and hook
+contents, so changing either requires approval again. User configuration is
+trusted automatically.
 
 Examples:
   gwt trust
@@ -1653,7 +2281,8 @@ Options:
   -h, --help      Show help for this command.
 
 The integration lets gwt change the current shell's directory after new,
-switch, and removal of the current worktree. It also installs completion.
+switch, and removal of the current worktree. It also loads the worktree's
+assigned ports and configured environment, and installs completion.
 
 Example:
   gwt shell install zsh`,
@@ -1668,7 +2297,9 @@ Options:
   -h, --help      Show help for this command.
 
 The command adds one initialization line to ~/.zshrc, or to $ZDOTDIR/.zshrc
-when ZDOTDIR is set. Restart Zsh or source the file after installation.
+when ZDOTDIR is set. Restart Zsh or source the file after installation. The
+integration updates the environment when Zsh starts or changes directory and
+restores previous values after leaving a managed worktree.
 
 Examples:
   gwt shell install zsh
@@ -1736,15 +2367,18 @@ 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}`)
 }