multi-agent-mux/.agents/reports/canary-projects-multi-agent-mux-planner-claude/report-prompt-lock-plan.md

Prompt-Lock Fix Implementation Plan (Planner Claude — Final)

• Planner: Planner Claude (canary-projects-multi-agent-mux-planner-claude)
• Date: 2026-07-11
• Brief: .mam/reports/brief-planner-prompt-lock-plan.md
• Inputs consolidated:
  1. Reviewer Cline — .agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-prompt-lock-analysis.md
  2. Creator Claude — .agents/reports/canary-projects-multi-agent-mux-creator-claude/report-prompt-lock-analysis.md
• Executor: Antigravity
• Roadmap linkage: closes FW-W2 (FUTURE_WORKS.md:25 / FUTURE_WORKS.ko.md:24)

---

0. Consolidation Verdict

Both analyses agree on the root causes (keys sent on timers, not evidence; no dialog detection; wait_for_tui_ready misclassifies dialogs as ready) and on the remedy shape (evidence-based send_keys_safe in lib.sh). I adopt Creator Claude's helper design as the base with four planner amendments (A1–A4 below).

Discrepancy resolved — the delegate-job duplicate. Cline's Site B is real and Creator Claude missed it: .agents/skills/multi-agent-mux-delegate-job/multi-agent-mux-delegate-job:365-369 is a raw copy-paste of the inject_instructions body (verified in code; Creator's "sole caller is create_session.sh:384" is technically true of the function but ignores the duplicated logic). This is the highest-traffic delegation path and must be in the mod-sites list (MS-7). I verified lib.sh is side-effect-free at source time (only variable defaults + function definitions), so the delegate-job wrapper can safely source it — this also retires the copy-paste that violates lib.sh's single-source-of-truth mandate (header §4.1).

Planner amendments to Creator's helper:

• A1 — marker derivation: Creator's head -c 200 | tail -c 24 can straddle a newline in the multi-line instructions built at create_session.sh:374-381, producing a marker that can never match a single captured line. Amended: last 24 chars of the last non-empty line.
• A2 — submit verification: Creator's "marker left tail -n 5" alone risks a false failure (Claude's TUI echoes the submitted prompt into the transcript just above the input box, so the marker can linger in the bottom 5 lines after a successful submit → spurious retries → exit 4 → spurious rollback). Amended: submitted = marker left the bottom 3 lines AND the pane visibly changed relative to a pre-Enter snapshot. Line count is DoD-tunable (DoD-6).
• A3 — dialog detection scope: grep the bottom 20 lines of the pane, not the full viewport — dialog signatures appearing in agent conversation output higher up must not block delivery forever.
• A4 — resume needs an accept-policy helper, not send_keys_safe: send_keys_safe deliberately refuses to type into dialogs; the resume flow must accept the trust/bypass dialogs. That is a separate policy helper, handle_startup_dialogs (conditional, signature-gated — replaces the blind Enter/Down/Enter both reports condemned).

Non-goal (out of scope, per surgical principle): adding dialog auto-accept to the create path — it has never had dialog handling; with MS-2/MS-5 a dialog during create now fails loudly with rollback instead of silently prompt-locking. If field data shows trust dialogs during create, a follow-up can reuse handle_startup_dialogs.

---

1. Deliverable 1 — Concrete Helper Implementation

Insert into .agents/skills/lib.sh immediately after inject_instructions (after current line 1100). Plain bash, no new dependencies.

# ---------------------------------------------------------------------------
# Prompt-lock safe delivery (FW-W2). Keys are sent on evidence, not timers.
# send_keys_safe returns 0 only if the text was verifiably submitted.
# Exit codes: 1=pane never quiesced  2=dialog blocking input
#             3=paste not visible    4=Enter not accepted
# Callers MUST handle non-zero.
# ---------------------------------------------------------------------------

# Server-aware tmux (same isolation rule as inject_instructions).
_sks_tmux() {
  if [ -n "${TMUX_SERVER_NAME:-}" ] && [ "$TMUX_SERVER_NAME" != "default" ]; then
    tmux -L "$TMUX_SERVER_NAME" "$@"
  else
    tmux "$@"
  fi
}

_pane_capture() { _sks_tmux capture-pane -p -t "$1" 2>/dev/null || echo ""; }

# _pane_quiescent <sess> [tries=20] [interval=0.5]
# Renderer settled = two consecutive identical non-empty captures.
# Defeats RC-A (Blessed/Ink renderer bottleneck) without a magic fixed sleep.
_pane_quiescent() {
  local sess="$1" tries="${2:-20}" interval="${3:-0.5}" prev="__none__" cur i
  for ((i = 0; i < tries; i++)); do
    cur=$(_pane_capture "$sess")
    [ -n "$cur" ] && [ "$cur" = "$prev" ] && return 0
    prev="$cur"
    sleep "$interval"
  done
  return 1
}

# _pane_dialog_open <sess> — focus-stealing modal signatures (trust /
# permission / OAuth / list-selection), checked in the bottom 20 pane lines
# only (dialogs render near the input area; conversation text above must not
# trigger this). Tokens must NOT appear on normal idle prompt screens —
# validate against real captures per agent TUI release (DoD-5).
_pane_dialog_open() {
  _pane_capture "$1" | tail -n 20 | grep -Eq \
    'Do you trust the files|Yes, proceed|No, exit|Allow this|Press Enter to continue|browser to authenticate|Use arrow keys|Esc to cancel'
}

# send_keys_safe <sess> <text> [job_id]
# 1. Wait for renderer quiescence (RC-A).
# 2. Refuse to paste while a dialog is open (RC-B/RC-C): wait up to
#    SKS_DIALOG_TIMEOUT (default 30 s); if SKS_DIALOG_ESCAPE=1, send a single
#    Escape per poll and re-check. NEVER a blind Enter — accepting an unknown
#    dialog is a policy decision, not a delivery detail.
# 3. Paste via unique buffer; verify the text landed (marker visible).
# 4. Submit C-m; verify submission (marker left the input area AND the pane
#    changed); retry up to 3 times — re-Enter on unsubmitted text is idempotent.
send_keys_safe() {
  local sess="$1" text="$2" job_id="${3:-adhoc}"
  local marker pre_submit deadline try
  # Verification token: last 24 chars of the last non-empty line (multi-line safe).
  marker=$(printf '%s' "$text" | tr -d '\r' | awk 'NF {line=$0} END {print line}' | tail -c 24)

  _pane_quiescent "$sess" || { echo "send_keys_safe: pane never quiesced ($sess)" >&2; return 1; }

  deadline=$(( $(date +%s) + ${SKS_DIALOG_TIMEOUT:-30} ))
  while _pane_dialog_open "$sess"; do
    if [ "${SKS_DIALOG_ESCAPE:-0}" = "1" ]; then
      _sks_tmux send-keys -t "$sess" Escape
      sleep 1
    fi
    if [ "$(date +%s)" -ge "$deadline" ]; then
      echo "send_keys_safe: dialog blocking input ($sess)" >&2
      return 2
    fi
    sleep 2
  done

  _sks_tmux set-buffer -b "sks_$job_id" "$text"
  _sks_tmux paste-buffer -b "sks_$job_id" -t "$sess"
  _sks_tmux delete-buffer -b "sks_$job_id" 2>/dev/null || true
  sleep 0.5
  _pane_capture "$sess" | grep -Fq "$marker" || { echo "send_keys_safe: paste not visible ($sess)" >&2; return 3; }

  for try in 1 2 3; do
    pre_submit=$(_pane_capture "$sess")
    _sks_tmux send-keys -t "$sess" C-m
    sleep "$try"
    # Submitted = input area released the text AND rendering changed after Enter.
    if ! _pane_capture "$sess" | tail -n 3 | grep -Fq "$marker" \
       && [ "$(_pane_capture "$sess")" != "$pre_submit" ]; then
      return 0
    fi
  done
  echo "send_keys_safe: Enter not accepted after 3 tries ($sess)" >&2
  return 4
}

# handle_startup_dialogs <sess> [timeout_sec=20]
# Post-start/resume dialog policy for claude: accept the trust / bypass
# dialogs ONLY when their signature is positively on screen; return as soon
# as the TUI banner is ready. Replaces the blind Enter/Down/Enter sequence.
# Non-fatal by design: on timeout the caller proceeds (attach shows leftovers).
handle_startup_dialogs() {
  local sess="$1" timeout="${2:-20}" waited=0 pane
  while [ "$waited" -lt "$timeout" ]; do
    pane=$(_pane_capture "$sess" | tail -n 20)
    if printf '%s\n' "$pane" | grep -q 'Do you trust the files'; then
      _sks_tmux send-keys -t "$sess" Enter                     # accept trust prompt
    elif printf '%s\n' "$pane" | grep -q 'Yes, proceed'; then
      _sks_tmux send-keys -t "$sess" Down                      # select "Yes, proceed"
      sleep 0.3
      _sks_tmux send-keys -t "$sess" Enter
    elif printf '%s\n' "$pane" | grep -Eq 'Anthropic|Assistant|Chat|Welcome|projects'; then
      return 0                                                 # ready, no dialog
    fi
    sleep 2
    waited=$((waited + 2))
  done
  return 0
}

⚠️ Signature-token caveat (both analyses inherited this): neither input report captured the actual dialog text of current claude/agy/hermes/cline TUI builds. The token lists above are the best available hypotheses. DoD-5 makes validating them against real capture-pane output a merge blocker — the executor must adjust tokens to observed text before committing.

---

2. Deliverable 2 — Surgical Mod-Sites List

Every change traces to a verified defect site. No other lines are touched.

#	File : lines (current)	Change
MS-1	.agents/skills/lib.sh (insert after 1100)	Add the §1 helper block verbatim.
MS-2	.agents/skills/lib.sh:1056	wait_for_tui_ready claude regex: "Anthropic|Assistant|Chat|Dangerously|dangerously|Enter|Welcome|projects" → "Anthropic|Assistant|Chat|Welcome|projects" (drop the three tokens that also match trust/bypass dialogs — RC-B fix).
MS-3	.agents/skills/lib.sh:1050-1053	Inside the retry loop, before the case: skip the ready-check while a dialog is up — insert if _pane_dialog_open "$sess"; then sleep 1; continue; fi after the capture (requires MS-1 helpers; they are defined later in the file but resolved at call time — bash allows this).
MS-4	.agents/skills/lib.sh:1083	echo "⚠️ Warning: ... Proceeding anyway..." → echo "⚠️ TUI readiness check timed out for '$sess'." >&2; return 1 — the gate must be allowed to fail.
MS-5	.agents/skills/lib.sh:1088-1100	Rewrite inject_instructions body as a thin wrapper: inject_instructions() { send_keys_safe "$1" "$2" "${3:-onboard}"; } (same signature; sole caller inherits the fix; keep the function comment, note the delegation).
MS-6	.agents/skills/multi-agent-mux-create/scripts/create_session.sh:199	wait_for_tui_ready "$SESSION_NAME" "$AGENT" → explicit guard: if ! wait_for_tui_ready "$SESSION_NAME" "$AGENT"; then echo "ERROR: agent TUI never became ready — aborting (rollback via trap)" >&2; exit 1; fi (the trap cleanup_tmux_on_error EXIT armed at line 196 kills the session and removes the isolation home).
MS-7	.agents/skills/multi-agent-mux-create/scripts/create_session.sh:384	Guard the injection: if ! inject_instructions "$SESSION_NAME" "$instructions" "$DELEGATE_JOB_ID"; then delegate_publish_event "$DELEGATE_JOB_ID" error "instruction injection failed (prompt-lock, rc=$?)"; exit 1; fi — the job gets a terminal error event (no more zombie jobs waiting for watchdog timeout), then the EXIT trap rolls the session back. started (line 386) now only publishes on verified delivery.
MS-8	.agents/skills/multi-agent-mux-delegate-job/multi-agent-mux-delegate-job:364-369	Replace the duplicated raw block (set-buffer/paste-buffer/sleep 0.5/C-m/delete-buffer) with: source "$SCRIPT_DIR/../lib.sh" (immediately before use; lib.sh is load-side-effect-free — verified) then if ! send_keys_safe "$sess" "$instructions" "$job_id"; then echo "ERROR: 프롬프트 주입 실패 — 세션 '$sess' (프롬프트 잠금 의심)" >&2; return 1; fi. Keep the local _tmux definition (lines 347-350) — still used by has-session (352) and the attach hint (371). The return 1 propagates under set -euo pipefail and fires the EXIT trap at 358-362, which publishes the error event.
MS-9	.agents/skills/multi-agent-mux-resume/SKILL.md:150-156	Replace the blind block (sleep 5; Enter; sleep 3; Down; sleep 0.3; Enter) with: handle_startup_dialogs "$SESSION_NAME" 20 (the embedded script already sources lib.sh at line 68). Fixes both failure directions: no-dialog → no stray keys into the prompt/history; late dialog → polled, not raced.
MS-10	.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh:192	tmux send-keys -t "$SESSION_NAME" "$exitkey" Enter 2>/dev/null || true → send_keys_safe "$SESSION_NAME" "$exitkey" "stop$$" || echo "graceful: safe delivery failed (rc=$?) — falling back to kill chain" (script already sources lib.sh at line 32; the SIGTERM→SIGKILL fallback chain at 193-207 stays byte-identical).
MS-11	.agents/skills/multi-agent-mux-create/SKILL.md:214-215	Replace the stray-Enter probe example with a passive one: tmux capture-pane -t "$SESSION_NAME" -p -S -20 # TUI ready = agent banner visible, no dialog text (never fire keys as a liveness probe).
MS-12	FUTURE_WORKS.md:25, FUTURE_WORKS.ko.md:24	Mark FW-W2 resolved using the existing FW-D1 strikethrough convention (~~...~~ + resolution date 2026-07-11 + commit ref), both languages.

Explicitly NOT touched (verified non-vulnerable, matching Creator §2-F): update_yaml_resumed.sh, scripts/install_mam.sh, reconcile.sh, all Python backplane scripts.

---

3. Deliverable 3 — Execution Instructions (for Antigravity)

Run from the repo root, in order. Halt and report back on any non-zero step that isn't explicitly tolerated.

T0 — Preflight

cd /home/godopu16/PuKi/laa/canary_projects/multi-agent-mux
git diff --quiet && git diff --cached --quiet || { echo "ABORT: dirty tree"; exit 1; }

(Untracked files are expected: the two analysis reports and this plan.)

T1 — Apply MS-1…MS-5 to lib.sh

Insert the §1 helper block after line 1100; apply the four edits to wait_for_tui_ready / inject_instructions exactly as specified in §2. Then:

bash -n .agents/skills/lib.sh

T2 — Apply MS-6/MS-7 to create_session.sh, MS-8 to the delegate-job wrapper, MS-9 to resume/SKILL.md, MS-10 to stop_session.sh, MS-11 to create/SKILL.md

bash -n .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
        .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
        .agents/skills/multi-agent-mux-delegate-job/multi-agent-mux-delegate-job
command -v shellcheck >/dev/null && shellcheck -S warning \
        .agents/skills/lib.sh \
        .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
        .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh || true

Zero new findings allowed (pre-existing findings are out of scope).

T3 — Verification gate (Definition of Done) — scratch server only, never real sessions

All tmux activity on tmux -L sks-test; tmux -L sks-test kill-server afterwards.

1. DoD-1 RC-A (renderer stall): mock TUI that floods stdout for 10 s before reading stdin (while :; do echo spam; done & sleep 10; kill %1; cat) → send_keys_safe must wait out quiescence and deliver (rc 0); confirm by capturing the mock's received line.
2. DoD-2 RC-B/C (dialog block): mock that prints Do you trust the files in this folder? and swallows input → send_keys_safe must refuse to paste and return 2 after SKS_DIALOG_TIMEOUT=6; with SKS_DIALOG_ESCAPE=1 verify a single Escape per poll, still no blind Enter.
3. DoD-3 E2E create: real create_session.sh --submit-job on a scratch workspace → instructions verifiably submitted, started event observed, normal stop afterwards.
4. DoD-4 E2E delegate + resume + stop: delegate-job submit to a running scratch session (delivery via the new path); resume a stopped claude scratch session twice — once where the trust dialog appears, once where it doesn't — confirm no stray keys land in the prompt in the second case; --graceful stop delivers /exit via the helper and the fallback chain still engages when the pane is blocked.
5. DoD-5 signature validation (merge blocker): capture-pane the real trust/bypass/permission dialogs of the current claude build; confirm every _pane_dialog_open and handle_startup_dialogs token matches observed text and none appears on the idle prompt screen; adjust tokens to reality before committing.
6. DoD-6 A2 tuning: during DoD-3, confirm the submit check (marker leaves bottom-3-lines + pane change) doesn't false-fail on the TUI's transcript echo; tune the tail -n 3 count if needed and record the final value in the commit message.

T4 — Commit (single atomic commit)

git add .agents/skills/lib.sh \
        .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
        .agents/skills/multi-agent-mux-create/SKILL.md \
        .agents/skills/multi-agent-mux-delegate-job/multi-agent-mux-delegate-job \
        .agents/skills/multi-agent-mux-resume/SKILL.md \
        .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
        FUTURE_WORKS.md FUTURE_WORKS.ko.md \
        .agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-prompt-lock-analysis.md \
        .agents/reports/canary-projects-multi-agent-mux-creator-claude/report-prompt-lock-analysis.md \
        .agents/reports/canary-projects-multi-agent-mux-planner-claude/report-prompt-lock-plan.md
git commit -m "fix(skills): evidence-based prompt delivery (send_keys_safe) to end prompt-lock (FW-W2)

- Add send_keys_safe + quiescence/dialog-detection helpers to lib.sh:
  keys are sent on pane evidence, never fixed timers; distinct exit
  codes 1-4; dialogs are never blindly Enter-ed
- inject_instructions delegates to send_keys_safe; create --submit-job
  publishes a terminal error event on delivery failure (no zombie jobs)
- wait_for_tui_ready: drop dialog-ambiguous tokens, treat open dialogs
  as not-ready, return 1 on timeout instead of proceeding
- delegate-job wrapper: replace copy-pasted raw paste/C-m block with
  lib.sh send_keys_safe (restores single source of truth)
- resume: conditional signature-gated dialog handling replaces blind
  Enter/Down/Enter; stop --graceful delivers exitkey safely, fallback
  chain unchanged
- create SKILL: passive capture-pane probe instead of stray Enter
- Mark FW-W2 resolved; add 3-agent analysis/plan reports"

T5 — Post-commit sanity

git status --short          # expected: empty
grep -n "Proceeding anyway" .agents/skills/lib.sh   # expected: no match
grep -rn "sleep 0.5$" .agents/skills/multi-agent-mux-delegate-job/multi-agent-mux-delegate-job  # expected: no match

Halt conditions: any DoD failure, any bash -n error, any new shellcheck warning, or dialog tokens that cannot be validated (DoD-5) → stop, do not commit, report back to Planner with the failing capture.

---

4. Risk Register

Risk	Severity	Mitigation
Dialog signature tokens don't match real TUI text	High (silently defeats RC-B fix)	DoD-5 is a merge blocker; tokens curated per agent release
A2 submit-check false-fails on transcript echo	Medium (spurious rollback)	Pane-change AND-condition + DoD-6 tuning
wait_for_tui_ready now failing hard changes create-path behavior on slow hosts	Medium	15×1s budget unchanged; failure now rolls back loudly instead of injecting blind — strictly better; monitor first real runs
Longer stop latency (--graceful quiescence wait)	Low	Fallback chain untouched; worst case ≈ +10 s before kill-session
delegate-job sourcing lib.sh in copied-out installs	Low	Installers ship .agents/skills/ as a tree incl. lib.sh; verified side-effect-free load

---

Final Authorization

Plan status: APPROVED for execution by Antigravity exactly as written in §3. DoD-5 (real-capture validation of dialog signatures) is a hard merge blocker. Any deviation halts execution and returns to the Planner.