@infinitedusky/indusk-mcp 1.36.2 → 1.37.0

package/extensions/worktree/scripts/lib/workbench-helpers.sh

@@ -15,6 +15,23 @@
 #       Caller is responsible for calling _resolve_workbench_root first
 #       and cd'ing or passing the path explicitly via WORKBENCH_ROOT env.
 #
+#   _read_workbench_repos
+#       Echoes the declared repo names, one per line, in declared order.
+#       DELIBERATE PORT of readWorkbenchRepos() in
+#       src/lib/worktree/repos.ts — bash cannot import the TS module, so
+#       the reduction lives in two places and they change together.
+#       `worktree.repos[]` is canonical; the legacy `worktree.wrapped_repo`
+#       reduces to a one-element list. Names that are not clean path
+#       segments are dropped and duplicates collapse to first occurrence,
+#       because every caller joins these into a filesystem path.
+#
+#   _resolve_workbench_repo [requested]
+#       Echoes the one repo the caller means. With `requested` it must
+#       match a declared repo. Without it, a single declared repo is
+#       implied; with several, this FAILS and names the candidates on
+#       stderr rather than picking one — putting a worktree in the wrong
+#       repo looks exactly like success until someone reads the branch.
+#
 #   _read_worktree_config <repo> <jq-filter>
 #       Reads a value from .indusk/worktree-configs/<repo>.json using the
 #       provided jq filter. Echoes the value or empty string if config
@@ -78,6 +95,73 @@ _read_workbench_field() {
 	jq -r ".worktree.${field} // \"\"" "$config" 2>/dev/null || echo ""
 }
 
+_read_workbench_repos() {
+	local root="${WORKBENCH_ROOT:-}"
+	if [[ -z "$root" ]]; then
+		echo "Error: _read_workbench_repos: WORKBENCH_ROOT must be set" >&2
+		return 1
+	fi
+	local config="$root/.indusk/config.json"
+	if [[ ! -f "$config" ]]; then
+		echo "Error: _read_workbench_repos: $config not found" >&2
+		return 1
+	fi
+	# The reduction, in jq. `unique` is deliberately NOT used: it sorts, and
+	# declared order is meaningful (the first repo is the implied one at N=1).
+	jq -r '
+		(.worktree // {}) as $w
+		| (
+			if ($w.repos | type) == "array" then $w.repos
+			elif ($w.wrapped_repo | type) == "string" then [{ name: $w.wrapped_repo }]
+			else []
+			end
+		)
+		| map(select(type == "object"))
+		| map(.name)
+		| map(select(type == "string"))
+		| map(select(. != "" and . != "." and . != ".." and (contains("/") | not) and (contains("\\") | not)))
+		| reduce .[] as $n ([]; if (index($n) == null) then . + [$n] else . end)
+		| .[]
+	' "$config" 2>/dev/null || echo ""
+}
+
+_resolve_workbench_repo() {
+	local requested="${1:-}"
+	local repos=()
+	while IFS= read -r line; do
+		[[ -n "$line" ]] && repos+=("$line")
+	done < <(_read_workbench_repos)
+
+	if [[ ${#repos[@]} -eq 0 ]]; then
+		echo "Error: this project is not a workbench (set worktree.shape=\"workbench\" and worktree.repos[] in .indusk/config.json, or run \`indusk init --workbench\`)." >&2
+		return 1
+	fi
+
+	local joined
+	joined="$(printf '%s, ' "${repos[@]}")"
+	joined="${joined%, }"
+
+	if [[ -n "$requested" ]]; then
+		local r
+		for r in "${repos[@]}"; do
+			if [[ "$r" == "$requested" ]]; then
+				echo "$r"
+				return 0
+			fi
+		done
+		echo "Error: no declared repo named \"$requested\". This workbench declares: ${joined}." >&2
+		return 1
+	fi
+
+	if [[ ${#repos[@]} -eq 1 ]]; then
+		echo "${repos[0]}"
+		return 0
+	fi
+
+	echo "Error: this workbench declares more than one repo, so the repo must be named: ${joined}." >&2
+	return 1
+}
+
 _read_worktree_config() {
 	local repo="$1"
 	local filter="$2"

package/extensions/worktree/scripts/preflight.sh

@@ -53,20 +53,16 @@ fi
 WORKBENCH_ROOT="$(_resolve_workbench_root)"
 export WORKBENCH_ROOT
 
-WRAPPED_REPO="$(_read_workbench_field wrapped_repo)"
-if [[ -z "$WRAPPED_REPO" ]]; then
-	echo "Error: .indusk/config.json missing worktree.wrapped_repo" >&2
-	exit 1
-fi
+REPO="$(_resolve_workbench_repo "${REPO_ARG:-}")"
 
-CONFIG_FILE="$WORKBENCH_ROOT/.indusk/worktree-configs/${WRAPPED_REPO}.json"
+CONFIG_FILE="$WORKBENCH_ROOT/.indusk/worktree-configs/${REPO}.json"
 if [[ ! -f "$CONFIG_FILE" ]]; then
 	echo "Error: no worktree config at $CONFIG_FILE" >&2
 	exit 1
 fi
 
 # Reject preflighting the trunk — preflight is a feature-branch concept.
-if [[ "$SLUG" == "$WRAPPED_REPO" ]]; then
+if [[ "$SLUG" == "$REPO" ]]; then
 	echo "Error: preflight cannot target the trunk; pick a worktree slug" >&2
 	exit 1
 fi
@@ -86,7 +82,7 @@ for entry in "$WORKBENCH_ROOT"/*; do
 	name="$(basename "$entry")"
 	_is_reserved_name "$name" && continue
 	# Skip the trunk symlink — preflight is for feature worktrees.
-	[[ "$name" == "$WRAPPED_REPO" ]] && continue
+	[[ "$name" == "$REPO" ]] && continue
 	if [[ "$name" == "$SLUG" ]]; then
 		exact_paths+=("$entry")
 	elif [[ "$name" == *"-$SLUG" ]]; then

package/extensions/worktree/scripts/refresh-worktree.sh

@@ -33,17 +33,13 @@ ARG="${1:?Usage: refresh-worktree.sh <slug|--all>}"
 WORKBENCH_ROOT="$(_resolve_workbench_root)"
 export WORKBENCH_ROOT
 
-WRAPPED_REPO="$(_read_workbench_field wrapped_repo)"
-if [[ -z "$WRAPPED_REPO" ]]; then
-	echo "Error: .indusk/config.json missing worktree.wrapped_repo" >&2
-	exit 1
-fi
+REPO="$(_resolve_workbench_repo "${REPO_ARG:-}")"
 
 SIBLING_PARENT_RAW="$(_read_workbench_field sibling_parent)"
 SIBLING_PARENT="$(_expand_path "$SIBLING_PARENT_RAW")"
-CLIENT_ROOT="$SIBLING_PARENT/$WRAPPED_REPO"
+CLIENT_ROOT="$SIBLING_PARENT/$REPO"
 
-CONFIG_FILE="$WORKBENCH_ROOT/.indusk/worktree-configs/${WRAPPED_REPO}.json"
+CONFIG_FILE="$WORKBENCH_ROOT/.indusk/worktree-configs/${REPO}.json"
 if [[ ! -f "$CONFIG_FILE" ]]; then
 	echo "Error: no worktree config at $CONFIG_FILE" >&2
 	exit 1
@@ -59,7 +55,7 @@ refresh_one() {
 		echo "  SKIP: $slug — directory not found"
 		return 0
 	fi
-	if [[ "$slug" == "$WRAPPED_REPO" ]]; then
+	if [[ "$slug" == "$REPO" ]]; then
 		return 0 # trunk symlink, not a worktree
 	fi
 	# Check this is actually a git worktree (has a .git file pointing into

package/extensions/worktree/scripts/setup-worktree.sh

@@ -3,16 +3,21 @@
 # single-repo workbench.
 #
 # Usage:
-#   setup-worktree.sh <slug> [base-branch]
+#   setup-worktree.sh [--repo <name>] [--worktrees-dir <dir>] <slug> [base-branch]
 #
 # Examples:
 #   setup-worktree.sh feat-autoops-cancel-polish
-#   setup-worktree.sh feat-autoops-reschedule main
+#   setup-worktree.sh --repo avoca-next feat-thing main
+#
+# `--repo` names which declared repo to branch from. It is optional when the
+# workbench declares exactly one; with several it is REQUIRED, and omitting it
+# fails naming the candidates rather than defaulting to the first.
 #
 # What it does:
 #   1. Resolves the workbench root (walks up from cwd to find
 #      .indusk/config.json with worktree.shape == "workbench").
-#   2. Reads .indusk/config.json for worktree.wrapped_repo + worktree.sibling_parent.
+#   2. Resolves which declared repo to use (worktree.repos[], legacy
+#      wrapped_repo reduced) + worktree.sibling_parent.
 #   3. Reads .indusk/worktree-configs/<repo>.json for trunk_branch, base_branch,
 #      copy_files[], append_files[], apply_commits[].
 #   4. Creates a worktree at <workbench>/<slug>, branched off <base-branch>
@@ -33,17 +38,27 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=lib/workbench-helpers.sh
 source "$SCRIPT_DIR/lib/workbench-helpers.sh"
 
-SLUG="${1:?Usage: setup-worktree.sh <slug> [base-branch]}"
+REPO_ARG=""
+WORKTREES_DIR=""
+# Flags in any order; both optional. `--worktrees-dir` is passed by the TS
+# wrapper when the repo DECLARES a worktrees location. Absent, worktrees land
+# at the workbench root — today's flat layout, unchanged.
+while [[ "${1:-}" == --* ]]; do
+	case "$1" in
+		--repo) REPO_ARG="${2:?--repo requires a repo name}"; shift 2 ;;
+		--worktrees-dir) WORKTREES_DIR="${2:?--worktrees-dir requires a directory}"; shift 2 ;;
+		*) echo "Error: unknown flag $1" >&2; exit 1 ;;
+	esac
+done
+SLUG="${1:?Usage: setup-worktree.sh [--repo <name>] <slug> [base-branch]}"
 BASE_BRANCH_ARG="${2:-}"
 
 WORKBENCH_ROOT="$(_resolve_workbench_root)"
 export WORKBENCH_ROOT
 
-WRAPPED_REPO="$(_read_workbench_field wrapped_repo)"
-if [[ -z "$WRAPPED_REPO" ]]; then
-	echo "Error: .indusk/config.json missing worktree.wrapped_repo (required in single-repo workbench mode)" >&2
-	exit 1
-fi
+# One resolver for "which repo" — refuses rather than guessing when the
+# workbench declares several and the caller named none.
+REPO="$(_resolve_workbench_repo "$REPO_ARG")"
 
 SIBLING_PARENT_RAW="$(_read_workbench_field sibling_parent)"
 if [[ -z "$SIBLING_PARENT_RAW" ]]; then
@@ -52,31 +67,40 @@ if [[ -z "$SIBLING_PARENT_RAW" ]]; then
 fi
 SIBLING_PARENT="$(_expand_path "$SIBLING_PARENT_RAW")"
 
-CLIENT_ROOT="$SIBLING_PARENT/$WRAPPED_REPO"
+CLIENT_ROOT="$SIBLING_PARENT/$REPO"
 if [[ ! -d "$CLIENT_ROOT/.git" ]]; then
 	echo "Error: $CLIENT_ROOT is not a git repo" >&2
 	exit 1
 fi
 
-CONFIG_FILE="$WORKBENCH_ROOT/.indusk/worktree-configs/${WRAPPED_REPO}.json"
+CONFIG_FILE="$WORKBENCH_ROOT/.indusk/worktree-configs/${REPO}.json"
 if [[ ! -f "$CONFIG_FILE" ]]; then
 	echo "Error: no worktree config at $CONFIG_FILE" >&2
 	echo "Run 'indusk extensions enable worktree' to scaffold the starter, or hand-create the file." >&2
 	exit 1
 fi
 
-TRUNK_BRANCH="$(_read_worktree_config "$WRAPPED_REPO" '.trunk_branch // "main"')"
-CONFIG_BASE_BRANCH="$(_read_worktree_config "$WRAPPED_REPO" '.base_branch // .trunk_branch // "main"')"
+TRUNK_BRANCH="$(_read_worktree_config "$REPO" '.trunk_branch // "main"')"
+CONFIG_BASE_BRANCH="$(_read_worktree_config "$REPO" '.base_branch // .trunk_branch // "main"')"
 BASE_BRANCH="${BASE_BRANCH_ARG:-$CONFIG_BASE_BRANCH}"
 
 # Reject slug collisions with the wrapped repo's name (resolution would be
 # ambiguous; the trunk lives at that path).
-if [[ "$SLUG" == "$WRAPPED_REPO" ]]; then
+if [[ -z "$WORKTREES_DIR" && "$SLUG" == "$REPO" ]]; then
+	# Only a flat layout can collide — a declared worktrees directory puts the
+	# worktree somewhere the trunk can never be.
 	echo "Error: slug '$SLUG' collides with the wrapped repo name; pick a different slug" >&2
 	exit 1
 fi
 
-WORKTREE_PATH="$WORKBENCH_ROOT/$SLUG"
+# A declared location is a single clean segment (guarded on the TS side before
+# it ever reaches here), so this join cannot escape the workbench.
+if [[ -n "$WORKTREES_DIR" ]]; then
+	WORKTREE_PATH="$WORKBENCH_ROOT/$WORKTREES_DIR/$SLUG"
+	mkdir -p "$WORKBENCH_ROOT/$WORKTREES_DIR"
+else
+	WORKTREE_PATH="$WORKBENCH_ROOT/$SLUG"
+fi
 if [[ -e "$WORKTREE_PATH" ]]; then
 	echo "Error: worktree already exists at $WORKTREE_PATH" >&2
 	echo "To remove: git -C $CLIENT_ROOT worktree remove --force $WORKTREE_PATH" >&2
@@ -91,7 +115,7 @@ BRANCH_NAME="$SLUG"
 
 echo "Setting up worktree:"
 echo "  Workbench:    $WORKBENCH_ROOT"
-echo "  Wrapped repo: $WRAPPED_REPO"
+echo "  Wrapped repo: $REPO"
 echo "  Slug:         $SLUG"
 echo "  Branch:       $BRANCH_NAME (off $BASE_BRANCH)"
 echo "  Trunk:        $TRUNK_BRANCH"

package/extensions/worktree/skill.md

@@ -23,10 +23,10 @@ A workbench is an indusk project with this shape:
 ```
 my-workbench/                  # the indusk project
 ├── .indusk/                   # single source of truth — plans, eval, highlights, worktree-configs
-│   ├── config.json            # `worktree.shape: "workbench"` + `worktree.wrapped_repo` + `worktree.sibling_parent`
+│   ├── config.json            # `worktree.shape: "workbench"` + `worktree.repos[]` (legacy `wrapped_repo` reduces) + `worktree.sibling_parent`
 │   └── worktree-configs/
 │       └── <repo>.json        # per-wrapped-repo config (copy_files, apply_commits, preflight, etc.)
-├── <repo>                     # symlink → canonical clone (the trunk; name matches `wrapped_repo`)
+├── <repo>                     # symlink → canonical clone (one trunk per declared repo)
 ├── <slug-1>/                  # active worktree (git worktree add'd from the trunk)
 ├── <slug-2>/                  # another active worktree
 ├── ce.json                    # LEGACY composable.env config (deprecated — doppler is the default env layer); optional `composeProjectName: "<repo>"`
@@ -35,7 +35,9 @@ my-workbench/                  # the indusk project
 
 The wrapped repo's canonical clone lives elsewhere on disk (typically `~/code/<area>/<repo>`); the workbench's `<repo>` symlink points to it. The clone keeps its own `.git/`; the workbench keeps the `.indusk/`. Worktrees are created via `git worktree add` from inside the trunk symlink and land as siblings of the trunk.
 
-**Trunk vs worktrees**: identified by config (`worktree.wrapped_repo` names the trunk) and structurally (the trunk is a symlink; worktrees are real directories). Worktree slugs must not collide with the trunk's name.
+**Declared layout**: a repo entry may carry `path` (where its checkout lives) and `worktrees` (where its worktrees go), both relative to the workbench and both single clean segments. Absent means flat — the workbench root — so an existing workbench is untouched and nesting is opt-in per repo. `worktree list` then groups structurally from the declared directory rather than asking git who owns what, and anything on disk it cannot place renders under **Unattributed**, naming the worktrees inside it: declarations add structure and can never subtract.
+
+**Trunk vs worktrees**: a workbench declares its repos in `worktree.repos[]` (the legacy `worktree.wrapped_repo` reduces to a one-element list, so existing workbenches need no edit). Each declared repo gets its own trunk symlink at the workbench root; worktrees are real directories beside them. `indusk worktree list` renders one block per repo and attributes each worktree to its owning repo by asking git for `--git-common-dir` — not by guessing from the slug, because a wrong attribution reads exactly like a right one. Worktree slugs must not collide with any declared repo name. `docs/` is reserved at the workbench root (internal engagement docs), alongside `scripts/` and `env/`.
 
 ## When to enable
 
@@ -55,9 +57,9 @@ Four state-management commands, all run from the workbench root:
 
 ### `indusk worktree create <slug> [base-branch]`
 
-Creates a new worktree at `<workbench-root>/<slug>/`, branched off `<base-branch>` (default per `.indusk/worktree-configs/<wrapped_repo>.json`'s `base_branch`). Applies the config's `copy_files[]` and `append_files[]` declarations. Applies any `apply_commits[]` entries as **upstream-file-overlay** (full-file replacement via `git show <sha>:<file>` followed by `git update-index --skip-worktree`), NOT cherry-pick — the overlay files are invisible to `git status` / `git diff` / `git commit -a`. After setup, env is **auto-provisioned** (doppler extension, if configured) and the config's **`post_create[]`** shell commands run in order inside the new worktree — `pnpm install`, build, anything — so `create` yields a *runnable* worktree in one shot, not a bare checkout. A `post_create` command that exits non-zero stops the rest and prints what to re-run. Idempotent: invoking twice with the same `<slug>` exits non-zero with "worktree already exists at <path>".
+Creates a new worktree at `<workbench-root>/<slug>/`, branched off `<base-branch>` (default per `.indusk/worktree-configs/<repo>.json`'s `base_branch`, keyed by the resolved repo). Applies the config's `copy_files[]` and `append_files[]` declarations. Applies any `apply_commits[]` entries as **upstream-file-overlay** (full-file replacement via `git show <sha>:<file>` followed by `git update-index --skip-worktree`), NOT cherry-pick — the overlay files are invisible to `git status` / `git diff` / `git commit -a`. After setup, env is **auto-provisioned** (doppler extension, if configured) and the config's **`post_create[]`** shell commands run in order inside the new worktree — `pnpm install`, build, anything — so `create` yields a *runnable* worktree in one shot, not a bare checkout. A `post_create` command that exits non-zero stops the rest and prints what to re-run. Idempotent: invoking twice with the same `<slug>` exits non-zero with "worktree already exists at <path>".
 
-The `<repo>` argument from the multi-repo design is dropped — single-repo workbenches know their wrapped repo from `worktree.wrapped_repo` in `.indusk/config.json`.
+The `<repo>` argument is BACK (versioned-workbench): `indusk worktree create [repo] <slug> [base-branch]`. It is optional when the workbench declares exactly one repo; with several it is required, and omitting it fails naming the candidates rather than picking the first. A leading token counts as a repo only when the workbench actually declares it, so existing single-repo invocations keep their meaning.
 
 ### `indusk worktree refresh <slug>`
 
@@ -93,7 +95,7 @@ Examples (workbench is wrapping `numero`):
 - `pnpm wt numero lint` — cd to `<workbench>/numero/` (the trunk symlink), run `pnpm lint`
 - `pnpm wt cancel-polish ce dc:up local` — cd to `<workbench>/cancel-polish/`, run `pnpm ce dc:up local` (ce reads the worktree's env)
 
-The trunk is addressable by its repo name (`pnpm wt numero ...`). No `pnpm wt trunk` alias — keeps the surface minimal; the repo name is already in `worktree.wrapped_repo` config and stable.
+Each trunk is addressable by its repo name (`pnpm wt numero ...`). No `pnpm wt trunk` alias — keeps the surface minimal; the names are already in `worktree.repos[]` and stable.
 
 ### Composing with composable.env (legacy — deprecated in favor of doppler)
 

package/hooks/_hook-paths.js

@@ -107,18 +107,24 @@ function findGitPathFromCwd(cwd) {
  * against it fails even though the commit DID happen in a real git repo
  * inside the workbench.
  *
- * The fallback reads `${statePath}/.indusk/config.json` for the
- * `worktree.wrapped_repo` field. If present and the path exists, returns
- * the realpath of `${statePath}/${wrapped_repo}`. Otherwise returns null
- * (caller logs an actionable skip message naming `statePath`).
- *
- * Trade-off accepted: if the user committed in a SIBLING WORKTREE rather
- * than the wrapped repo, this resolves `gitPath` to the wrapped repo
- * (giving the eval agent the wrapped repo's HEAD, which may not be the
- * commit just made). That's a known incompleteness — Phase N+1 work
- * could read `tool_input.command` for a `cd <worktree>` prefix to
- * disambiguate. Until then, the wrapped-repo fallback is strictly better
- * than the pre-1.31.10 behavior of silently bailing every commit.
+ * The fallback reads `${statePath}/.indusk/config.json` for the declared repo
+ * set — `worktree.repos[]`, with the legacy `worktree.wrapped_repo` reducing
+ * to a one-element list. **Deliberate port of `lib/worktree/repos.ts`'s
+ * reduction**: a hook cannot import TypeScript, so the rule lives in two
+ * places and they must change together.
+ *
+ * With exactly ONE declared repo the behaviour is unchanged from 1.31.10.
+ *
+ * With MORE THAN ONE (versioned-workbench D6) the fallback is ambiguous, so it
+ * does not guess: it returns null, and the caller can name every declared repo
+ * via `declaredReposAt`. Picking the first would attribute a commit to the
+ * wrong repo, and a wrong attribution is indistinguishable from a right one in
+ * the eval record — a silent gap is recoverable, a confident wrong answer is
+ * not.
+ *
+ * Trade-off accepted (single-repo case, unchanged): if the user committed in a
+ * SIBLING WORKTREE rather than the wrapped repo, this resolves `gitPath` to the
+ * wrapped repo, whose HEAD may not be the commit just made.
  *
  * @param {string | null} statePath
  * @returns {string | null}
@@ -133,9 +139,11 @@ function findGitPathFromWorkbenchConfig(statePath) {
 	} catch {
 		return null;
 	}
-	const wrappedRepo = config?.worktree?.wrapped_repo;
-	if (!wrappedRepo || typeof wrappedRepo !== "string") return null;
-	const candidate = resolve(statePath, wrappedRepo);
+	const declared = declaredRepoNames(config);
+	// Ambiguous: more than one repo could hold this commit. Refuse rather than
+	// attribute it to whichever happens to be declared first.
+	if (declared.length !== 1) return null;
+	const candidate = resolve(statePath, declared[0]);
 	if (!existsSync(candidate)) return null;
 	try {
 		return realpathSync(candidate);
@@ -144,6 +152,61 @@ function findGitPathFromWorkbenchConfig(statePath) {
 	}
 }
 
+/**
+ * The declared repo names, singular reduced into plural.
+ *
+ * Deliberate port of `readWorkbenchRepos` in `src/lib/worktree/repos.ts` —
+ * hooks are plain JS and cannot import the TS module. Change both together.
+ * Name-only: the hook never needs remotes.
+ *
+ * @param {unknown} config
+ * @returns {string[]}
+ */
+function declaredRepoNames(config) {
+	const worktree = config && typeof config === "object" ? config.worktree : null;
+	if (!worktree || typeof worktree !== "object") return [];
+	const raw = Array.isArray(worktree.repos)
+		? worktree.repos
+		: typeof worktree.wrapped_repo === "string"
+			? [{ name: worktree.wrapped_repo }]
+			: [];
+	const seen = new Set();
+	const names = [];
+	for (const entry of raw) {
+		if (!entry || typeof entry !== "object") continue;
+		const name = entry.name;
+		if (typeof name !== "string") continue;
+		const clean =
+			name.trim() !== "" &&
+			name !== "." &&
+			name !== ".." &&
+			!name.includes("/") &&
+			!name.includes("\\");
+		if (!clean || seen.has(name)) continue;
+		seen.add(name);
+		names.push(name);
+	}
+	return names;
+}
+
+/**
+ * Every declared repo name at a workbench root, so a caller that refuses can
+ * SAY what it could not choose between.
+ *
+ * @param {string | null} statePath
+ * @returns {string[]}
+ */
+export function declaredReposAt(statePath) {
+	if (!statePath) return [];
+	const configPath = resolve(statePath, ".indusk/config.json");
+	if (!existsSync(configPath)) return [];
+	try {
+		return declaredRepoNames(JSON.parse(readFileSync(configPath, "utf-8")));
+	} catch {
+		return [];
+	}
+}
+
 /**
  * Resolve both the InDusk state path and the git path for a given cwd. Either
  * may be null:

package/hooks/workbench-sync.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * workbench-sync.js — PostToolUse hook (Edit|Write).
+ *
+ * The trigger half of workbench sync. The mechanism lives in
+ * `lib/worktree/sync.ts` and is shared with `indusk workbench sync`; this only
+ * decides WHEN to call it. Keeping the two apart means the trigger can become
+ * a watcher daemon later without touching the mechanism.
+ *
+ * THREE GUARDS, and the first is the important one:
+ *
+ *   1. WORKBENCH ONLY. A normal-mode project keeps `.indusk/` inside its own
+ *      product repo, so auto-committing there would commit a developer's
+ *      half-finished source on every edit. dusk itself is such a project. This
+ *      hook must be inert anywhere `worktree.shape` is not "workbench".
+ *   2. DEBOUNCED. Edit/Write fires constantly; a push per keystroke-burst is
+ *      pointless network traffic. The stamp lives under the GITDIR, never the
+ *      working tree — per-machine state that must not become a tracked file
+ *      (the worktree extension keeps its overlay state the same way).
+ *   3. NEVER BLOCKS. Always exits 0. A sync failure must not fail a developer's
+ *      edit, and an unreachable remote is a normal condition, not an error.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveStateAndGitPaths } from "./_hook-paths.js";
+
+/** Seconds between syncs. Edits burst; the remote does not need every burst. */
+const DEBOUNCE_SECONDS = 20;
+
+function isWorkbench(root) {
+	try {
+		const cfg = JSON.parse(readFileSync(join(root, ".indusk", "config.json"), "utf-8"));
+		return cfg?.worktree?.shape === "workbench";
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Stamp path — under the gitdir when there is one, which keeps it untracked by
+ * construction rather than by a rule.
+ *
+ * CHICKEN-AND-EGG: a workbench that has never been git-initialized has no
+ * gitdir, and the only thing that git-inits a workbench is `sync` itself. A
+ * null here used to mean "not due", so exactly the workbenches that most need
+ * their first sync were the ones that never got one. The fallback is inside
+ * `.indusk/`, which every workbench has and which the managed ignore covers.
+ */
+function stampPath(root) {
+	const r = spawnSync("git", ["rev-parse", "--absolute-git-dir"], { cwd: root, encoding: "utf-8" });
+	if (r.status === 0) return join(r.stdout.trim(), "indusk-sync-stamp");
+	return join(root, ".indusk", "sync-stamp");
+}
+
+function dueForSync(stamp) {
+	if (!stamp) return true;
+	if (!existsSync(stamp)) return true;
+	try {
+		return (Date.now() - statSync(stamp).mtimeMs) / 1000 >= DEBOUNCE_SECONDS;
+	} catch {
+		return true;
+	}
+}
+
+function touch(stamp) {
+	try {
+		if (existsSync(stamp)) {
+			const now = new Date();
+			utimesSync(stamp, now, now);
+		} else {
+			writeFileSync(stamp, "workbench sync debounce stamp\n");
+		}
+	} catch {
+		// A stamp we cannot write means we sync more often than intended —
+		// noisy, never wrong. Silence is the correct response.
+	}
+}
+
+async function main() {
+	let event = {};
+	try {
+		event = JSON.parse(readFileSync(0, "utf-8") || "{}");
+	} catch {
+		process.exit(0);
+	}
+
+	const { statePath } = resolveStateAndGitPaths(event.cwd ?? process.cwd());
+	if (!statePath) process.exit(0);
+
+	// Guard 1 — the load-bearing one.
+	if (!isWorkbench(statePath)) process.exit(0);
+
+	// Guard 2.
+	const stamp = stampPath(statePath);
+	if (!dueForSync(stamp)) process.exit(0);
+	touch(stamp);
+
+	// Guard 3: spawn detached and never wait. A sync must not add latency to a
+	// developer's edit, and its outcome must not decide whether the edit stood.
+	const bin = process.env.INDUSK_BIN ?? "indusk";
+	try {
+		const child = spawnSync(bin, ["workbench", "sync"], {
+			cwd: statePath,
+			encoding: "utf-8",
+			timeout: 25_000,
+		});
+		if (child.status !== 0 && child.stderr) {
+			// Reported, not raised. The hook still exits 0.
+			process.stderr.write(`[workbench-sync] ${child.stderr.trim().split("\n")[0]}\n`);
+		}
+	} catch {
+		// ignore
+	}
+	process.exit(0);
+}
+
+main();