Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,10 @@ A lock-refused session must not spawn, steer, merge, drain the wake queue, repai
A file that does not exist prints an explicit `ABSENT` marker, never confused with an empty-but-present file: absence is meaningful (`captain.md` absent means use the firstmate repo's built-in defaults, `projects.md` absent means rebuild it from the clones under `projects/`, etc.).
7. **Fleet-state digest** - the compact backlog listing owned by `bin/fm-session-start.sh`; every `state/<id>.meta`; a bounded tail of each task's `state/<id>.status` (labeled as wake-EVENT history, not current state, with the full log path printed for a deeper read); the `state/.afk` flag; and one cheap alive/dead read of each task's recorded backend endpoint.
That liveness line is a fast presence check only, not a full state read - when you need a crew's actual current state (a run-step, not just "is the pane there"), read it with `bin/fm-crew-state.sh <id>` as before; the digest deliberately skips that deeper, slower read for every task so it stays fast and bounded.
8. **Parlay** - a read-only `parlay sweep` that surfaces captain-parked agents held for captain action.
A one-line count summary (`parlay: N agent(s) held for captain action` or `parlay: none held for captain action`) is always printed when the `parlay` binary is on PATH.
When N > 0, the HOLD lines with `state=needs-decision`, `state=blocked`, or `state=failed` follow, each truncated to 80 chars; `done`, `unknown`, `no-launch-spec`, and `would-close` lines are suppressed.
The section is absent entirely when the `parlay` binary is not installed; no action is required in that case.

Bootstrap detects first, asks for consent, and installs only after the captain approves in the current session.
Do not dispatch until the required tools are present and GitHub authentication is good.
Expand Down
37 changes: 36 additions & 1 deletion bin/fm-session-start.sh
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,7 @@ done
# The ordered stage list is the contract behind the truncation banner: the child
# names the stage it is entering, and the parent reports every stage at or after
# that one as never emitted. Keep it in the exact order the digest prints.
SESSION_START_STAGES='lock bootstrap wake-queue supervision-instructions persona context fleet-state next-step'
SESSION_START_STAGES='lock bootstrap wake-queue supervision-instructions persona context fleet-state parlay next-step'

stage() { # <stage-name>: breadcrumb for the parent's truncation banner
[ -n "${FM_SESSION_START_STAGE_FILE:-}" ] || return 0
Expand Down Expand Up @@ -461,6 +461,35 @@ print_status_tail() {
tail -n "$STATUS_TAIL" "$status"
}

# print_parlay_section: surface parlay agents held for captain action.
# Skips silently when the parlay binary is absent.
# Surfaces only HOLD lines with state=needs-decision, blocked, or failed;
# ignores done, unknown, no-launch-spec, and would-close lines.
print_parlay_section() {
local sweep held count line
command -v parlay >/dev/null 2>&1 || return 0
section "PARLAY"
sweep=$(parlay sweep 2>/dev/null) || sweep=
held=$(printf '%s\n' "$sweep" | grep -E '^HOLD[[:space:]].*state=(needs-decision|blocked|failed)' || true)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Match complete Parlay state values.

The current regex accepts unsupported values such as state=failed-retryable because it does not require a boundary after the allowed state. This conflicts with the documented exact-state filter.

  • bin/fm-session-start.sh#L473-L473: require whitespace or end-of-line after needs-decision, blocked, or failed.
  • tests/fm-session-start.test.sh#L2049-L2055: add a state=failed-retryable fixture and assert that the digest suppresses it.
Proposed fix
-  held=$(printf '%s\n' "$sweep" | grep -E '^HOLD[[:space:]].*state=(needs-decision|blocked|failed)' || true)
+  held=$(printf '%s\n' "$sweep" | grep -E '^HOLD[[:space:]].*state=(needs-decision|blocked|failed)([[:space:]]|$)' || true)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
held=$(printf '%s\n' "$sweep" | grep -E '^HOLD[[:space:]].*state=(needs-decision|blocked|failed)' || true)
held=$(printf '%s\n' "$sweep" | grep -E '^HOLD[[:space:]].*state=(needs-decision|blocked|failed)([[:space:]]|$)' || true)
📍 Affects 2 files
  • bin/fm-session-start.sh#L473-L473 (this comment)
  • tests/fm-session-start.test.sh#L2049-L2055
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@bin/fm-session-start.sh` at line 473, The HOLD-state regex in
bin/fm-session-start.sh lines 473-473 must match only complete values by
requiring whitespace or end-of-line after needs-decision, blocked, or failed.
Add a state=failed-retryable fixture and assert the digest suppresses it in
tests/fm-session-start.test.sh lines 2049-2055.

count=0
[ -n "$held" ] && count=$(printf '%s\n' "$held" | grep -c .)
if [ "$count" -eq 0 ]; then
printf 'parlay: none held for captain action\n'
return
fi
printf 'parlay: %s agent(s) held for captain action\n' "$count"
while IFS= read -r line; do
[ -n "$line" ] || continue
if [ "${#line}" -gt 80 ]; then
printf '%s\n' "${line:0:80}"
else
printf '%s\n' "$line"
fi
done <<EOF
$held
EOF
}

hash_file() {
local file=$1
[ -f "$file" ] || return 1
Expand Down Expand Up @@ -688,6 +717,12 @@ if fm_pf_relay_active "$FM_HOME" \
fi
fi

# --- 7a. parlay sweep --------------------------------------------------
# Read-only parlay sweep surfacing captain-parked agents. Skips silently
# when the parlay binary is absent.
stage parlay
print_parlay_section

# --- 8. closing reminder -----------------------------------------------
stage next-step
section "NEXT STEP"
Expand Down
33 changes: 31 additions & 2 deletions bin/fm-watch.sh
Original file line number Diff line number Diff line change
Expand Up @@ -745,6 +745,35 @@ heartbeat_scan_finds_actionable() {
return 1
}

# parlay_heartbeat_payload: build the heartbeat wake-queue payload including a
# compact parlay sweep summary. When parlay is absent, returns plain "heartbeat".
# Surfaces only needs-decision, blocked, and failed HOLD lines; truncates each
# to 80 chars. Read-only and safe to call at any time.
parlay_heartbeat_payload() {
local sweep held count line summary
command -v parlay >/dev/null 2>&1 || { printf 'heartbeat'; return 0; }
sweep=$(parlay sweep 2>/dev/null) || sweep=
held=$(printf '%s\n' "$sweep" | grep -E '^HOLD[[:space:]].*state=(needs-decision|blocked|failed)' || true)
count=0
[ -n "$held" ] && count=$(printf '%s\n' "$held" | grep -c .)
if [ "$count" -eq 0 ]; then
printf 'heartbeat | parlay: none held'
return
fi
summary="heartbeat | parlay: ${count} agent(s) held"
while IFS= read -r line; do
[ -n "$line" ] || continue
if [ "${#line}" -gt 80 ]; then
summary="${summary} | ${line:0:80}"
else
summary="${summary} | ${line}"
fi
done <<EOF
$held
EOF
printf '%s' "$summary"
}

# event_wait_or_sleep: the terminal wait of each supervision cycle. For a home
# with push-capable windows (herdr), it replaces the blind `sleep POLL` with a
# bounded wait on the backend's native transition stream, so a crew going
Expand Down Expand Up @@ -1383,14 +1412,14 @@ EOF
# without exiting); the away-mode daemon, when present, owns triage and wants
# every heartbeat.
if afk_present; then
fm_wake_append heartbeat heartbeat heartbeat || exit 1
fm_wake_append heartbeat heartbeat "$(parlay_heartbeat_payload)" || exit 1
touch "$STATE/.last-heartbeat"
wake "heartbeat"
Comment on lines +1543 to 1545

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Publish the generated payload.

Line 1415 queues the Parlay-aware payload. Line 1417 publishes the fixed heartbeat string. wake sends its argument to watch_delivery_publish, so the immediate away-mode delivery omits the Parlay report.

Build the payload once. Pass it to both fm_wake_append and wake.

Proposed fix
-      fm_wake_append heartbeat heartbeat "$(parlay_heartbeat_payload)" || exit 1
+      heartbeat_payload=$(parlay_heartbeat_payload)
+      fm_wake_append heartbeat heartbeat "$heartbeat_payload" || exit 1
       touch "$STATE/.last-heartbeat"
-      wake "heartbeat"
+      wake "$heartbeat_payload"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
fm_wake_append heartbeat heartbeat "$(parlay_heartbeat_payload)" || exit 1
touch "$STATE/.last-heartbeat"
wake "heartbeat"
heartbeat_payload=$(parlay_heartbeat_payload)
fm_wake_append heartbeat heartbeat "$heartbeat_payload" || exit 1
touch "$STATE/.last-heartbeat"
wake "$heartbeat_payload"
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@bin/fm-watch.sh` around lines 1415 - 1417, Update the heartbeat flow around
fm_wake_append and wake to build the Parlay heartbeat payload once, store it in
a variable, and pass that same payload to both calls so immediate away-mode
delivery publishes the generated report instead of the fixed heartbeat string.

elif heartbeat_scan_finds_actionable; then
# Backstop: a captain-relevant status the per-wake path absorbed by mistake.
# Enqueue first, then mark every captain-relevant status surfaced so the next
# heartbeat does not re-fire them (enqueue-before-suppress preserved).
fm_wake_append heartbeat heartbeat heartbeat || exit 1
fm_wake_append heartbeat heartbeat "$(parlay_heartbeat_payload)" || exit 1
touch "$STATE/.last-heartbeat"
mark_all_captain_relevant_surfaced
wake "heartbeat"
Expand Down
134 changes: 133 additions & 1 deletion tests/fm-session-start.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -1608,7 +1608,7 @@ EOF
assert_contains "$out" "RUNTIME BOUND" "the truncation banner did not name the bound it hit"
assert_contains "$out" 'stopped during the "bootstrap" stage' "the truncation banner did not name the incomplete stage"
assert_contains "$out" "RECONCILE these stages" "the truncation banner did not tell the agent what to reconcile"
assert_contains "$out" "wake-queue supervision-instructions persona context fleet-state next-step" \
assert_contains "$out" "wake-queue supervision-instructions persona context fleet-state parlay next-step" \
"the truncation banner did not list every stage that never ran"
assert_not_contains "$out" "NEXT STEP" "a truncated digest claimed to have reached its closing reminder"
assert_absent "$home/state/.session-start-complete" \
Expand Down Expand Up @@ -2029,6 +2029,134 @@ EOF
pass "session start rejects Pi loaded markers from previous sessions"
}

# --- parlay sweep section ---------------------------------------------------

test_parlay_section_with_held_agents() {
local rec root home fakebin out fleet_line parlay_line
rec=$(new_world parlay-held)
IFS='|' read -r root home fakebin <<EOF
$rec
EOF
make_fake_toolchain "$fakebin"
make_fake_ps_claude "$fakebin"

# Stub parlay sweep with a canned mix: one needs-decision, one blocked, one
# failed, one unknown (to be ignored), one would-close (to be ignored), and
# one done (to be ignored).
cat > "$fakebin/parlay" <<'SH'
#!/usr/bin/env bash
[ "${1:-}" = sweep ] || exit 0
cat <<'OUT'
HOLD agent-alpha — state=needs-decision — PR #1 green; captain picks merge or park
HOLD agent-beta — state=blocked — waiting on upstream fix before any PR can land
HOLD agent-gamma — state=failed — pipeline exit 1 on the last run
HOLD agent-delta — state=unknown — no status recorded
would-close mc-robots-0shd — done · task robots-0shd
OUT
SH
chmod +x "$fakebin/parlay"

out=$(run_session_start "$home" "$root" "$fakebin:$BASE_PATH")

assert_contains "$out" "PARLAY" "digest did not print a PARLAY section header"
assert_contains "$out" "parlay: 3 agent(s) held for captain action" \
"digest did not print correct hold count (expected 3: alpha, beta, gamma)"
assert_contains "$out" "agent-alpha" "digest did not surface the needs-decision agent"
assert_contains "$out" "agent-beta" "digest did not surface the blocked agent"
assert_contains "$out" "agent-gamma" "digest did not surface the failed agent"
assert_not_contains "$out" "agent-delta" "digest surfaced an unknown-state agent (should be ignored)"
assert_not_contains "$out" "would-close" "digest surfaced a would-close line (should be ignored)"

# PARLAY section must appear after FLEET STATE.
fleet_line=$(printf '%s\n' "$out" | grep -n '^FLEET STATE$' | head -1 | cut -d: -f1)
parlay_line=$(printf '%s\n' "$out" | grep -n '^PARLAY$' | head -1 | cut -d: -f1)
[ -n "$fleet_line" ] && [ -n "$parlay_line" ] || fail "FLEET STATE or PARLAY section header missing: $out"
[ "$parlay_line" -gt "$fleet_line" ] || fail "PARLAY did not follow FLEET STATE"

pass "session start PARLAY section surfaces needs-decision/blocked/failed hold agents"
}

test_parlay_section_none_held() {
local rec root home fakebin out
rec=$(new_world parlay-none-held)
IFS='|' read -r root home fakebin <<EOF
$rec
EOF
make_fake_toolchain "$fakebin"
make_fake_ps_claude "$fakebin"

# Stub parlay sweep with only ignored lines.
cat > "$fakebin/parlay" <<'SH'
#!/usr/bin/env bash
[ "${1:-}" = sweep ] || exit 0
cat <<'OUT'
HOLD agent-alpha — state=unknown — no status recorded
would-close mc-robots-0shd — done · task robots-0shd
OUT
SH
chmod +x "$fakebin/parlay"

out=$(run_session_start "$home" "$root" "$fakebin:$BASE_PATH")

assert_contains "$out" "PARLAY" "digest did not print a PARLAY section header when parlay is present"
assert_contains "$out" "parlay: none held for captain action" \
"digest did not print none-held summary when no agents need captain action"

pass "session start PARLAY section prints none-held summary when no agents are held"
}

test_parlay_section_absent_when_no_binary() {
local rec root home fakebin out
rec=$(new_world parlay-absent)
IFS='|' read -r root home fakebin <<EOF
$rec
EOF
make_fake_toolchain "$fakebin"
make_fake_ps_claude "$fakebin"
# parlay is deliberately NOT added to fakebin; it must not be on PATH.

out=$(run_session_start "$home" "$root" "$fakebin:/usr/bin:/bin")

assert_not_contains "$out" "PARLAY" "digest printed a PARLAY section when parlay binary is absent"
assert_not_contains "$out" "parlay:" "digest printed parlay output when binary is absent"

pass "session start omits PARLAY section silently when parlay binary is absent"
}

test_parlay_section_truncates_long_lines() {
local rec root home fakebin out long_line
rec=$(new_world parlay-truncate)
IFS='|' read -r root home fakebin <<EOF
$rec
EOF
make_fake_toolchain "$fakebin"
make_fake_ps_claude "$fakebin"

# Stub parlay with a HOLD line whose agent description exceeds 80 chars.
long_line="HOLD very-long-agent-name-here — state=needs-decision — $(printf '%0.s x' {1..60})"
cat > "$fakebin/parlay" <<SH
#!/usr/bin/env bash
[ "\${1:-}" = sweep ] || exit 0
printf '%s\n' '$long_line'
SH
chmod +x "$fakebin/parlay"

out=$(run_session_start "$home" "$root" "$fakebin:$BASE_PATH")

assert_contains "$out" "parlay: 1 agent(s) held for captain action" \
"digest did not surface the held agent"
# Each printed HOLD line must be at most 80 chars.
while IFS= read -r line; do
if printf '%s' "$line" | grep -q '^HOLD'; then
[ "${#line}" -le 80 ] || fail "HOLD line exceeds 80 chars: $line"
fi
done <<BLOCK
$out
BLOCK

pass "session start PARLAY section truncates HOLD lines to 80 chars"
}

test_context_digest_absent_empty_present
test_persona_tracked_default_printed
test_persona_local_override_supersedes_default
Expand Down Expand Up @@ -2071,5 +2199,9 @@ test_runtime_bound_leaves_a_healthy_digest_untouched
test_runtime_bound_leaves_harness_ancestry_headroom
test_reemit_skips_startup_sweeps_but_keeps_the_wake_drain
test_reemit_keeps_repair_ownership_with_the_lock_holder
test_parlay_section_with_held_agents
test_parlay_section_none_held
test_parlay_section_absent_when_no_binary
test_parlay_section_truncates_long_lines

echo "# fm-session-start.test.sh: all assertions passed"
7 changes: 7 additions & 0 deletions tests/wake-helpers.sh
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,13 @@ fi
exit 1
SH
chmod +x "$fakebin/tmux"
# Stub parlay with a fast no-op sweep so tests that use PATH="$fakebin:$PATH"
# are not slowed by a real parlay installation on the host.
cat > "$fakebin/parlay" <<'SH'
#!/usr/bin/env bash
exit 0
SH
chmod +x "$fakebin/parlay"
make_fake_crew_state "$fakebin" >/dev/null
printf '%s\n' "$dir"
}
Expand Down
Loading