@vzn/vx 0.0.646 → 0.0.648

package/src/graph/task-graph.ts

@@ -1,11 +1,15 @@
+import path from 'node:path'
 import type { ProjectConfig, TaskConfig, WorkspaceRules } from '../config.js'
 import {
   asTrees,
+  braceAlternatives,
+  GLOB_WILDCARDS,
   checkIgnoreSync,
   ignoreProbes,
   isLiteralPattern,
   literalPath,
   listedSync,
+  nearest,
   normalizeGlob,
   relPosix,
   splitNegations,
@@ -15,15 +19,14 @@ import {
   UserError,
   wholeIgnored,
   wholeSubtreePrefixes,
-} from '../util/index.js'
-import type { PackageGraph, ProjectEntry } from '../workspace/index.js'
-import {
   DependencySpecError,
   compileTaskPattern,
   isTaskPattern,
   parseDependencySpec,
   type DependencySpec,
-} from './dependency-spec.js'
+} from '../util/index.js'
+import type { PackageGraph, ProjectEntry } from '../workspace/index.js'
+import { isDefaultBuild } from './default-build.js'
 import { foldedDeps, isGroupTask } from './folds.js'
 import type { TaskOutcome } from './scheduler.js'
 
@@ -69,6 +72,11 @@ export interface TaskNode {
    * Absent when no plugin declares the stage.
    */
   keyParts?: ReadonlyArray<readonly [name: string, value: string]>
+  /**
+   * The platform this run runs it on, when it declares `exec.platforms`:
+   * set by placement, folded into its key.
+   */
+  platform?: string
   /**
    * Ids of upstream tasks whose declared outputs this task's outputs
    * overlap: this task ADDS to their trees (twenty's `build:individual`
@@ -102,9 +110,20 @@ export function taskId(project: string, task: string): string {
 // graph is where every reader of a task id looks for it.
 export { splitTaskId } from '../util/index.js'
 
-/** A keyed group: the default `build` (orchestrator/projects.ts), or a config's group with `inputs`. */
-function isKeyedGroup(task: TaskConfig): boolean {
-  return task.exec === undefined && task.inputs !== undefined
+/**
+ * A keyed group that is only its dependencies' own `name` (`^name`): the
+ * default `build` (orchestrator/projects.ts), or a config's of that shape.
+ * Only this shape walks last on a package cycle and is passed through.
+ * Any keyed group was: `ci` keyed on `lint` lost its edge and ran nothing,
+ * and `deploy` on `^build` walked `^deploy`.
+ */
+function isChainGroup(task: TaskConfig, name: string): boolean {
+  return (
+    task.exec === undefined &&
+    task.inputs !== undefined &&
+    task.dependsOn?.length === 1 &&
+    task.dependsOn[0] === `^${name}`
+  )
 }
 
 /**
@@ -283,11 +302,17 @@ export interface BuildGraphOptions {
   workspaceRoot?: string
   /** The workspace's `run.rules`; each is on unless set to `false`. */
   rules?: GraphRules | undefined
+  /**
+   * By project name, every project rooted inside its dir (absolute dirs).
+   * Given with `workspaceRoot` and unlocked (`vx lock`), an `inputs.files`
+   * entry rooted inside one is refused (`refuseNestedInputs`).
+   */
+  nestedProjects?: ReadonlyMap<string, ReadonlyArray<{ name: string; dir: string }>>
 }
 
 /**
  * `run.rules` as the graph applies them. `locked`: a run, which never
- * checks them; `vx lock` and `vx lock --check` do (owner, 2026-10-14).
+ * checks them; `vx lock` and `vx lock --check` do (2026-10-14).
  */
 export type GraphRules = WorkspaceRules & { readonly locked?: boolean }
 
@@ -298,9 +323,14 @@ export type GraphRules = WorkspaceRules & { readonly locked?: boolean }
  * legal without a holder — a preset spreads `^build` over projects whose
  * dependencies lack it.
  */
-export function undeclaredDepsError(taskId: string, name: string): UserError {
+export function undeclaredDepsError(
+  taskId: string,
+  name: string,
+  declared: Iterable<string>,
+): UserError {
+  const meant = nearest(name, declared)
   return new UserError(
-    `${taskId}: dependsOn ^${name} but no project in the workspace declares ${name}`,
+    `${taskId}: dependsOn ^${name} but no project in the workspace declares ${name}${meant === undefined ? '' : `. Did you mean ^${meant}?`}`,
     'VX_E_DEPENDS_ON',
   )
 }
@@ -335,7 +365,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
 
   function add(node: TaskNode): void {
     nodes.set(node.id, node)
-    if (isKeyedGroup(node.config) && onCycle(node.projectName)) deferred.push(node)
+    if (isChainGroup(node.config, node.taskName) && onCycle(node.projectName)) deferred.push(node)
     else if ((node.config.dependsOn?.length ?? 0) > 0) {
       stack.push({ node, entry: 0, added: false, pending: null, next: 0 })
     }
@@ -401,7 +431,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     return declared.has(name)
   }
 
-  // Package cycles, for the default `build` (`isKeyedGroup`): each project
+  // Package cycles, for the default `build` (`isChainGroup`): each project
   // on one maps to its strongly connected component, found on the first ask
   // (iterative Tarjan over `directDeps`, the order the `^name` walk reads).
   const component = new Map<string, number>()
@@ -466,7 +496,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       if (visit(frame, target, name, false)) {
         held = true
         const task = declaredTask(projects.get(target)!.config, name)!
-        if (isKeyedGroup(task) && onCycle(target)) {
+        if (isChainGroup(task, name) && onCycle(target)) {
           frontier.push(...packageGraph.directDeps(target))
         }
       } else frontier.push(...packageGraph.directDeps(target))
@@ -474,13 +504,14 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     return held
   }
 
-  // An edge by name (`build`, `pkg#build`) to a default build on a package
-  // cycle goes on past it as a `^build` walk does: that build folds nothing
-  // of the builds on its cycle, so `a#test` on `build` with `a` ↔ `b` both
-  // on the default build folded none of `b` and hit after `b` changed.
+  // An edge by name (`build`, `pkg#build`) or pattern (`bui*`, `^bui*`) to
+  // a default build on a package cycle goes on past it as a `^build` walk
+  // does: that build folds nothing of the builds on its cycle, so `a#test`
+  // on `build` with `a` ↔ `b` both on the default build folded none of `b`
+  // and hit after `b` changed.
   function goPast(frame: Frame, project: string, name: string, visited: Set<string>): void {
     const task = declaredTask(projects.get(project)!.config, name)!
-    if (isKeyedGroup(task) && onCycle(project)) walkHolders(frame, name, visited, project)
+    if (isChainGroup(task, name) && onCycle(project)) walkHolders(frame, name, visited, project)
   }
 
   // Resolves one `dependsOn` entry of `frame`'s task into its edges.
@@ -489,7 +520,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     const { id, projectName, taskName } = node
     let spec: DependencySpec
     try {
-      spec = parseDependencySpec(raw)
+      spec = parseDependencySpec(raw, 'dependsOn')
     } catch (err) {
       if (err instanceof DependencySpecError) {
         throw new UserError(`${id}: ${err.message}`, 'VX_E_DEPENDS_ON')
@@ -530,13 +561,20 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         for (const name of Object.keys(projects.get(projectName)!.config.tasks ?? {})) {
           if (name === taskName || !re.test(name)) continue
           visit(frame, projectName, name, false)
+          goPast(frame, projectName, name, new Set([projectName]))
         }
       } else {
         // Missing target is a hard error — the user typed a name that
         // doesn't resolve in this project.
         if (!visit(frame, projectName, spec.task, false)) {
+          const meant = nearest(
+            spec.task,
+            Object.keys(projects.get(projectName)!.config.tasks ?? {}).filter(
+              (n) => n !== taskName,
+            ),
+          )
           throw new UserError(
-            `${id}: dependsOn ${taskId(projectName, spec.task)} but no such task is declared`,
+            `${id}: dependsOn ${taskId(projectName, spec.task)} but no such task is declared${meant === undefined ? '' : `. Did you mean ${meant}?`}`,
             'VX_E_DEPENDS_ON',
           )
         }
@@ -576,7 +614,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       // task behind it would fold no upstream either.
       if (!packageGraph.edgeSource) {
         throw new UserError(
-          `${id}: ^${spec.task} needs project edges; add pnpm()/bun()/npm()/yarn() and install so its lockfile exists, or a plugin that returns \`deps\``,
+          `${id}: ${isDefaultBuild(node.config) ? `${projectName} declares no build, so it is the default build, whose ` : ''}^${spec.task} needs project edges; add pnpm()/bun()/npm()/yarn() and install so its lockfile exists, or a plugin that returns \`deps\``,
           'VX_E_DEPENDS_ON',
         )
       }
@@ -584,7 +622,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       if (!isTaskPattern(spec.task)) {
         const held = walkHolders(frame, spec.task, visited, projectName)
         if (!held && !declaredAnywhere(projectName, spec.task)) {
-          if (undeclaredDeps === undefined) throw undeclaredDepsError(id, spec.task)
+          if (undeclaredDeps === undefined) throw undeclaredDepsError(id, spec.task, declared ?? [])
           undeclaredDeps(id, spec.task)
         }
         return
@@ -600,7 +638,10 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
           re.test(n),
         )
         if (names.length > 0) {
-          for (const name of names) visit(frame, target, name, false)
+          for (const name of names) {
+            visit(frame, target, name, false)
+            goPast(frame, target, name, new Set([projectName, target]))
+          }
         } else {
           frontier.push(...packageGraph.directDeps(target))
         }
@@ -684,13 +725,13 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       }
       const to = taskId(target, name)
       if (sameCycle(x.projectName, target)) {
-        if (!isKeyedGroup(task) && !nodes.has(to)) {
+        if (!isChainGroup(task, name) && !nodes.has(to)) {
           visit(null, target, name, false)
           drain()
           expanded = true
           reaching = null
         }
-        if (isKeyedGroup(task) || (reaching ??= reachingTo(nodes, x.id)).has(to)) {
+        if (isChainGroup(task, name) || (reaching ??= reachingTo(nodes, x.id)).has(to)) {
           frontier.push(...packageGraph.directDeps(target))
           continue
         }
@@ -700,7 +741,8 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       visit(frame, target, name, false)
       drain()
       if (nodes.size !== size) reaching = null
-      if (isKeyedGroup(task) && onCycle(target)) frontier.push(...packageGraph.directDeps(target))
+      if (isChainGroup(task, name) && onCycle(target))
+        frontier.push(...packageGraph.directDeps(target))
     }
     x.deps = [...new Set(x.deps)].sort()
   }
@@ -718,9 +760,50 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
   }
 
   checkGraph(nodes, options.workspaceRoot, options.rules)
+  if (options.nestedProjects !== undefined && options.rules?.locked !== true)
+    refuseNestedInputs(nodes, options.nestedProjects, options.workspaceRoot)
   return nodes
 }
 
+/**
+ * Refuse an `inputs.files` entry rooted inside a project nested in the
+ * task's own: every file it can match belongs to that project, which a
+ * project's globs never reach, so the entry keys nothing and an edit there
+ * hits (a `dist/**` over a build output holding its own config was dropped
+ * from the key in silence). Judged by each brace alternative's fixed
+ * prefix: `**` or a sibling reaches past the nested dir and is fine.
+ */
+function refuseNestedInputs(
+  nodes: ReadonlyMap<string, TaskNode>,
+  nested: ReadonlyMap<string, ReadonlyArray<{ name: string; dir: string }>>,
+  workspaceRoot: string | undefined,
+): void {
+  for (const n of nodes.values()) {
+    const inner = nested.get(n.projectName)
+    if (inner === undefined || inner.length === 0 || isGroupTask(n)) continue
+    for (const g of positives(n.config.inputs?.files)) {
+      for (const alt of braceAlternatives(g)) {
+        const prefix = staticPrefix(alt)
+        if (prefix === '.' || prefix === '') continue
+        const abs = path.join(n.projectDir, prefix)
+        const hit = inner.find((p) => abs === p.dir || abs.startsWith(p.dir + path.sep))
+        if (hit === undefined) continue
+        const rel =
+          workspaceRoot === undefined
+            ? hit.name
+            : relPosix(workspaceRoot, path.join(n.projectDir, alt.replace(/^\.\//, '')))
+        throw new UserError(
+          `${n.id} reads ${JSON.stringify(g)} in inputs.files, which lies inside the project ` +
+            `${hit.name}: a project's globs never reach another project's files, so it keys ` +
+            `nothing. Depend on a ${hit.name} task, or name the files in inputs.workspaceFiles ` +
+            `(${JSON.stringify(rel)}).`,
+          'VX_E_NESTED_INPUT',
+        )
+      }
+    }
+  }
+}
+
 /** The ids of the tasks that reach `target` along `deps`, itself included. */
 function reachingTo(nodes: Map<string, TaskNode>, target: string): Set<string> {
   const dependants = new Map<string, string[]>()
@@ -913,6 +996,16 @@ export function excludeDependencies(
  * 445). One rule, one place: the copy is gone.
  */
 export function outputsOverlap(rawA: string, rawB: string): boolean {
+  // Each brace alternative on its own: the checks below read a brace as
+  // one opaque segment, so `build/{a,b}.js` met `build/*.js`, and
+  // `dist/{esm,cjs}/**` met `**/*.js`, nowhere (fuzz, 2026-10-25).
+  const as = braceAlternatives(rawA)
+  const bs = braceAlternatives(rawB)
+  if (as.length === 1 && bs.length === 1) return overlapOne(rawA, rawB)
+  return as.some((a) => bs.some((b) => overlapOne(a, b)))
+}
+
+function overlapOne(rawA: string, rawB: string): boolean {
   // A built path proves overlap only between globs as written: a literal's
   // `/**` twin reads it as a directory, and `dist/types.d.ts` met
   // `dist/**/*.js` at `dist/types.d.ts/x.js`, a file no one can write.
@@ -966,7 +1059,7 @@ function witnessed(a: string, b: string): boolean {
   }
   // Each glob filled in whole, every wildcard a name and `**` one level or
   // none: `**/dist/**` beside `**/*` meets at `x/dist/x`, a path neither
-  // last segment builds (solid, M 2026-10-15).
+  // last segment builds (solid, 2026-10-15).
   for (const glob of [a, b]) {
     const segs = glob.split('/')
     if (segs.some((s) => /[[\]{}()!+@]/.test(s))) continue
@@ -977,7 +1070,97 @@ function witnessed(a: string, b: string): boolean {
       if (candidate !== '' && ga.match(candidate) && gb.match(candidate)) return true
     }
   }
-  return false
+  const met = unified(a.split('/'), b.split('/'))
+  return met !== null && met !== '' && ga.match(met) && gb.match(met)
+}
+
+/**
+ * A path both globs take, built segment by segment, each a name both
+ * segments take, `**` matching a segment of the other or none: `out/**`
+ * beside every `.d.ts` in a `types` directory one level down meets at
+ * `out/types/x.d.ts`, and `*` beside `[ab]` at `a`, paths neither glob
+ * filled alone builds (fuzz, 2026-10-25). Null when none is found; a find
+ * is checked whole after.
+ */
+function unified(sa: readonly string[], sb: readonly string[]): string | null {
+  // A `!` opening a class is the class's; anywhere else, an extglob.
+  if ([...sa, ...sb].some((x) => /[{}()!+@]/.test(x.replaceAll('[!', '[')))) return null
+  const memo = new Map<string, string | null>()
+  const join = (name: string, rest: string): string => (rest === '' ? name : `${name}/${rest}`)
+  const walk = (i: number, j: number): string | null => {
+    const key = `${i},${j}`
+    if (memo.has(key)) return memo.get(key)!
+    memo.set(key, null)
+    let out: string | null = null
+    if (i === sa.length && j === sb.length) out = ''
+    else if (sa[i] === '**' || sb[j] === '**') {
+      // A last `**` takes one segment at least: `out/**` is not `out`.
+      const lastA = sa[i] === '**' && i === sa.length - 1
+      const lastB = sb[j] === '**' && j === sb.length - 1
+      const [wide, x, y, other] = sa[i] === '**' ? [sa, i, j, sb] : [sb, j, i, sa]
+      if (lastA && lastB) out = 'x'
+      if (out === null && sa[i] === '**' && !lastA) out = walk(i + 1, j)
+      if (out === null && sb[j] === '**' && !lastB) out = walk(i, j + 1)
+      if (out === null && y < other.length && other[y] !== '**') {
+        const name = segmentMeet('*', other[y]!)
+        // Having taken one, it may take more or stop.
+        const rest =
+          name === null
+            ? null
+            : wide === sa
+              ? (walk(x, y + 1) ?? walk(x + 1, y + 1))
+              : (walk(y + 1, x) ?? walk(y + 1, x + 1))
+        if (name !== null && rest !== null) out = join(name, rest)
+      }
+    } else if (i < sa.length && j < sb.length) {
+      const name = segmentMeet(sa[i]!, sb[j]!)
+      const rest = name === null ? null : walk(i + 1, j + 1)
+      if (name !== null && rest !== null) out = join(name, rest)
+    }
+    memo.set(key, out)
+    return out
+  }
+  return walk(0, 0)
+}
+
+/** A name both segments take, from each filled in and the one's head joined to the other's tail. */
+function segmentMeet(x: string, y: string): string | null {
+  const fill = (seg: string, star: string): string =>
+    seg
+      .replace(/\*+/g, star)
+      .replace(/\?/g, 'x')
+      // A negated class takes a name it does not list: `[!a]` is not `a`.
+      .replace(/\[([!^]?)(.)([^\]]*)\]/g, (_, not: string, first: string, more: string) =>
+        not === ''
+          ? first
+          : (['x', 'y', 'z', '0', '_'].find((c) => !`${first}${more}`.includes(c)) ?? first),
+      )
+  const head = (seg: string): string => {
+    const at = seg.search(GLOB_WILDCARDS)
+    return at === -1 ? seg : seg.slice(0, at)
+  }
+  const tail = (seg: string): string => {
+    let at = seg.length
+    while (at > 0 && !GLOB_WILDCARDS.test(seg[at - 1]!)) at--
+    return seg.slice(at)
+  }
+  const gx = new Bun.Glob(x)
+  const gy = new Bun.Glob(y)
+  for (const c of [
+    fill(x, 'x'),
+    fill(y, 'x'),
+    fill(x, ''),
+    fill(y, ''),
+    head(x) + tail(y),
+    head(y) + tail(x),
+    // Each name a class lists, the other's class filled: `[ab]` beside `[!a]` meets at `b`.
+    ...[x, y].flatMap((seg) => {
+      const listed = /\[([^!^\]][^\]]*)\]/.exec(seg)?.[1] ?? ''
+      return listed.split('').map((ch) => fill(seg.replace(/\[[^!^\]][^\]]*\]/, ch), 'x'))
+    }),
+  ])
+    if (c !== '' && gx.match(c) && gy.match(c)) return c
+  return null
 }
 
 /**
@@ -988,7 +1171,16 @@ function witnessed(a: string, b: string): boolean {
  * back its own stale copy of the narrow one's output under a green run
  * (item 941).
  */
+const WHOLE_ROOT = new Set(['**', '**/*'])
+
 function covers(tree: string, glob: string): boolean {
+  // The root's own tree has no directory to name: `**` beside a `!` that
+  // spared the config cleaned every source under it, and the refusal of
+  // a task's own sources as outputs never fired.
+  if (WHOLE_ROOT.has(normalizeGlob(tree))) {
+    const g = normalizeGlob(glob)
+    return !g.startsWith('!') && !g.startsWith('/') && !g.split('/').includes('..')
+  }
   const dir = wholeSubtreePrefixes([tree])?.[0]
   if (dir === undefined) return false
   const prefix = staticPrefix(glob)
@@ -1317,7 +1509,8 @@ function overlapCandidates<T>(
   for (let i = 0; i < tasks.length; i++) {
     const s = sideOf?.(tasks[i]!) === true ? 1 : 0
     side.push(s)
-    for (const tree of asTrees(globsOf(tasks[i]!) ?? [])) {
+    // Each brace alternative, as `outputsOverlap` reads them.
+    for (const tree of asTrees((globsOf(tasks[i]!) ?? []).flatMap(braceAlternatives))) {
       const lit = literalPath(tree)
       if (lit !== null) {
         literals.push([i, lit])
@@ -1567,10 +1760,10 @@ interface Side {
 
 /**
  * Refuse a task whose input globs can match another task's declared
- * outputs (X-54; no opt-out, owner 2026-10-16). Such a key reads bytes a
+ * outputs (X-54; no opt-out, 2026-10-16). Such a key reads bytes a
  * producer writes this run, so it is not known until the producer ran;
  * refused, every key reads only what no task writes and can be derived
- * before anything runs (M, 2026-10-07: "hash ahead of time, not
+ * before anything runs (2026-10-07: "hash ahead of time, not
  * waterfall"). A dependency's own key already cascades through
  * `dependsOn`, so the bytes it wrote add nothing a key needs; the one
  * exception is `refuseOverlaps`'s unfolded dependency.
@@ -1706,9 +1899,9 @@ type Found = Map<string, Overlap[]>
  * Which overlaps stand. A reader may read the outputs of a task in its
  * `dependsOn` closure whose key its own does not fold (it sets
  * `inputs.tasks` and leaves the producer out, also through the tasks it
- * folds): its key waits for the producer and hashes the bytes (owner,
- * 2026-10-16). Otherwise an output git ignores whole is no overlap (M,
- * 2026-10-15), a key reading only what git lists, unless the reader's
+ * folds): its key waits for the producer and hashes the bytes
+ * (2026-10-16). Otherwise an output git ignores whole is no overlap
+ * (2026-10-15), a key reading only what git lists, unless the reader's
  * glob starts in an ignored path (`dist/**`): naming it is asking for it.
  * Git is asked once, for every output and prefix together; one it cannot
  * speak for is refused. The answer holds for the lock; a run's stability
@@ -1858,7 +2051,7 @@ function readsOutputs(
           new UserError(
             `${reader.node.id} reads ${JSON.stringify(gi.slice(at.length))} in inputs.${field}, which matches ` +
               `${writer.node.id}'s output ${JSON.stringify(shown)} — a task's key must not read ` +
-              `the outputs of a task it does not depend on, or whose key it already folds. ` +
+              `the outputs of a task it does not depend on, or whose key it already includes. ` +
               `Exclude it: add ${JSON.stringify(`!${out}`)} to ${reader.node.id}'s ` +
               `inputs.${field}, or depend on ${writer.node.id} and leave it out of ` +
               `${reader.node.id}'s inputs.tasks, so its key hashes those bytes instead.`,

package/src/handoff.ts

@@ -1,11 +1,11 @@
-// A global vx hands off to the project's own (owner, 2026-10-13), found
+// A global vx hands off to the project's own (2026-10-13), found
 // from the workspace root, the one lookup every verb shares. Here for
 // the compiled binary installed by hand; an npm install's launcher
 // (npm-launcher.sh) walks the same way and `exec`s, which Bun cannot. The
 // walk runs before anything else loads, through `Bun.file(…).exists()`:
 // importing `node:fs` alone was ~1.1 ms of a 4 ms start (2026-10-13).
 
-/** `vx upgrade -g`: moves only the global vx, so it never hands off (owner, 2026-10-16). */
+/** `vx upgrade -g`: moves only the global vx, so it never hands off (2026-10-16). */
 export function upgradesOnlyItself(argv: readonly string[]): boolean {
   return argv[0] === 'upgrade' && argv.some((a) => a === '-g' || a === '--global')
 }
@@ -24,7 +24,8 @@ export async function localVx(
   compiled: boolean,
   uid = process.getuid?.(),
 ): Promise<string | null> {
-  if (process.env['VX_HANDED_OFF'] !== undefined || !compiled) return null
+  // Empty is unset, as the launcher's `[ -z "${VX_HANDED_OFF-}" ]` reads it.
+  if (process.env['VX_HANDED_OFF'] || !compiled) return null
   if (execPath.includes('/node_modules/')) return null
   const file = await workspaceFile(cwd)
   if (file === null) return null
@@ -44,7 +45,7 @@ export async function localVx(
 
 /**
  * The workspace config's paths under the root, in lookup order: one marks
- * the workspace root, the directory holding its `.vx` (owner, 2026-10-14).
+ * the workspace root, the directory holding its `.vx` (2026-10-14).
  */
 export const WORKSPACE_CONFIG_FILENAMES = [
   '.vx/workspace.ts',
@@ -67,7 +68,7 @@ const files = new Map<string, Promise<string | null>>()
 /**
  * The workspace config that marks the root for `dir`: the first
  * `.vx/workspace.*` from `dir` up to the git top-level ({@link gitTop}),
- * inclusive, or to `/` outside git (owner, 2026-10-13: "Workspace file is
+ * inclusive, or to `/` outside git (2026-10-13: "Workspace file is
  * the ultimate" and "never go out of git root"). Null when there is none.
  * Learned once per directory per run: the hand-off and the workspace root
  * share it (principle 9).
@@ -87,7 +88,7 @@ export function workspaceFileWritten(): void {
 }
 
 async function findWorkspaceFile(start: string): Promise<string | null> {
-  const top = await gitTop(start)
+  let top = await gitTop(start)
   const passed: string[] = []
   let found: string | null = null
   walk: for (let d = start; ; d = d.slice(0, d.lastIndexOf('/'))) {
@@ -99,15 +100,79 @@ async function findWorkspaceFile(start: string): Promise<string | null> {
         break walk
       }
     }
-    if (d === '' || d === top) break
+    if (d === '') break
+    if (d === top) {
+      // A submodule whose `.git` is a directory (added from a clone, not
+      // absorbed) is a top-level by its files: git alone knows the
+      // superproject tracks it. Asked only once the walk found nothing.
+      const above = await superproject(d)
+      if (above === null) break
+      top = await gitTop(above)
+    }
   }
+  if (found === null && top !== null && top !== '/') found = await outerWorkspaceFile(top)
   // Every directory walked has the same answer: the loader asks for the root's.
   for (const d of passed) if (!files.has(d)) files.set(d, Promise.resolve(found))
   return found
 }
 
+/**
+ * The workspace config of the repository `top` is embedded in (an untracked
+ * clone with its own `.git` directory), when that repository's git does not
+ * ignore it: `vx lock` lists such a repository's configs as the outer
+ * workspace's, and a run from inside one stopped at its `.git`, "no
+ * .vx/workspace.ts". A submodule's walk goes on already ({@link gitTop}).
+ * Asked only when the walk found nothing, so a run pays nothing for it.
+ */
+async function outerWorkspaceFile(top: string): Promise<string | null> {
+  // A worktree's `.git` is a file: another checkout, its own top-level.
+  if (!(await Bun.file(`${top}/.git/HEAD`).exists())) return null
+  const parent = top.slice(0, top.lastIndexOf('/')) || '/'
+  const outer = await gitTop(parent)
+  if (outer === null) return null
+  const file = await workspaceFile(parent)
+  if (file === null) return null
+  try {
+    // Plain `git`, as handoff imports nothing (the hand-off runs first).
+    // Exit 1: not ignored, so the outer listing holds it; 0 ignored; 128 an error.
+    // `./`: check-ignore reads `:x` as pathspec magic and refuses `:(literal)`.
+    const rel = top.slice(outer.length + (outer === '/' ? 0 : 1))
+    const p = Bun.spawnSync({
+      cmd: ['git', 'check-ignore', '-q', '--', `./${rel}`],
+      cwd: outer,
+      stdin: 'ignore',
+      stdout: 'ignore',
+      stderr: 'ignore',
+    })
+    return p.exitCode === 1 ? file : null
+  } catch {
+    return null
+  }
+}
+
 const tops = new Map<string, Promise<string | null>>()
 
+/** The working tree of the repository that tracks `top` as a submodule, or null. */
+async function superproject(top: string): Promise<string | null> {
+  const { executablePath, gitEnv } = await import('./util/index.js')
+  try {
+    const proc = Bun.spawn({
+      cmd: [executablePath('git'), 'rev-parse', '--show-superproject-working-tree'],
+      cwd: top,
+      env: gitEnv(),
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    const [out, exit] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+    const dir = out.trim()
+    return exit === 0 && dir.length > 0 ? dir : null
+  } catch {
+    // No git: the files are all there is to go by.
+    return null
+  }
+}
+
 /**
  * The git top-level holding `dir`, or null outside git: the nearest `.git`
  * up from it, a directory in a clone, a file in a worktree. A submodule's
@@ -132,6 +197,11 @@ async function findGitTop(start: string): Promise<string | null> {
     if (await file.exists()) {
       const gitdir = await file.text().catch(() => '')
       if (!/(^|[\s/])\.git\/modules\//.test(gitdir)) return d || '/'
+      // A submodule's own worktree points there too, and is a top-level:
+      // git writes `commondir` in a worktree's gitdir alone.
+      const to = gitdir.replace(/^gitdir:\s*/, '').trim()
+      if (await Bun.file(`${to.startsWith('/') ? '' : `${d}/`}${to}/commondir`).exists())
+        return d || '/'
     }
     if (d === '') return null
   }
@@ -149,6 +219,10 @@ export function vxPath(): string {
  * second would read as "stop now" (npm-launcher.cjs, the same rule).
  */
 export async function handOff(bin: string, args: readonly string[]): Promise<never> {
+  // This vx waits out the whole run beside the tasks, and `run()`, which
+  // hides the env on every verb, is never reached here. Imported here:
+  // a start that hands off nothing pays nothing.
+  await (await import('./util/index.js')).hideEnvFromTasks()
   const child = Bun.spawn([bin, ...args], {
     stdio: ['inherit', 'inherit', 'inherit'],
     env: { ...process.env, VX_HANDED_OFF: process.execPath },
@@ -159,13 +233,27 @@ export async function handOff(bin: string, args: readonly string[]): Promise<nev
     })
   }
   const code = await child.exited
+  const signal = child.signalCode
+  if (signal === null) process.exit(code)
+  // Die of a stop signal the local vx died of, as vx itself does: a shell
+  // running vx in a script stops on Ctrl-C only when its child died of
+  // SIGINT, and an exit 130 ran the script's next line. The code below is
+  // the rest, and the fallback should the signal not land.
+  if (signal === 'SIGINT' || signal === 'SIGTERM' || signal === 'SIGHUP') {
+    process.removeAllListeners(signal)
+    process.kill(process.pid, signal)
+  }
+  if (typeof signal === 'number') process.exit(128 + signal)
   const { constants } = await import('node:os')
-  process.exit(child.signalCode === null ? code : 128 + (constants.signals[child.signalCode] ?? 1))
+  process.exit(128 + (constants.signals[signal] ?? 1))
 }
 
 function inForeground(): boolean {
   try {
-    const stat = Bun.spawnSync(['ps', '-o', 'pgid=,tpgid=', '-p', String(process.pid)])
+    // The handed-off vx's tasks run meanwhile and could read its env: PATH alone (`helperEnv`).
+    const stat = Bun.spawnSync(['ps', '-o', 'pgid=,tpgid=', '-p', String(process.pid)], {
+      env: { PATH: process.env['PATH'] ?? '' },
+    })
     const [pgid, tpgid] = stat.stdout.toString().trim().split(/\s+/)
     return pgid !== undefined && pgid === tpgid
   } catch {