feat(droid-control): decouple tctl launch --cwd from --repo-root + degraded-tail recipe (MB-18)

--cwd now sets the child working directory independently on both
backends (defaulting to --repo-root when unset) and is recorded in
launch provenance, replacing the sh -c 'cd ... && exec' shim. Documents
the degraded-tail repro recipe (slow PreToolUse hook in a scratch
project) in the droid-control skill.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: factory-ain3sh

plugins/droid-control/ARCHITECTURE.md

@@ -117,7 +117,7 @@ Terminal workflows use `bin/tctl` as the only launch/control boundary. It hides
 | `tuistory` | Virtual PTY sessions, deterministic waits/snapshots, asciinema recording at launch. | Fast TUI automation and most demo captures. |
 | `true-input` | Headless Wayland compositor, real terminal emulator, native key injection, PTY log/screenshot/video capture. | Real terminal rendering or keyboard-encoding proof. |
 
-`tctl` also enforces Droid CLI launch invariants. `droid-dev` sessions must provide `--repo-root`, which lets `tctl` set `DROID_DEV_REPO_ROOT` and record provenance for the captured branch and commit.
+`tctl` also enforces Droid CLI launch invariants. `droid-dev` sessions must provide `--repo-root`, which lets `tctl` set `DROID_DEV_REPO_ROOT` and record provenance for the captured branch and commit. `--cwd` is independent: it sets the child's working directory (recorded in provenance) and defaults to `--repo-root` when unset, so a session can run one worktree's code from a different project directory.
 
 Browser/Electron and native-desktop workflows intentionally do **not** go through `tctl`. They have their own control boundaries: `agent-browser`'s persistent Playwright daemon for DOM snapshots, screenshots, and CDP-connected apps; `cua-driver`'s daemon for accessibility trees and per-`(pid, window_id)` element caches on desktop GUIs.
 

plugins/droid-control/bin/tctl

@@ -31,7 +31,8 @@ Launch options:
   --terminal <name>          Override terminal for true-input
   --cols <n>                 Columns (default: 120)
   --rows <n>                 Rows (default: 36)
-  --cwd <path>               Working directory (tuistory)
+  --cwd <path>               Working directory for the child, both backends
+                             (default: --repo-root when set)
   --repo-root <path>         Git worktree root for provenance + droid-dev launches
   --env <KEY=VALUE>          Environment variable (repeatable)
   --tmux                     Wrap the command in tmux with RGB-safe tuistory defaults
@@ -319,21 +320,25 @@ require_git_worktree_root() {
 write_provenance() {
   local session="$1"
   local repo_root="$2"
+  local cwd="$3"
   local file branch commit
   file="$(provenance_file "$session")"
 
-  if [[ -z "$repo_root" ]]; then
+  if [[ -z "$repo_root" && -z "$cwd" ]]; then
     rm -f "$file"
     return 0
   fi
 
-  branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || printf 'unknown')"
-  commit="$(git -C "$repo_root" rev-parse HEAD 2>/dev/null || printf 'unknown')"
-  cat > "$file" <<PROVENANCE
-repo_root=$repo_root
-branch=$branch
-commit=$commit
-PROVENANCE
+  {
+    if [[ -n "$repo_root" ]]; then
+      branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || printf 'unknown')"
+      commit="$(git -C "$repo_root" rev-parse HEAD 2>/dev/null || printf 'unknown')"
+      printf 'repo_root=%s\nbranch=%s\ncommit=%s\n' "$repo_root" "$branch" "$commit"
+    fi
+    if [[ -n "$cwd" ]]; then
+      printf 'cwd=%s\n' "$cwd"
+    fi
+  } > "$file"
 }
 
 resolve_backend() {
@@ -937,9 +942,12 @@ cmd_launch() {
 
   if [[ -n "$repo_root" ]]; then
     require_git_worktree_root "$repo_root"
-    if [[ -n "$cwd" && "$cwd" != "$repo_root" ]]; then
-      die "--cwd must match --repo-root when --repo-root is set"
-    fi
+  fi
+
+  if [[ -n "$cwd" ]]; then
+    [[ "$cwd" = /* ]] || die "--cwd must be an absolute path: $cwd"
+    [[ -d "$cwd" ]] || die "--cwd does not exist: $cwd"
+  elif [[ -n "$repo_root" ]]; then
     cwd="$repo_root"
   fi
 
@@ -977,7 +985,7 @@ cmd_launch() {
   WARMED_UP="0"
   REPO_ROOT="$repo_root"
   save_session_state "$session"
-  write_provenance "$session" "$repo_root"
+  write_provenance "$session" "$repo_root" "$cwd"
 
   if [[ "$BACKEND" == "tuistory" ]]; then
     launch_tuistory "$session" "$cols" "$rows" "$record_path"

plugins/droid-control/skills/droid-cli/SKILL.md

@@ -72,6 +72,7 @@ $TCTL -s demo press tab
 - **No per-branch builds.** One `npm run setup` (in any checkout) installs the shim. Switching branches is instant via `--repo-root`.
 - **Prerequisite:** The target worktree must have `node_modules` installed (`npm install` at the repo root). If missing, the bun launch fails.
 - **`tctl --repo-root`** sets `DROID_DEV_REPO_ROOT` automatically and pins the session to that worktree.
+- **`tctl --cwd`** is independent of `--repo-root`: run droid against one worktree's code while sitting in a different project directory (e.g., a scratch project with its own `.factory/settings.json` hooks). Defaults to `--repo-root` when unset.
 
 ### `droid-dev`
 

plugins/droid-control/skills/droid-control/SKILL.md

@@ -162,6 +162,44 @@ Terminal drivers use the unified `tctl` wrapper. agent-browser and desktop-contr
 
 Drivers can be combined in one workflow — e.g., `tctl` for a CLI and `agent-browser` for a web UI it interacts with.
 
+## Degraded-tail repro recipe (droid TUI)
+
+Deterministic recipe for reproducing degraded transcript tails in the droid CLI — stranded live tool rows and queued steering messages — without waiting for a slow model turn. The trick: a slow `PreToolUse` hook pins a tool in its executing state for as long as you need.
+
+1. **Scratch project.** Create a throwaway directory (never a real repo — the hook fires on every matching tool call) with a project-local hook that sleeps:
+
+   ```bash
+   SCRATCH="$(mktemp -d /tmp/degraded-tail-XXXXXX)"
+   mkdir -p "$SCRATCH/.factory"
+   cat > "$SCRATCH/.factory/settings.json" <<'JSON'
+   {
+     "hooks": {
+       "PreToolUse": [
+         {
+           "matcher": "TodoWrite",
+           "hooks": [{ "type": "command", "command": "sleep 120" }]
+         }
+       ]
+     }
+   }
+   JSON
+   ```
+
+   Pick a sleep long enough to interact mid-hook (60–180s) and a matcher for a tool the prompt will reliably trigger (`TodoWrite` fires on any multi-step ask).
+
+2. **Launch with `--cwd` pointed at the scratch project** — `--repo-root` stays on your dev worktree so `droid-dev` provenance still records the code under test:
+
+   ```bash
+   $TCTL launch "droid-dev" -s ${RUN_ID}-tail --cwd "$SCRATCH" \
+     --repo-root /abs/path/to/dev/worktree --record ${RUN_DIR}/tail.cast
+   ```
+
+3. **Trigger the hook**, then degrade the tail while the tool row shows executing:
+   - **Interrupt mid-hook** (`press escape`) — strands the live tool row: it never resolves to a completed/canceled state in the transcript tail.
+   - **Steer mid-hook** (`type "..."` + `press enter`) — the steering message queues behind the executing tool instead of interleaving.
+
+**Gotcha:** dev-scope hook settings can silently disable project hooks. If the tool completes instantly, run `/hooks` in the session and check the "Hooks enabled" toggle before debugging the hook config itself.
+
 ## Prerequisites
 
 | Stage | Platform | Required | Optional |

plugins/droid-control/skills/tuistory/SKILL.md

@@ -59,7 +59,7 @@ $TCTL -s demo close
 | `snapshot [--trim]` | Print cleaned text (`--trim` strips trailing blanks) |
 | `close` | Tear down session |
 
-Launch options: `--cols <n>`, `--rows <n>`, `--cwd <path>`, `--env KEY=VALUE`, `--record <path>`.
+Launch options: `--cols <n>`, `--rows <n>`, `--cwd <path>` (child working directory; defaults to `--repo-root` when set), `--env KEY=VALUE`, `--record <path>`.
 
 ## Recording