refactor(#4653): narrow the containment export and migrate all 15 validatePath sites

Phase 3 of epic #4636, stages 1-2. Implements ADR-4650 decisions 1 and 2: one
containment predicate, and an exported shape that cannot hand a caller a usable
path when the answer is unsafe.

THE EXPORT IS NOW A PAIR, BOTH RETURNING A BRANDED TYPE:

  assertWithinRoot(candidate, root, label?, opts?) -> ContainedPath   (throws)
  tryWithinRoot(candidate, root, opts?)            -> ContainedPath | null

ADR-4650 names only the throwing form. That does not survive contact with the
call sites: findPhaseArtifact probes a direct path, then a .planning/ path, then
each readdir entry, and throwing on the first miss breaks it outright. Six of the
fifteen sites need a non-throwing check. Recorded here rather than papered over.

WHY BRANDED. validatePath returns { safe, resolved, error } and populates
resolved with the ESCAPING path on the traversal branch — so a caller who skips
the boolean gets an attacker-controlled value precisely in the dangerous case.
tryWithinRoot returns exactly null there; assertWithinRoot throws. A plain string
is not assignable to ContainedPath, so a migrated site that validates one path
and then passes a different one is now a type error rather than a silent bug.
That is the defect this epic exists to close, and I introduced it twice in
Phase 2.

THE ENGINE IS UNTOUCHED. validatePath's body is not re-derived — the diff shows
zero edits to the dangling-symlink existence-oracle closure, the ancestor
canonicalization (macOS /var vs /private/var), or the separator-aware boundary
test. Each was acquired as a bug fix and a re-derivation would silently lose one.
requireSafePath now delegates to assertWithinRoot, so there is one implementation
beneath both names; its return type is branded, which is why its 13 call sites
compile unchanged.

A TYPESCRIPT LIMITATION, FIXED AT THE ROOT RATHER THAN WORKED AROUND. TS applies
never-return control-flow narrowing only when the callee is a function
declaration or a const with an EXPLICIT type annotation. Both routers do
`const { error } = io` — destructured, unannotated — so `error(...)` did not
narrow ContainedPath | null and four sites wanted a dead
`throw new Error('unreachable')` after it. Annotating the const
(`const error: typeof io.error = io.error`) makes TS narrow properly and the dead
throws are gone.

That annotation has a large, deliberate consequence: with narrowing working,
`@typescript-eslint/no-unnecessary-type-assertion` fires at 37 sites in
commands.cts where `as string` / `!` existed ONLY to paper over the missing
narrowing. They are removed. The rule is type-aware and fires only where the
assertion changes nothing, and both forms erase at compile time, so the emitted
behavior is unchanged — but the module loses 37 unchecked casts over
string | undefined, which is the same class of "trust me" the containment work
is removing. Widening the diff here buys that.

TWO SITES LOSE DIAGNOSTIC TEXT, deliberately. tryWithinRoot has no error channel,
so init.cts's agent-skills warning and cmdPrSubrepo's rejection now name the
condition rather than echoing validatePath's message. verify.cts had already
stopped echoing it on purpose — the message embeds absolute host paths — so this
makes the three agree instead of two-of-three.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/security.cts

@@ -182,16 +182,58 @@ export function loadTrustedGlobalRoots(config: unknown): string[] {
   return result;
 }
 
+/**
+ * A path proven to resolve inside a declared root.
+ *
+ * A plain `string` is NOT assignable to `ContainedPath` — that asymmetry is
+ * the entire point. The shape being replaced (`validatePath`'s
+ * `{ resolved: string }`) returns a usable-looking path even when the answer
+ * is unsafe (the traversal branch still populates `resolved` with the
+ * escaping path), so a plain string in hand proves nothing. A
+ * `ContainedPath` can only be produced by `assertWithinRoot` /
+ * `tryWithinRoot` on their success paths, so possessing one is proof the
+ * containment check already passed.
+ */
+export type ContainedPath = string & { readonly __containedIn: unique symbol };
+
 /**
  * Validate a file path and throw on traversal attempt.
  * Convenience wrapper around validatePath for use in CLI commands.
  */
-export function requireSafePath(filePath: unknown, baseDir: unknown, label: string | null | undefined, opts: { allowAbsolute?: boolean } = {}): string {
-  const result = validatePath(filePath, baseDir, opts);
+export function assertWithinRoot(candidate: unknown, root: unknown, label?: string | null, opts: { allowAbsolute?: boolean } = {}): ContainedPath {
+  const result = validatePath(candidate, root, opts);
   if (!result.safe) {
     throw new Error(`${label || 'Path'} validation failed: ${result.error}`);
   }
-  return result.resolved;
+  return result.resolved as ContainedPath;
+}
+
+/**
+ * Validate a file path and return null on traversal attempt (no throw).
+ *
+ * Returns exactly `null` when unsafe — never `''`, never `result.resolved`.
+ * `validatePath` populates `resolved` with the ESCAPING path on the
+ * traversal branch, so returning it here would reproduce the defect this
+ * narrowing exists to remove.
+ */
+export function tryWithinRoot(candidate: unknown, root: unknown, opts: { allowAbsolute?: boolean } = {}): ContainedPath | null {
+  const result = validatePath(candidate, root, opts);
+  if (!result.safe) {
+    return null;
+  }
+  return result.resolved as ContainedPath;
+}
+
+/**
+ * Validate a file path and throw on traversal attempt.
+ * Convenience wrapper around validatePath for use in CLI commands.
+ *
+ * Delegates to assertWithinRoot so there is one implementation beneath both
+ * names; its declared return type is ContainedPath (a branded string, still
+ * assignable to string) so existing callers keep compiling untouched.
+ */
+export function requireSafePath(filePath: unknown, baseDir: unknown, label: string | null | undefined, opts: { allowAbsolute?: boolean } = {}): ContainedPath {
+  return assertWithinRoot(filePath, baseDir, label, opts);
 }
 
 // ─── Prompt Injection Detection ────────────────────────────────────────────────────