instar 1.3.928 → 1.3.930

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-24T04:02:28.049Z",
-  "instarVersion": "1.3.928",
+  "generatedAt": "2026-07-24T04:44:30.524Z",
+  "instarVersion": "1.3.930",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "5fbeb5944f457051b0d8d4cf8151d7900e23e4b3d1849f1013a93d5d5a0107f9",
+      "contentHash": "6f779c5c3de7e6e0fae678ec6867e1798aaeaac45e3a78f1e9e13e44442198fa",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.929.md

@@ -0,0 +1,22 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Every place the system invents a credential — the dashboard PIN and internal auth tokens — now uses the operating system's cryptographically secure random source instead of the predictable general-purpose one. Externally contributed fix (Marceli Pawlinski, PR #1587), adopted with authorship preserved, plus one additional site the contribution missed (the PIN auto-generated during post-update migration).
+
+## What to Tell Your User
+
+Nothing to do. Existing PINs and tokens are untouched; only newly generated ones use the stronger source.
+
+## Summary of New Capabilities
+
+None — same PINs, same token shapes, just unpredictable ones.
+
+## Evidence
+
+- PIN range preserved exactly (6 digits, 100000–999999); token length preserved (32 hex chars).
+- Full-tree sweep for remaining credential-class `Math.random` uses: zero (non-credential uses — tmp suffixes, spawn ids, record ids — reviewed and left).
+- External PR #1587's unit shards ran fully green on CI before adoption (8/8 shards, node 20 + 22).

package/upgrades/1.3.930.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`WorktreeManager` creates an isolated dev checkout (`git worktree add`, or `git clone` when the source is outside agent home) and fast-copies `node_modules` — but it never regenerated husky's git-ignored `.husky/_` shim. Since `core.hooksPath = .husky/_` points at that shim, a fresh checkout had the tracked `pre-commit`/`pre-push` hook files but not the directory git actually resolves the hooks to. Git then silently ran **no** hook (no error), so the instar-dev pre-commit/pre-push enforcement was bypassed in every fresh worktree until someone ran `npm install`.
+
+A new best-effort `seedGitHooks(worktreePath)` step runs right after the create/clone: it resolves the effective `core.hooksPath`, and if it is a relative path present in the source but missing in the fresh checkout, copies the shim directory across (and, on the clone path where the fresh `.git/config` carries no hooksPath, replicates the hooksPath config). It is generic (never names husky), fails open (warns, never blocks worktree creation), is idempotent, path-contained, and a no-op for repos with no relative hooksPath or an absolute one.
+
+## What to Tell Your User
+
+Nothing changes in how you use your agent day to day — this is an internal reliability fix for instar development. If you run instar-dev / build worktrees, their local commit/push safety checks now actually run from the first commit instead of being silently skipped until a dependency install. There is no new command, setting, or user-visible behavior.
+
+## Summary of New Capabilities
+
+- Fresh dev worktrees/clones get their git-hooks shim seeded automatically, so the instar-dev pre-commit/pre-push gates are live immediately — no `npm install` required to activate them.
+- No new API, config, or operator surface; the seeding is automatic, fail-open, and a no-op for repos that don't use a relative-path hooks framework.
+
+## Evidence
+
+- Empirically reproduced: a fresh `git worktree add HEAD` has `pre-commit`/`pre-push` but no `.husky/_` → git runs nothing; a live echo dev worktree was found with dead hooks.
+- New regression test `tests/unit/WorktreeManager-git-hooks-seed.test.ts` (4 tests) exercises the real create path via the two-session harness: clone path (shim seeded + hooksPath replicated), worktree path (shim seeded, hooksPath inherited), and both no-op boundaries (non-husky repo, absolute hooksPath). Verified test-first: the clone + worktree tests fail without the fix, all 4 pass with it.
+- Existing worktree suites (`WorktreeManager`, `InstarWorktreeManager`, `WorktreeManager-merkle` — 64 tests) pass unchanged; full `tsc` build clean.

package/upgrades/side-effects/adopt-secure-random.md

@@ -0,0 +1,35 @@
+# Side-Effects Review — adopt-secure-random
+
+## Change
+
+Replace `Math.random()`-derived credential generation with `node:crypto` CSPRNG
+calls at every credential-generation site:
+
+- `src/commands/server.ts` — dashboard PIN regeneration (4 sites) → `randomInt(100000, 1000000)`; auth-token generation → `randomBytes(16).toString('hex')`. (Adopted from external PR #1587, author Marceli Pawlinski, authorship preserved via cherry-pick.)
+- `src/monitoring/CoherenceMonitor.ts` — token generation → `randomBytes` (same adoption).
+- `src/core/PostUpdateMigrator.ts` — the one site #1587 missed: auto-generated dashboard PIN on migration → `crypto.randomInt(100000, 1000000)`.
+
+## Behavior preserved
+
+- PIN semantics identical: `randomInt(100000, 1000000)` yields exactly the 6-digit
+  range 100000–999999, matching `Math.floor(100000 + Math.random() * 900000)`.
+- Token length identical: `randomBytes(16).toString('hex')` = 32 hex chars, same
+  shape as the prior 32-char output.
+- No format, storage, or consumer change: every reader of `dashboardPin` /
+  `authToken` sees the same shape.
+
+## Blast radius
+
+- Values only become unpredictable (the point of the fix). No API surface, config
+  schema, or message format changes.
+- `crypto.randomInt` throws only on invalid ranges; the ranges here are constant
+  and valid. `randomBytes(16)` failure modes (entropy exhaustion) are the same
+  class Node itself depends on at startup.
+- Migration path: the migrator PIN site runs only when `dashboardPin` is absent
+  and `authToken` present — the exact prior trigger. Existing PINs are untouched.
+
+## Not affected
+
+- No test fixtures encode specific PIN/token values derived from Math.random.
+- Remaining `Math.random()` uses in src/ are non-credential (tmp-file suffixes,
+  spawn ids, store record ids) — reviewed and deliberately left.

package/upgrades/side-effects/worktree-git-hooks-seed.md

@@ -0,0 +1,109 @@
+# Side-Effects Review — Seed git-hooks shim into fresh worktrees/clones
+
+**Version / slug:** `worktree-git-hooks-seed`
+**Date:** `2026-07-19`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `independent reviewer subagent — Concur (see Phase 5 note at end)`
+
+## Summary of the change
+
+`WorktreeManager.createBinding` creates an isolated dev environment two ways — `git worktree add` (in-tree) or `git clone` (when the source lives outside agent home) — then fast-copies `node_modules` from the source. It never ran husky's `prepare`, so the git-ignored, generated `.husky/_` shim (the directory `core.hooksPath = .husky/_` actually points at) was absent in every fresh checkout. Git then resolves the hooksPath to a missing directory and silently runs **no** hook — no error — so the instar-dev pre-commit/pre-push enforcement was bypassed until an `npm install` regenerated the shim. This change adds one best-effort call, `seedGitHooks(worktreePath)`, right after the create/clone + `fastCopyDeps` block. It resolves the effective `core.hooksPath`, and if it is a relative path missing in the fresh checkout but present in the source, copies the shim directory across (and, on the clone path where the fresh `.git/config` has no hooksPath, replicates the hooksPath config). Files touched: `src/core/WorktreeManager.ts` (+1 call site, +1 private method); test `tests/unit/WorktreeManager-git-hooks-seed.test.ts`.
+
+## Decision-point inventory
+
+- `WorktreeManager.seedGitHooks` — **add** — filesystem/setup operation that seeds a hooks shim. It holds **no** block/allow authority: it never rejects, delays, or blocks worktree creation; it only makes an EXISTING decision point (the pre-commit/pre-push gates) able to run. On any uncertainty it warns and returns.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. `seedGitHooks` cannot reject a worktree creation; every failure path (`try/catch`, missing source, path-escape, absolute hooksPath) is a silent `return` or an advisory `warn`, and worktree creation proceeds regardless.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+No block/allow surface — under-block not applicable in the gate sense. Remaining *coverage* gaps (stated honestly, not deferred):
+
+- **Source repo has no shim to copy** (e.g. a genuinely bare source with no on-disk `.husky/_` and no relative hooksPath resolvable in the source): the method emits a warn and the new worktree's hooks stay inactive until an install runs. This is an honest best-effort boundary, not a regression — behavior is no worse than before the fix, and the warn surfaces it.
+- **Worktrees created BEFORE this fix** stay hook-dead until re-created or re-installed. This change seeds NEW worktrees only; it does not retroactively repair existing ones (that would be a scope-separate sweep over live worktrees). Scope boundary, explicitly not silently deferred work.
+- **A repo whose hooks framework is not "regenerate-the-shim-shaped"** (a hooksPath pointing at a dir that legitimately must be regenerated per-checkout rather than copied) would get a copied-but-possibly-stale shim; husky's `_` shims are checkout-independent so this is correct for husky, and the copy is a strict improvement over "no hook at all" for any framework whose hooksPath dir is checkout-independent.
+- **A crafted/malicious `core.hooksPath`** — a `../`-relative value, an absolute value, or a value routed through a tracked `.husky` **symlink** — is refused: both a lexical containment check (`startsWith` the resolved root, trailing-`path.sep` so a sibling-prefix like `wt-evil` can't slip through) AND a symlink-safe realpath check (resolve the real path of the nearest existing ancestor and require it stays within the worktree/source real root, since `path.resolve` is lexical and does not follow symlinks). Not reachable under the trusted-source model, but enforced regardless so the guarantee holds literally.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The defect is that the worktree/clone creation primitive produced an environment missing a file git needs — so the fix belongs in the primitive that creates the environment (`WorktreeManager.createBinding`), immediately adjacent to `fastCopyDeps`, which already solves the sibling "the fresh checkout is missing generated content (`node_modules`)" problem the same best-effort way. It is deliberately NOT implemented as husky-specific logic (no husky string), and NOT as a higher-level gate — it is a low-level setup step that RESTORES the higher-level gate's ability to fire. No smarter existing layer owns "seed generated files into a fresh worktree"; `fastCopyDeps` is the only peer and this rides directly after it.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface. It is a filesystem setup step that makes the pre-existing pre-commit/pre-push gates operational in a fresh worktree. It produces no verdict and holds no authority. It fails open (warn, never throw) so a seeding failure can never block worktree creation — the safe direction.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new static heuristic at a competing-signals decision point. The logic is a deterministic invariant with an enumerable domain: "if the effective `core.hooksPath` is a relative path present in the source but missing in the worktree, copy it." There are no competing live signals (work evidence / liveness / ownership) being weighed — it is a pure setup precondition.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** Runs once, after the create/clone + `fastCopyDeps` block and before the binding is signed/emitted. It reads git config and copies a directory; it shadows nothing and is shadowed by nothing.
+- **Double-fire:** Idempotent — if the shim directory already exists it returns immediately (`fs.existsSync(destDir)`), so a re-attach or repeated create never re-copies or clobbers a live shim.
+- **Races:** Operates only on the freshly-created worktree path (not yet published as a binding, no other session attached), so no shared-state race. The source `.husky/_` is read-only from this method's view.
+- **Feedback loops:** None. It writes into the new worktree only; it does not feed any system that feeds back into worktree creation.
+- **SafeGitExecutor/SourceTreeGuard:** the config read uses `SafeGitExecutor.readSync` (`config --get` is in the read-only allowlist); the clone-path config SET uses `SafeGitExecutor.execSync` against the new worktree path (under agent home / stateDir), never the instar source tree — so SourceTreeGuard is not tripped. Both resolved paths are containment-checked (lexical `startsWith` on the resolved root PLUS a symlink-safe realpath check on the nearest existing ancestor) to refuse a hooksPath that escapes either root — via a `../` value, an absolute value, or a tracked symlink.
+
+---
+
+## 6. External surfaces
+
+- **Other agents / users:** none. Worktree creation is a local dev operation.
+- **External systems:** none (no Telegram/Slack/GitHub/network surface).
+- **Persistent state:** writes the `.husky/_` shim directory into the new worktree and, on the clone path, sets `core.hooksPath` in the new clone's local `.git/config`. Both are inside the freshly-created worktree/clone — no shared or durable instar state is touched.
+- **Timing:** no timing dependency; synchronous, bounded (3s git timeouts, a single directory copy).
+- **Operator surface (Mobile-Complete):** No operator-facing actions — not applicable.
+
+---
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable. This change touches no dashboard renderer, approval page, or grant/revoke/secret form.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** A worktree/clone is a physical checkout on one machine's disk; each machine's `WorktreeManager` creates and seeds its own worktrees. There is no cross-machine state to replicate and nothing to proxy on read — the fix is the same code running symmetrically on every machine, each seeding hooks into its own local checkouts. No user-facing notice, no durable state that could strand on topic transfer, no generated URL.
+
+---
+
+## 8. Rollback cost
+
+Low. The change is one additive, fail-open method + its call site. To back it out: revert the commit (or, as an in-place escape hatch, the method is a no-op for any repo with no relative `core.hooksPath`, and its only writes are into fresh worktrees — a bad seed is corrected by deleting/recreating the worktree, never a data migration). No schema, no persistent instar state, no release-coupled migration. Worst realistic failure mode (a warn-logged seed miss) leaves behavior exactly as it was before the fix.
+
+---
+
+## Phase 5 — Second-pass review (independent reviewer subagent)
+
+**Verdict: Concur with the review.**
+
+The reviewer independently traced the logic against `createBinding` and confirmed: (1) correctness on both paths — worktree path seeds the shim with the inherited relative hooksPath (git resolves a relative hooksPath against each worktree's own root), clone path seeds the shim AND sets the hooksPath on the clone's independent config; (2) the config SET can **never** mutate the source repo, because `needsConfigSet` is true only when the worktree's own config read was empty, which on a linked worktree (sharing the source config) is structurally impossible — so it only ever fires against a clone's independent config; (3) fail-open — the entire body is inside `try/catch → emit('warn')` and `'warn'` has no unhandled-emit throw semantics, so the method cannot throw and worktree creation can't break; (4) idempotent on re-attach.
+
+Two caveats the reviewer raised were addressed in this change (not merely recorded):
+- **Lexical-only containment** → added a symlink-safe realpath containment check (resolve the nearest existing ancestor's real path, require it stays within the worktree/source real root), so the "escape refused" claim now holds for symlink physical escapes, not just `../`/absolute values.
+- **No negative-path tests** → added two regression tests: an escaping `../evil` hooksPath (refused, nothing written outside, worktree still created) and a source-with-no-shim case (advisory warn, no-op, no throw).