From 7e18de16749b3a5338d57f7c4dc4d6d9e7a0dbbe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Igor=20=C5=A0=C4=87eki=C4=87?= <iscekic@protonmail.com>
Date: Tue, 28 Jul 2026 15:43:07 +0200
Subject: [PATCH 1/4] fix(mobile): unwedge Android E2E emulator claims and
 preflight
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three defects made Android E2E rounds fail for reasons agents could not
diagnose or recover from:

- Android device claims treated an ADB serial as a device identity, but
  serials are recycled emulator ports. A claim was only reclaimable once
  its owning worktree was deleted, and worktrees outlive runs by days, so
  a claim left behind by a dead emulator wedged that serial permanently.
  emulator-5554 and emulator-5556 were both wedged this way on the shared
  machine — the first two serials any emulator boot takes. Claims now
  record the guest kernel boot id, so a foreign claim holds a serial only
  while it names the instance currently answering on it.

- The shared E2E preflight accepted only `iOS Bundled` as Metro readiness
  evidence. On Android the alternative `Starting Metro Bundler` line
  scrolls out of the captured window on a long-lived stack, so preflight
  started failing with "Metro has not reached a usable state" the longer a
  session ran — exactly when mid-test recovery reruns login.sh. It also
  probed the Metro manifest as iOS regardless of the target platform.

- dispatch-role.sh resolved its target with an untargeted
  `tmux display-message -p '#S'`, which answers with the server's current
  session rather than the caller's. A dispatcher outside tmux silently
  dropped role windows into an unrelated session; freshly created
  kilo-e2e-android-* emulator sessions were the usual victim, and device
  cleanup then killed those foreign agents. The session is now resolved
  through $TMUX_PANE, falling back to an own session instead of a guess.

Also documents the one-time `expo prebuild --platform android` that
`build` needs in a fresh worktree, since apps/mobile/android/ is
git-ignored and `build` cannot generate it itself.
---
 .kilo_workflow/WORKFLOW.md       |  2 +-
 .kilo_workflow/dispatch-role.sh  | 17 +++++--
 apps/mobile/e2e/AGENTS.md        |  2 +
 apps/mobile/e2e/preflight.sh     |  6 ++-
 dev/local/mobile-android.test.ts | 87 +++++++++++++++++++++++++++++---
 dev/local/mobile-android.ts      | 50 ++++++++++++++----
 6 files changed, 142 insertions(+), 22 deletions(-)

diff --git a/.kilo_workflow/WORKFLOW.md b/.kilo_workflow/WORKFLOW.md
index 713d0e8dad..06202ef4cb 100644
--- a/.kilo_workflow/WORKFLOW.md
+++ b/.kilo_workflow/WORKFLOW.md
@@ -55,7 +55,7 @@ The cwd/worktree is always the **cloud** worktree, even when the slice edits a s
 
 What the script encodes (details in `learnings/`):
 
-- tmux wrapping — harness command timeouts kill bare long runs. The `e2e-verifier` gets its **own tmux session** (E2E slots are owned and auto-reclaimed by session name; a window-named owner leaks or shares slots); other roles run as windows in the dispatcher's session. Names are `<section>-<role>-<label>`, logs `$SCRATCH/<role>-<label>.log`.
+- tmux wrapping — harness command timeouts kill bare long runs. The `e2e-verifier` gets its **own tmux session** (E2E slots are owned and auto-reclaimed by session name; a window-named owner leaks or shares slots); other roles run as windows in the dispatcher's session, resolved through `$TMUX_PANE`. A dispatcher that is not itself inside tmux has no such session, so its roles get their own sessions too — never a guessed one. Names are `<section>-<role>-<label>`, logs `$SCRATCH/<role>-<label>.log`.
 - Full `KILO_*`/`OPENCODE*` env strip — a dispatcher running inside kilo poisons nested runs otherwise (see `learnings/nested-kilo-run-env-poisoning.md`).
 - Output redirected, never piped (`| tee` makes `$?` report the pipe's exit, not kilo's), with `EXITCODE=$?` appended as the log's last line.
 
diff --git a/.kilo_workflow/dispatch-role.sh b/.kilo_workflow/dispatch-role.sh
index 939c925439..b34243fe55 100755
--- a/.kilo_workflow/dispatch-role.sh
+++ b/.kilo_workflow/dispatch-role.sh
@@ -16,7 +16,7 @@
 #
 # The e2e-verifier gets its own tmux session (device slots are owned and
 # auto-reaped by session name); every other role runs as a window in the
-# caller's session.
+# caller's session, or in its own session when the caller is not inside tmux.
 set -euo pipefail
 
 ROLE=${1:?role} SECTION=${2:?section} LABEL=${3:?label} WT=${4:?worktree} SCRATCH=${5:?scratch} MSG=${6:?message}
@@ -35,9 +35,20 @@ CMD="cd $(printf '%q' "$WT") && env $STRIP kilo run $(printf '%q' "$MSG") --agen
 for arg in "$@"; do CMD+=" $(printf '%q' "$arg")"; done
 CMD+=" > $(printf '%q' "$LOG") 2>&1; echo EXITCODE=\$? >> $(printf '%q' "$LOG")"
 
-if [ "$ROLE" = "e2e-verifier" ]; then
+# Resolve the caller's session through this pane. An untargeted
+# `tmux display-message -p '#S'` answers with the SERVER's current session —
+# the most recently active one — so a dispatcher running outside tmux (a
+# harness shell, a stripped kilo env) silently drops its window into an
+# unrelated session. A freshly created `kilo-e2e-android-*` emulator session
+# is the usual victim, and it gets killed wholesale on device cleanup.
+CALLER_SESSION=""
+if [ -n "${TMUX_PANE:-}" ]; then
+  CALLER_SESSION=$(tmux display-message -p -t "$TMUX_PANE" '#S' 2>/dev/null || true)
+fi
+
+if [ "$ROLE" = "e2e-verifier" ] || [ -z "$CALLER_SESSION" ]; then
   tmux new-session -d -s "$NAME" "$CMD"
 else
-  tmux new-window -d -t "$(tmux display-message -p '#S')" -n "$NAME" "$CMD"
+  tmux new-window -d -t "$CALLER_SESSION" -n "$NAME" "$CMD"
 fi
 echo "$LOG"
diff --git a/apps/mobile/e2e/AGENTS.md b/apps/mobile/e2e/AGENTS.md
index 8593cab2c7..aa94936602 100644
--- a/apps/mobile/e2e/AGENTS.md
+++ b/apps/mobile/e2e/AGENTS.md
@@ -257,6 +257,8 @@ apps/mobile/e2e/login.sh <serial>
 
 `build` installs a validated cached APK when the Android native fingerprint and toolchain match. Never install an APK from another output path or invoke Gradle directly. Reinstall via `build <serial>` only when the native fingerprint changed, never to reset app state.
 
+`build` reads the generated Android project, and `apps/mobile/android/` is git-ignored — a fresh worktree has none. Run `npx expo prebuild --platform android` in `apps/mobile` once before the first `build`; it is codegen only, needs no wrapper, and a missing project is the one failure `build` cannot fix itself.
+
 `login.sh` and `logout.sh` accept an iOS simulator UDID or an Android ADB serial. On Android, `login.sh`'s shared preflight verifies the claim, applies both `adb reverse` mappings (the `nextjs` service's API port and the `mobile` service's Metro port, both from `pnpm dev:status --json` — there is no service named `metro`), and opens the dev-client deep link itself. On the primary path no manual reverse or `am start` is needed.
 
 ### Mid-test recovery
diff --git a/apps/mobile/e2e/preflight.sh b/apps/mobile/e2e/preflight.sh
index 2095c61d7f..d2d0e552d8 100755
--- a/apps/mobile/e2e/preflight.sh
+++ b/apps/mobile/e2e/preflight.sh
@@ -51,7 +51,9 @@ if ! grep -Fq "Starting project at $REPO_ROOT/apps/mobile" <<<"$MOBILE_LOG"; the
   printf 'Metro does not belong to this worktree: %s\n' "$REPO_ROOT" >&2
   exit 1
 fi
-if ! grep -Eq 'iOS Bundled|Starting Metro Bundler' <<<"$MOBILE_LOG"; then
+# "Starting Metro Bundler" scrolls out of the captured window on a long-lived
+# stack, leaving the per-platform bundle lines as the only readiness evidence.
+if ! grep -Eq '(iOS|Android) Bundled|Starting Metro Bundler' <<<"$MOBILE_LOG"; then
   printf 'Metro has not reached a usable state for %s\n' "$REPO_ROOT" >&2
   exit 1
 fi
@@ -79,7 +81,7 @@ NODE
 METRO_URL="http://${MOBILE_HOST}:${METRO_PORT}"
 MANIFEST="$(mktemp)"
 trap 'rm -f "$SESSION_PROBE" "$MANIFEST"' EXIT
-curl -sS -H 'expo-platform: ios' -H 'expo-protocol-version: 1' \
+curl -sS -H "expo-platform: $PLATFORM" -H 'expo-protocol-version: 1' \
   -H 'accept: application/expo+json,application/json' "$METRO_URL" >"$MANIFEST"
 node - "$MANIFEST" "http://${MOBILE_HOST}:${EXPECTED_API_PORT}" "$REPO_ROOT" <<'NODE'
 const fs = require('node:fs');
diff --git a/dev/local/mobile-android.test.ts b/dev/local/mobile-android.test.ts
index ec4ab8a5af..41b1249d66 100644
--- a/dev/local/mobile-android.test.ts
+++ b/dev/local/mobile-android.test.ts
@@ -45,14 +45,14 @@ test('serializes stale Android claim replacement with concurrent claim attempts'
   let attemptedConcurrentClaim = false;
 
   try {
-    const claim = claimAndroidDevice(serial, firstWorktree, {
+    const claim = claimAndroidDevice(serial, firstWorktree, 'boot-id-of-live-emulator', {
       fileOperations: {
         readFileSync: (candidate, encoding) => {
           const value = fs.readFileSync(candidate, encoding);
           if (candidate === filePath && !attemptedConcurrentClaim) {
             attemptedConcurrentClaim = true;
             assert.throws(
-              () => claimAndroidDevice(serial, secondWorktree),
+              () => claimAndroidDevice(serial, secondWorktree, 'boot-id-of-live-emulator'),
               /claim is being updated concurrently/
             );
           }
@@ -72,16 +72,89 @@ test('serializes stale Android claim replacement with concurrent claim attempts'
   }
 });
 
+test('reclaims a serial whose emulator instance is gone, even from a live worktree', () => {
+  const serial = `test-recycled-${process.pid}-${Date.now()}`;
+  const deadInstanceWorktree = fs.mkdtempSync(path.join(os.tmpdir(), 'kilo-worktree-dead-'));
+  const worktreeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'kilo-worktree-live-'));
+  const filePath = path.join(os.tmpdir(), 'kilo-mobile-android-claims', `${serial}.json`);
+
+  try {
+    claimAndroidDevice(serial, deadInstanceWorktree, 'boot-id-of-dead-emulator');
+
+    // Same serial, new emulator instance: the old claim names a worktree that
+    // still exists, so only the boot id can tell the port was recycled.
+    const claim = claimAndroidDevice(serial, worktreeRoot, 'boot-id-of-live-emulator');
+
+    assert.equal(claim.worktreeRoot, worktreeRoot);
+    assert.equal(claim.bootId, 'boot-id-of-live-emulator');
+    assert.equal(JSON.parse(fs.readFileSync(filePath, 'utf8')).worktreeRoot, worktreeRoot);
+  } finally {
+    fs.rmSync(filePath, { force: true });
+    fs.rmSync(`${filePath}.lock`, { recursive: true, force: true });
+    fs.rmSync(deadInstanceWorktree, { recursive: true, force: true });
+    fs.rmSync(worktreeRoot, { recursive: true, force: true });
+  }
+});
+
+test('reclaims a serial from a legacy claim that predates boot ids', () => {
+  const serial = `test-legacy-${process.pid}-${Date.now()}`;
+  const otherWorktree = fs.mkdtempSync(path.join(os.tmpdir(), 'kilo-worktree-other-'));
+  const worktreeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'kilo-worktree-live-'));
+  const filePath = path.join(os.tmpdir(), 'kilo-mobile-android-claims', `${serial}.json`);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(
+    filePath,
+    JSON.stringify({
+      serial,
+      worktreeRoot: otherWorktree,
+      claimedAt: new Date().toISOString(),
+      claimId: 'legacy',
+      status: 'ready',
+    })
+  );
+
+  try {
+    const claim = claimAndroidDevice(serial, worktreeRoot, 'boot-id-of-live-emulator');
+    assert.equal(claim.worktreeRoot, worktreeRoot);
+  } finally {
+    fs.rmSync(filePath, { force: true });
+    fs.rmSync(`${filePath}.lock`, { recursive: true, force: true });
+    fs.rmSync(otherWorktree, { recursive: true, force: true });
+    fs.rmSync(worktreeRoot, { recursive: true, force: true });
+  }
+});
+
+test('refreshes an own claim when the emulator instance changed', () => {
+  const serial = `test-reboot-${process.pid}-${Date.now()}`;
+  const worktreeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'kilo-worktree-'));
+  const filePath = path.join(os.tmpdir(), 'kilo-mobile-android-claims', `${serial}.json`);
+
+  try {
+    const first = claimAndroidDevice(serial, worktreeRoot, 'boot-id-one');
+    const second = claimAndroidDevice(serial, worktreeRoot, 'boot-id-one');
+    assert.equal(second.claimId, first.claimId);
+
+    const rebooted = claimAndroidDevice(serial, worktreeRoot, 'boot-id-two');
+    assert.equal(rebooted.bootId, 'boot-id-two');
+    assert.equal(JSON.parse(fs.readFileSync(filePath, 'utf8')).bootId, 'boot-id-two');
+  } finally {
+    fs.rmSync(filePath, { force: true });
+    fs.rmSync(`${filePath}.lock`, { recursive: true, force: true });
+    fs.rmSync(worktreeRoot, { recursive: true, force: true });
+  }
+});
+
 test('preserves an active Android claim owned by another worktree', () => {
   const serial = `test-active-${process.pid}-${Date.now()}`;
   const firstWorktree = fs.mkdtempSync(path.join(os.tmpdir(), 'kilo-worktree-one-'));
   const secondWorktree = fs.mkdtempSync(path.join(os.tmpdir(), 'kilo-worktree-two-'));
+  const bootId = 'boot-id-of-live-emulator';
 
   try {
-    claimAndroidDevice(serial, firstWorktree);
+    claimAndroidDevice(serial, firstWorktree, bootId);
 
     assert.throws(
-      () => claimAndroidDevice(serial, secondWorktree),
+      () => claimAndroidDevice(serial, secondWorktree, bootId),
       new RegExp(`claimed by ${firstWorktree}`)
     );
     assert.throws(
@@ -109,7 +182,7 @@ test('recovers an orphaned Android claim mutation lock', () => {
   fs.utimesSync(mutationLockPath, settledTime, settledTime);
 
   try {
-    const claim = claimAndroidDevice(serial, worktreeRoot);
+    const claim = claimAndroidDevice(serial, worktreeRoot, 'boot-id-of-live-emulator');
     assert.equal(claim.worktreeRoot, worktreeRoot);
     releaseAndroidDevice(serial, worktreeRoot);
   } finally {
@@ -125,7 +198,7 @@ test('creates an explicit ready Android claim', () => {
   const filePath = path.join(os.tmpdir(), 'kilo-mobile-android-claims', `${serial}.json`);
 
   try {
-    const claim = claimAndroidDevice(serial, worktreeRoot);
+    const claim = claimAndroidDevice(serial, worktreeRoot, 'boot-id-of-live-emulator');
     assert.equal(claim.status, 'ready');
     assert.equal(typeof claim.claimId, 'string');
     assert.ok(claim.claimId.length > 0);
@@ -148,7 +221,7 @@ test('upgrades a same-worktree legacy Android claim to ready', () => {
   );
 
   try {
-    const claim = claimAndroidDevice(serial, worktreeRoot);
+    const claim = claimAndroidDevice(serial, worktreeRoot, 'boot-id-of-live-emulator');
     assert.equal(claim.status, 'ready');
     assert.equal(JSON.parse(fs.readFileSync(filePath, 'utf8')).status, 'ready');
   } finally {
diff --git a/dev/local/mobile-android.ts b/dev/local/mobile-android.ts
index 010fc54128..d7a9de814f 100644
--- a/dev/local/mobile-android.ts
+++ b/dev/local/mobile-android.ts
@@ -37,6 +37,11 @@ type DeviceClaim = {
   claimedAt: string;
   claimId: string;
   status: 'ready';
+  // Linux boot id of the emulator instance the claim was taken against. ADB
+  // serials are recycled ports, not device identities: the next emulator to
+  // boot takes emulator-5554 again, so the serial alone cannot tell a live
+  // claim from one left behind by a long-dead instance.
+  bootId: string;
 };
 type ClaimOptions = {
   fileOperations?: {
@@ -150,6 +155,18 @@ function getAndroidSerials(env: AndroidEnvironment): string[] {
     .map(([serial]) => serial);
 }
 
+// Identity of the running emulator instance, stable for its whole life and
+// regenerated by the guest kernel on every boot.
+function readBootId(env: AndroidEnvironment, serial: string): string {
+  const bootId = execFileSync(
+    env.adb,
+    ['-s', serial, 'shell', 'cat', '/proc/sys/kernel/random/boot_id'],
+    { encoding: 'utf8', env: androidProcessEnv(env) }
+  ).trim();
+  if (!bootId) throw new Error(`Unable to read the boot id of ${serial}`);
+  return bootId;
+}
+
 function claimPath(serial: string): string {
   return path.join(
     os.tmpdir(),
@@ -166,6 +183,7 @@ function withClaimMutationLock<T>(filePath: string, mutate: () => T): T {
 function claimAndroidDevice(
   serial: string,
   worktreeRoot: string,
+  bootId: string,
   options?: ClaimOptions
 ): DeviceClaim {
   const filePath = claimPath(serial);
@@ -175,13 +193,22 @@ function claimAndroidDevice(
       const readFileSync = options?.fileOperations?.readFileSync ?? fs.readFileSync;
       const claim = JSON.parse(readFileSync(filePath, 'utf8')) as Partial<DeviceClaim>;
       if (claim.worktreeRoot === worktreeRoot) {
-        if (claim.status === 'ready' && typeof claim.claimId === 'string')
+        if (
+          claim.status === 'ready' &&
+          typeof claim.claimId === 'string' &&
+          claim.bootId === bootId
+        )
           return claim as DeviceClaim;
-        const upgraded = buildReadyClaim(serial, worktreeRoot);
+        const upgraded = buildReadyClaim(serial, worktreeRoot, bootId);
         fs.writeFileSync(filePath, JSON.stringify(upgraded));
         return upgraded;
       }
-      if (fs.existsSync(claim.worktreeRoot))
+      // A foreign claim only holds this serial while it names the emulator
+      // instance currently answering on it. Claims from earlier instances, and
+      // claims written before boot ids were recorded, are stale — their
+      // worktree usually still exists on disk, so worktree liveness alone
+      // would wedge the serial forever.
+      if (claim.bootId === bootId && directoryExists(claim.worktreeRoot))
         throw new Error(`${serial} is claimed by ${claim.worktreeRoot}`);
       fs.rmSync(filePath, { force: true });
     } catch (error) {
@@ -193,19 +220,24 @@ function claimAndroidDevice(
         throw error;
       }
     }
-    const claim = buildReadyClaim(serial, worktreeRoot);
+    const claim = buildReadyClaim(serial, worktreeRoot, bootId);
     fs.writeFileSync(filePath, JSON.stringify(claim), { flag: 'wx' });
     return claim;
   });
 }
 
-function buildReadyClaim(serial: string, worktreeRoot: string): DeviceClaim {
+function directoryExists(candidate: unknown): boolean {
+  return typeof candidate === 'string' && fs.existsSync(candidate);
+}
+
+function buildReadyClaim(serial: string, worktreeRoot: string, bootId: string): DeviceClaim {
   return {
     serial,
     worktreeRoot,
     claimedAt: new Date().toISOString(),
     claimId: `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`,
     status: 'ready',
+    bootId,
   };
 }
 
@@ -288,11 +320,11 @@ async function main(): Promise<void> {
     return;
   }
   if (command === 'claim') {
-    const requested = args[0];
-    const serial = requested ?? getAndroidSerials(env)[0];
-    if (!serial || !getAndroidSerials(env).includes(serial))
+    const serials = getAndroidSerials(env);
+    const serial = args[0] ?? serials[0];
+    if (!serial || !serials.includes(serial))
       throw new Error('No connected Android device is available');
-    console.log(JSON.stringify(claimAndroidDevice(serial, worktreeRoot)));
+    console.log(JSON.stringify(claimAndroidDevice(serial, worktreeRoot, readBootId(env, serial))));
     return;
   }
   if (command === 'release') {

From c6c2be489ca8720ba41415367fbb90283c237ce4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Igor=20=C5=A0=C4=87eki=C4=87?= <iscekic@protonmail.com>
Date: Tue, 28 Jul 2026 15:50:13 +0200
Subject: [PATCH 2/4] fix(workflow): stop the untargeted tmux session lookup at
 every caller
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

dispatch-role.sh was only one of three places using
`tmux display-message -p '#S'` without a target, which answers with the
tmux server's current session rather than the caller's:

- WORKFLOW.md told the starter to launch planners into that session, so
  planner windows can be filed under an unrelated section the same way
  role windows were.
- The e2e-verifier definition used it to name the owner of its device
  slot. That is the worst case: the slot ends up owned by another
  session's name and is reclaimed when that session dies while the
  verifier is still driving a device. The machine then over-subscribes
  past its three slots, and concurrent emulator boots and native builds
  start timing out — read as flaky emulators, not as a slot leak.

Both now resolve through `$TMUX_PANE`, and say what to do when it is
unset (own session for the planner; test-environment blocker for the
verifier) instead of guessing a target.

e2e-slot.sh now rejects an owner that is not a live tmux session, so a
window name or a misread session name fails loudly at acquire time
instead of booking a slot that is reapable the moment it is written.
---
 .kilo/agent/e2e-verifier.md |  2 +-
 .kilo_workflow/WORKFLOW.md  |  2 +-
 .kilo_workflow/e2e-slot.sh  | 11 +++++++++++
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/.kilo/agent/e2e-verifier.md b/.kilo/agent/e2e-verifier.md
index f2226a0b6c..256dea6179 100644
--- a/.kilo/agent/e2e-verifier.md
+++ b/.kilo/agent/e2e-verifier.md
@@ -23,7 +23,7 @@ Before testing:
 1. Read the learnings — the worktree's `.kilo_workflow/learnings/` plus the main checkout's `~/Projects/cloud/.kilo_workflow/learnings/system/` — then the surface-specific runbook, and follow it exactly for services, device claiming, builds, login, automation drivers, prompts, and cleanup — mobile: `apps/mobile/e2e/AGENTS.md`; extension: `apps/extension/AGENTS.md`; web and services: `DEVELOPMENT.md` and the repository dev runner. Never bypass a helper script's preflight, install unvalidated builds, or guess selectors.
 2. Translate the plan's goals and acceptance criteria into observable flows; for user-facing features, cover the happy, retryable-unhappy, non-retryable-unhappy, and empty states.
 3. Record pre-existing services, listeners, devices, and tmux sessions so cleanup removes only resources you created. Never use a device claimed by another worktree.
-4. Immediately before starting a stack, booting a simulator or emulator, or running a native build — and only then, never while you are still reading or planning — acquire a machine device slot with `.kilo_workflow/e2e-slot.sh acquire <your-tmux-session>`. The owner string is your own tmux session name (`tmux display-message -p '#S'`) — your dispatcher launched you in a dedicated session for exactly this reason; never pass a window name or a shared session name. This is mandatory on every run — the machine is shared and unslotted device work overloads it. The command blocks until a slot frees; blocking is correct behavior, never a wedge to work around, and never a reason to proceed unslotted.
+4. Immediately before starting a stack, booting a simulator or emulator, or running a native build — and only then, never while you are still reading or planning — acquire a machine device slot with `.kilo_workflow/e2e-slot.sh acquire <your-tmux-session>`. The owner string is your own tmux session name, resolved through your own pane: `tmux display-message -p -t "$TMUX_PANE" '#S'`. Never the untargeted `tmux display-message -p '#S'` — it answers with the tmux **server's** current session, so you would own a slot under another session's name; that slot is reclaimed when *that* session dies while you are still driving a device, over-subscribing the machine and making every concurrent emulator boot and build time out. If `$TMUX_PANE` is unset you are not in a session that can own a slot: stop and report a test-environment blocker rather than guessing a name. Your dispatcher launched you in a dedicated session for exactly this reason; never pass a window name or a shared session name. This is mandatory on every run — the machine is shared and unslotted device work overloads it. The command blocks until a slot frees; blocking is correct behavior, never a wedge to work around, and never a reason to proceed unslotted.
 5. Before any temporary edit, snapshot a baseline outside every repository: `git status --porcelain=v2 -z --untracked-files=all`, binary worktree and index diffs, and the byte hash, file mode, and symlink target of every untracked path. Copy the original bytes and mode of every tracked file you plan to edit. Temporary edits may touch only paths that are clean and tracked at baseline, or brand-new paths — never a pre-existing modified, staged, or untracked path.
 
 Output discipline — long verification runs die when their session payload grows too large. Cap every shell command's output (`| tail -c 1500` or `| tail -5`); write hierarchies, captures, and service logs to files and print only greps or counts; never re-read screenshots into context; keep your final report bounded.
diff --git a/.kilo_workflow/WORKFLOW.md b/.kilo_workflow/WORKFLOW.md
index 06202ef4cb..1b7b6735d9 100644
--- a/.kilo_workflow/WORKFLOW.md
+++ b/.kilo_workflow/WORKFLOW.md
@@ -106,7 +106,7 @@ The session the user invokes the workflow from is the starter, running on the ha
 2. Explore the relevant parts of the codebase.
 3. Interrogate the requirements — in `hands on` mode by grilling the user one question at a time, in `hands off` mode by grilling itself and answering from repository evidence, recording material assumptions. Always drive toward the simplest solution that achieves the user's goals, and challenge the request itself: "should we even do this?", "why not do this instead?", "we could achieve the same thing simpler, like this".
 4. Divide the finalized work into related, **disjoint** sections — no two sections may touch the same files or contracts.
-5. For each section: create the dedicated worktree and scratch directory (Ground Rules), write the section brief to `$SCRATCH/brief.md` — the work, the mode, acceptance criteria and constraints gathered so far, the requesting human's GitHub handle for PR assignment, the worktree path, and the scratch path — and launch a planner in a new tmux window on the planner harness and model. `<session>` is the starter's own tmux session (`tmux display-message -p '#S'`), and the `$SCRATCH` value must be expanded by the launching shell (double-quote the tmux command string; the tmux server does not know the variable):
+5. For each section: create the dedicated worktree and scratch directory (Ground Rules), write the section brief to `$SCRATCH/brief.md` — the work, the mode, acceptance criteria and constraints gathered so far, the requesting human's GitHub handle for PR assignment, the worktree path, and the scratch path — and launch a planner in a new tmux window on the planner harness and model. `<session>` is the starter's own tmux session, resolved through its own pane — `tmux display-message -p -t "$TMUX_PANE" '#S'`; never the untargeted `tmux display-message -p '#S'`, which answers with the tmux **server's** current session (the most recently active one) and silently files the window under an unrelated section. A starter that is not itself inside tmux has no such session and `$TMUX_PANE` is unset: launch the planner with `tmux new-session -d -s <section>-planner` instead of guessing a target. The `$SCRATCH` value must be expanded by the launching shell (double-quote the tmux command string; the tmux server does not know the variable):
 
 ```bash
 # kilo planner (the planner agent definition pins permissions; the model is the user's pick):
diff --git a/.kilo_workflow/e2e-slot.sh b/.kilo_workflow/e2e-slot.sh
index a272b8b87b..6954ae2357 100755
--- a/.kilo_workflow/e2e-slot.sh
+++ b/.kilo_workflow/e2e-slot.sh
@@ -48,6 +48,17 @@ reap() {
 case "${1:?usage: acquire|release|status <tmux-session>}" in
   acquire)
     who=${2:?tmux session name required}
+    # Reject an owner that is not a live session — a window name, or a session
+    # name misread from the untargeted `display-message -p '#S'`. Such a slot is
+    # reapable the moment it is written, so it gets handed to a second workflow
+    # while this one still drives a device, and the machine silently
+    # over-subscribes. Skip the check only when tmux cannot answer at all.
+    if alive=$(tmux list-sessions -F '#{session_name}' 2>/dev/null); then
+      if ! printf '%s\n' "$alive" | grep -qxF -- "$who"; then
+        echo "no live tmux session named '$who' — own the slot with your own session name, not a window name" >&2
+        exit 1
+      fi
+    fi
     # already holding one? idempotent.
     for s in "$DIR"/slot-*; do
       [ -d "$s" ] && [ "$(cat "$s/owner" 2>/dev/null)" = "$who" ] && { echo "already holding $(basename "$s")"; exit 0; }

From ac6247215b8b8008e415acee5c01aeb0fed02f6e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Igor=20=C5=A0=C4=87eki=C4=87?= <iscekic@protonmail.com>
Date: Tue, 28 Jul 2026 15:52:27 +0200
Subject: [PATCH 3/4] chore(workflow): tell an attached pane where a role
 agent's output went
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Dispatched role agents redirect stdout and stderr into the scratch log, so
their tmux pane is empty for the whole run and an attached human reads a
live agent as a dead one. Print the log path and the tail command in the
pane before exec'ing kilo. Terminal only — nothing reaches the log, so the
trailing EXITCODE marker and the sentinel contract are unchanged.
---
 .kilo_workflow/dispatch-role.sh | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.kilo_workflow/dispatch-role.sh b/.kilo_workflow/dispatch-role.sh
index b34243fe55..2ee341769d 100755
--- a/.kilo_workflow/dispatch-role.sh
+++ b/.kilo_workflow/dispatch-role.sh
@@ -31,7 +31,10 @@ LOG="$SCRATCH/$ROLE-$LABEL.log"
 # `|| true` keeps an empty match from failing under the pane's shell.
 STRIP='$(env | grep -oE "^(KILO|OPENCODE)[A-Za-z0-9_]*" | sed "s/^/-u /" | tr "\n" " " || true)'
 
-CMD="cd $(printf '%q' "$WT") && env $STRIP kilo run $(printf '%q' "$MSG") --agent $(printf '%q' "$ROLE") --title $(printf '%q' "$NAME")"
+# Redirection below means an attached pane shows nothing at all. Say so in the
+# pane itself — a blank window reads as a dead agent otherwise. This prints to
+# the terminal only, never into the log, so the EXITCODE contract is untouched.
+CMD="echo $(printf '%q' "$NAME: output goes to $LOG — this pane stays blank by design; watch with: tail -f $LOG") && cd $(printf '%q' "$WT") && env $STRIP kilo run $(printf '%q' "$MSG") --agent $(printf '%q' "$ROLE") --title $(printf '%q' "$NAME")"
 for arg in "$@"; do CMD+=" $(printf '%q' "$arg")"; done
 CMD+=" > $(printf '%q' "$LOG") 2>&1; echo EXITCODE=\$? >> $(printf '%q' "$LOG")"
 

From fd1ad6399596db5691c988e645668ba944b48e2b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Igor=20=C5=A0=C4=87eki=C4=87?= <iscekic@protonmail.com>
Date: Tue, 28 Jul 2026 16:11:30 +0200
Subject: [PATCH 4/4] fix(workflow): make a device slot and a dev stack one
 resource
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A slot capped concurrent device phases; nothing capped live dev stacks.
The slot was released the moment a device phase ended while the stack
stayed up, and `dev:stop` only happened when a section reached a terminal
state — so any section that looped between rounds, wedged, or died left
~17 services running with nothing accounting for them. Five stacks were up
on this 14-core host against a cap of three, load average 379, which is
why emulator boots blew through the 8-minute envelope and read as flaky
devices.

e2e-slot.sh now owns both halves:

- acquire records the worktree that took the slot.
- release frees the slot and stops that worktree's stack, unless another
  held slot still covers it. A later round re-acquires and starts fresh;
  that restart is the price of the cap holding.
- Reclaiming a dead holder's slot stops its stack too, so a section that
  dies mid-flight no longer leaks one forever.
- status reports each holder's worktree and stack state, and warns about
  stacks running with no slot.
- stacks [--reap] lists those and stops the workflow-owned ones. Stacks
  with no section run id in the name were started by hand and are only
  reported, never stopped.

Coverage falls back to the holder's session-name prefix when a slot has no
recorded worktree, so slots written before this change never make a live
stack look abandoned.
---
 .kilo_workflow/WORKFLOW.md |   9 ++-
 .kilo_workflow/e2e-slot.sh | 124 +++++++++++++++++++++++++++++++++----
 apps/mobile/e2e/AGENTS.md  |   5 +-
 3 files changed, 122 insertions(+), 16 deletions(-)

diff --git a/.kilo_workflow/WORKFLOW.md b/.kilo_workflow/WORKFLOW.md
index 1b7b6735d9..a16559c3d1 100644
--- a/.kilo_workflow/WORKFLOW.md
+++ b/.kilo_workflow/WORKFLOW.md
@@ -261,16 +261,19 @@ The machine is shared by parallel workflows, and unslotted device or stack work
 
 ```bash
 .kilo_workflow/e2e-slot.sh acquire <tmux-session>   # blocks until a slot frees
-.kilo_workflow/e2e-slot.sh status                   # current holders
+.kilo_workflow/e2e-slot.sh status                   # holders, their worktrees, stack coverage
 .kilo_workflow/e2e-slot.sh release <tmux-session>   # the moment the device phase ends
+.kilo_workflow/e2e-slot.sh stacks [--reap]          # stacks running with no slot
 ```
 
+**A slot and a dev stack are the same resource.** The slot is what entitles a worktree to run a stack, and a stack must never outlive it: `release` stops the releasing worktree's stack, and reclaiming a dead holder's slot stops its stack too. So a later round re-acquires and starts a fresh stack rather than inheriting one — that restart is the price of the cap. A stack up with no slot is a defect, not a shortcut; `stacks` lists them and `stacks --reap` stops the workflow-owned ones (a stack with no section run id in its name was started by hand and is only reported). Five live stacks on this host drove the load average past 300 and made every emulator boot and native build time out, which reads as flaky devices rather than as over-subscription.
+
 - Slot state lives in `$HOME/.cache/kilo-e2e-slots`, machine-global by design: every copy of the script — any worktree, any repository — contends for the same slots, and the script has no overrides by design. When working in a repository without the script (a sibling like `~/Projects/kilocode`), invoke it by absolute path from a cloud worktree.
 - This holds on every run, not only when another workflow is visibly active, and a stack that is already up is not an exemption.
 - `acquire` blocking is correct behavior, never a wedge to route around and never a reason to start device work unslotted. If an acquire is still blocked after about 45 minutes, the dispatcher inspects `status` for a wedged foreign holder and reports a blocker instead of waiting forever.
 - The slot caps load, not data: postgres and redis containers are shared across worktrees. Keep test data keyed to this worktree's accounts (the runbooks' per-worktree defaults) and never wipe shared state.
-- Release immediately when the device/stack phase ends. Planning, implementation, review, checks, and CI waits are uncapped; never hold a slot through them.
-- Slots are owned by tmux session name and reclaimed automatically when the session dies. A holder that is alive but wedged belongs to its own workflow's monitor — never kill another session to free a slot; if the queue is starved by a foreign wedge, report a blocker to the user instead.
+- Release immediately when the device/stack phase ends. Planning, implementation, review, checks, and CI waits are uncapped; never hold a slot through them — and since release takes the stack with it, do not release mid-round while you still need the services.
+- Slots are owned by tmux session name, record the worktree that took them, and are reclaimed automatically when the session dies. A holder that is alive but wedged belongs to its own workflow's monitor — never kill another session to free a slot; if the queue is starved by a foreign wedge, report a blocker to the user instead.
 - The orchestrator is accountable: every device-phase handoff states the slot rule, and a role agent that reports device work with no acquire gets re-dispatched.
 
 ## Feature-State Matrix
diff --git a/.kilo_workflow/e2e-slot.sh b/.kilo_workflow/e2e-slot.sh
index 6954ae2357..068ab40d1b 100755
--- a/.kilo_workflow/e2e-slot.sh
+++ b/.kilo_workflow/e2e-slot.sh
@@ -1,16 +1,21 @@
 #!/usr/bin/env bash
 # Device/stack slot semaphore for parallel workflows.
 #
-# Only work that needs a simulator, emulator, browser fleet, local backend
-# stack, or native build is capped. Planning, implementation, review, and CI
-# waits are unlimited.
+# A slot and a dev stack are the same resource: a slot is what entitles a
+# worktree to run a stack, a device, or a native build. A stack must never
+# outlive the slot that started it — five live stacks on a 14-core host push the
+# load past the point where emulator boots and native builds time out, which
+# reads as flaky devices rather than as over-subscription. Planning,
+# implementation, review, and CI waits need neither, and are unlimited.
 #
 #   e2e-slot.sh acquire <tmux-session>   # blocks until a slot is free, then holds it
-#   e2e-slot.sh release <tmux-session>   # release as soon as the device phase ends
-#   e2e-slot.sh status                   # who holds what, and for how long
+#   e2e-slot.sh release <tmux-session>   # frees the slot AND stops the worktree's stack
+#   e2e-slot.sh status                   # who holds what, for how long, with stack coverage
+#   e2e-slot.sh stacks [--reap]          # stacks with no slot; --reap stops them
 #
-# A slot is owned by a tmux session name. If that tmux session no longer exists
-# the slot is stale and is reclaimed automatically — no heartbeats to maintain.
+# A slot is owned by a tmux session name and records the worktree that took it.
+# If that tmux session no longer exists the slot is stale and is reclaimed
+# automatically — no heartbeats to maintain.
 #
 # State is machine-global on purpose: every worktree's copy of this script must
 # contend for the same slots, so the state dir never lives next to the script.
@@ -23,6 +28,44 @@ TOTAL=3
 POLL=60
 mkdir -p "$DIR"
 
+# The worktree that owns this copy of the script — recorded at acquire time so
+# release and reap know which stack belongs to the slot.
+SELF_WORKTREE=$(git -C "$(dirname "$0")" rev-parse --show-toplevel 2>/dev/null || echo)
+
+# Section slugs carry a random run id (`<name>-$(openssl rand -hex 2)`, see
+# WORKFLOW.md Ground Rules). Only those stacks are workflow-owned; a stack
+# started by hand in a personal worktree is reported, never stopped.
+is_section_slug() { [[ "$1" =~ -[0-9a-f]{4}$ ]]; }
+
+stack_session() { echo "kilo-dev-$(basename "$1" | tr -c 'A-Za-z0-9_-' '_')"; }
+
+# Is any held slot entitled to this stack session? The recorded worktree is the
+# real answer; the owner-name prefix is a fallback so slots written before
+# worktrees were recorded never make a live stack look abandoned.
+stack_is_covered() {
+  sess=$1
+  for s in "$DIR"/slot-*; do
+    [ -d "$s" ] || continue
+    wt=$(cat "$s/worktree" 2>/dev/null || echo)
+    [ -n "$wt" ] && [ "$(stack_session "$wt")" = "$sess" ] && return 0
+    owner=$(cat "$s/owner" 2>/dev/null || echo)
+    case "$owner" in "${sess#kilo-dev-}"*) return 0 ;; esac
+  done
+  return 1
+}
+
+# Stop a worktree's stack, but only once no remaining slot covers it — a section
+# can hold a second slot for a concurrent phase.
+stop_stack() {
+  wt=$1
+  [ -n "$wt" ] && [ -d "$wt" ] || return 0
+  sess=$(stack_session "$wt")
+  stack_is_covered "$sess" && return 0
+  tmux has-session -t "$sess" 2>/dev/null || return 0
+  echo "stopping dev stack for $wt"
+  (cd "$wt" && pnpm dev:stop)
+}
+
 reap() {
   # If tmux cannot answer (missing binary, no server, socket error), liveness
   # cannot be judged — keep every slot rather than wipe live ones. Acquirers
@@ -41,7 +84,21 @@ reap() {
       [ "$age" -gt 60 ] && rm -rf "$s"
       continue
     fi
-    printf '%s\n' "$alive" | grep -qxF -- "$owner" || rm -rf "$s"
+    if ! printf '%s\n' "$alive" | grep -qxF -- "$owner"; then
+      # The owner is gone, so the slot AND the stack it entitled are both
+      # reclaimable. Nothing is using a stack whose session died.
+      wt=$(cat "$s/worktree" 2>/dev/null || echo)
+      rm -rf "$s"
+      stop_stack "$wt"
+    fi
+  done
+}
+
+# Stacks are named after their worktree, so a stack with no slot recording that
+# worktree is uncovered — it outlived whatever entitled it to exist.
+uncovered_stacks() {
+  tmux list-sessions -F '#{session_name}' 2>/dev/null | grep '^kilo-dev-' | while read -r sess; do
+    stack_is_covered "$sess" || echo "$sess"
   done
 }
 
@@ -68,8 +125,9 @@ case "${1:?usage: acquire|release|status <tmux-session>}" in
       for i in $(seq 1 "$TOTAL"); do
         if mkdir "$DIR/slot-$i" 2>/dev/null; then
           printf '%s' "$who" > "$DIR/slot-$i/owner"
+          printf '%s' "$SELF_WORKTREE" > "$DIR/slot-$i/worktree"
           date -u +%Y-%m-%dT%H:%M:%SZ > "$DIR/slot-$i/since"
-          echo "acquired slot-$i"
+          echo "acquired slot-$i for ${SELF_WORKTREE:-unknown worktree}"
           exit 0
         fi
       done
@@ -80,7 +138,14 @@ case "${1:?usage: acquire|release|status <tmux-session>}" in
   release)
     who=${2:?tmux session name required}
     for s in "$DIR"/slot-*; do
-      [ -d "$s" ] && [ "$(cat "$s/owner" 2>/dev/null)" = "$who" ] && rm -rf "$s" && echo "released $(basename "$s")"
+      [ -d "$s" ] || continue
+      [ "$(cat "$s/owner" 2>/dev/null)" = "$who" ] || continue
+      wt=$(cat "$s/worktree" 2>/dev/null || echo)
+      rm -rf "$s"
+      echo "released $(basename "$s")"
+      # The stack goes with the slot. A later round acquires again and starts a
+      # fresh one; leaving it up is what pushes the host past three stacks.
+      stop_stack "$wt"
     done
     exit 0
     ;;
@@ -90,9 +155,44 @@ case "${1:?usage: acquire|release|status <tmux-session>}" in
     for s in "$DIR"/slot-*; do
       [ -d "$s" ] || continue
       n=$((n + 1))
-      echo "$(basename "$s"): $(cat "$s/owner" 2>/dev/null) since $(cat "$s/since" 2>/dev/null)"
+      wt=$(cat "$s/worktree" 2>/dev/null || echo)
+      # No recorded worktree means the slot predates this script — say so rather
+      # than reporting a stack state that was never looked up.
+      if [ -z "$wt" ]; then
+        stack='worktree unrecorded, stack unknown'
+      elif tmux has-session -t "$(stack_session "$wt")" 2>/dev/null; then
+        stack="$wt stack=up"
+      else
+        stack="$wt stack=none"
+      fi
+      echo "$(basename "$s"): $(cat "$s/owner" 2>/dev/null) since $(cat "$s/since" 2>/dev/null) [$stack]"
     done
     echo "$n/$TOTAL held"
+    uncovered=$(uncovered_stacks)
+    if [ -n "$uncovered" ]; then
+      echo "uncovered stacks (up with no slot — run '$0 stacks --reap'): $(printf '%s ' $uncovered)" >&2
+    fi
+    ;;
+  stacks)
+    reap
+    uncovered=$(uncovered_stacks)
+    [ -z "$uncovered" ] && { echo "every running dev stack is covered by a slot"; exit 0; }
+    for sess in $uncovered; do
+      slug=${sess#kilo-dev-}
+      if [ "${2:-}" != "--reap" ]; then
+        echo "$sess: up with no slot"
+        continue
+      fi
+      if ! is_section_slug "$slug"; then
+        echo "$sess: no section run id in the name — started by hand, leaving it alone"
+        continue
+      fi
+      wt=$(git worktree list --porcelain | sed -n 's/^worktree //p' | while read -r p; do
+        [ "$(basename "$p")" = "$slug" ] && echo "$p"; done | head -1)
+      [ -n "$wt" ] || { echo "$sess: no worktree on disk, leaving its session alone"; continue; }
+      echo "stopping $sess ($wt)"
+      (cd "$wt" && pnpm dev:stop)
+    done
     ;;
-  *) echo "usage: $0 acquire|release|status <tmux-session>" >&2; exit 1 ;;
+  *) echo "usage: $0 acquire|release|status|stacks <tmux-session>" >&2; exit 1 ;;
 esac
diff --git a/apps/mobile/e2e/AGENTS.md b/apps/mobile/e2e/AGENTS.md
index aa94936602..c50d46a2d7 100644
--- a/apps/mobile/e2e/AGENTS.md
+++ b/apps/mobile/e2e/AGENTS.md
@@ -10,8 +10,11 @@ This machine is shared by parallel workflows. Before starting a stack, booting a
 .kilo_workflow/e2e-slot.sh acquire <your-tmux-session>   # blocks until a slot frees
 .kilo_workflow/e2e-slot.sh status                        # current holders
 .kilo_workflow/e2e-slot.sh release <your-tmux-session>   # the moment the device phase ends
+.kilo_workflow/e2e-slot.sh stacks                        # any stack running with no slot
 ```
 
+A slot and this worktree's dev stack are one resource: the slot is what entitles you to the stack, and `release` stops the stack with it. Release when your device phase is genuinely over, not partway through a round you still need services for.
+
 - Default 3 slots, machine-global, owned by tmux session name; a dead session's slot is reclaimed automatically, so a crash cannot wedge the queue.
 - `acquire` blocking is correct behavior, not a hang and not a wedge. Wait for it. Never start device work unslotted because the queue was busy, because your phase looks small, or because a stack is already up.
 - Acquiring is idempotent per session; every device phase (repro gate, each E2E round) needs a slot.
@@ -305,7 +308,7 @@ Clean up only resources you started. The remote CLI session and its disposable i
 tmux kill-session -t "$ANDROID_SESSION"      # if created
 rm -f "$LOGIN_LOG"                           # if created
 rm -f "$EMULATOR_LOG"                        # if created
-pnpm dev:stop                                # only if you started this worktree's stack
+pnpm dev:stop                                # only if the slot release below did not already stop it
 xcrun simctl shutdown <udid>                 # only if you booted it
 pnpm dev:mobile:simulator release <udid>     # every simulator you claimed
 pnpm dev:mobile:android release <serial>     # every Android device you claimed