Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,8 @@ config/wedge-alarm optional away-mode wedge-alarm active-alert directives; LOCA
config/watched-tools.json optional list of the tools this home depends on, read by the update check armed with bin/fm-tool-update-check.sh; LOCAL, gitignored, firstmate-maintained but human-editable, and NOT inherited by secondmate homes; see docs/configuration.md "Watched tool updates"
config/x-mode.env generated Relay watcher cadence; LOCAL, gitignored; source before arming watcher when present
data/ personal fleet records; LOCAL, gitignored as a whole
firstmate.identity persistent human-friendly name for this exact Firstmate home; bin/fm-identity-lib.sh owns the record
crew-identities/ persistent callsign bindings and historical non-rebinding records for this home's tasks; bin/fm-identity-lib.sh owns the records
backlog.md task queue, dependencies, history
captain.md this home's domain-local captain preferences and working style; LOCAL, gitignored, canonical even if harness memory mirrors it, and updated with inspect-then-update
captain-shared.md main-authoritative shared captain preferences propagated read-only to secondmate homes; LOCAL, gitignored, owned by secondmate-provisioning
Expand Down Expand Up @@ -300,10 +302,10 @@ The spawn must resolve a genuine isolated task worktree distinct from the primar
After spawning, confirm the worker is processing the brief, handle any trust dialog through `harness-adapters`, and record ship or scout work as under way.
A persistent secondmate is recorded in the secondmate registry and runtime state, never as a backlog work item.

Steer a worker with short single-line messages through fail-closed `fm-send`; put long instructions in a file.
Address workers by callsign in captain-facing language and steer one with short single-line messages through `fm-send`; exact task IDs remain the internal identity, and `bin/fm-identity-lib.sh` owns unambiguous names-first resolution.
When a steer answers an open keyed decision or blocker, pass `fm-send`'s `--resolve-key` so the answer itself closes that decision record at answer time, identically for local and remote workers (contract: `bin/fm-send.sh` header).
`fm-send` is the data plane for text the worker should read; never use its key or text paths for interrupt, exit, or other lifecycle control, because routing-marked lifecycle text becomes chat the worker reasons about instead of executing.
Drive a worker's lifecycle through `bin/fm-control.sh <task-id> interrupt|exit|relaunch`, which owns the per-runtime mechanics, verifies each action, and never tears down or discards anything ([`docs/agent-control.md`](docs/agent-control.md)).
Drive a worker's lifecycle through `bin/fm-control.sh <callsign-or-task-id> interrupt|exit|relaunch`, which owns the per-runtime mechanics, verifies each action, and never tears down or discards anything ([`docs/agent-control.md`](docs/agent-control.md)).
Codex ship conversation continuity is opt-in only through `exit --resumable` and `relaunch --resume --note <text>`; ordinary lifecycle calls remain disposable, and no caller may substitute `--last`, a label, cwd recency, or a terminal UUID scan for the exact recorded session binding.
A secondmate's routed reply returns through status or a document pointer, not by firstmate peeking into its chat.
For the parent-owned correlation, recovery, and escalation contract on marked secondmate requests, see `bin/fm-pending-reply-lib.sh`.
Expand Down
16 changes: 9 additions & 7 deletions bin/fm-bearings-snapshot.sh
Original file line number Diff line number Diff line change
Expand Up @@ -111,10 +111,10 @@ usage: fm-bearings-snapshot.sh [--json] [--include-prs] [--fields <list>]
Compact bearings projection over fm-fleet-snapshot.sh. TOON by default.
Default is LOCAL-ONLY (no network); --include-prs is the only path that fetches.

Default fields: schema, home, generated, prs, in_flight{id,kind,state,doing},
Default fields: schema, home, generated, prs, in_flight{id,callsign,kind,state,doing},
secondmates{id,state,doing,provenance,freshness,age_seconds,contradiction,reason},
decisions_open{id,key,verb,summary,owner}, landed{id,what,artifact,owner},
gates{id,title,blocked_by,reason,owner}, reports{id,path}, recorded_prs{id,url},
decisions_open{id,key,verb,summary,owner}, landed{id,callsign,what,artifact,owner},
gates{id,title,blocked_by,reason,owner}, reports{id,callsign,path}, recorded_prs{id,url},
unhealthy_endpoints{...} (only when non-empty), omitted{surface,reveal}.
landed merges this home's Done with registered secondmate homes' Done, bounded by
a per-home cap (FM_BEARINGS_LANDED_PER_HOME) and an overall cap (FM_BEARINGS_LANDED),
Expand Down Expand Up @@ -319,13 +319,15 @@ MODEL=$(printf '%s' "$SNAP" | jq \
| $groups[]
| select(length > $i)
| .[$i]][:$n];
(.identities // []) as $identities
| def callsign_for($id): ([ $identities[] | select(.id == $id) | .callsign ][0] // $id);
Comment on lines +322 to +323

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: Build an id-to-callsign lookup object once from identities, then perform constant-time lookups in callsign_for instead of scanning the entire identities array for every landed, in-flight, and report row. [custom_rule]

Severity Level: Major ⚠️

Why it matters? ⭐

The jq function scans the entire identities array for every callsign lookup. It is invoked while projecting multiple landed, in-flight, and report rows, causing repeated linear work proportional to the number of output rows times the identity count. Building an id-to-callsign object once would make each lookup constant-time and avoid this repeated computation on larger fleets.

Rule source 📖

CodeAnt dashboard (rule "agent-persona-performance")

Use CodeAnt Skill

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** bin/fm-bearings-snapshot.sh
**Line:** 322:323
**Comment:**
	*Custom Rule: Build an id-to-callsign lookup object once from `identities`, then perform constant-time lookups in `callsign_for` instead of scanning the entire identities array for every landed, in-flight, and report row.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

($fields | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(. != ""))) as $fl
| (($fl | index("bodies")) != null) as $f_bodies
| (($fl | index("paths")) != null) as $f_paths
| (($fl | index("actions")) != null) as $f_actions
| (($fl | index("endpoints")) != null) as $f_endpoints
| ([ .backlog.records[] | select(.state == "done" and .structured and .hold_kind != "captain")
| {id, title, pr_url, report_path, local_note, completion, home:"(main)", home_id:"(main)"} ]) as $main_done
| {id, callsign:callsign_for(.id), title, pr_url, report_path, local_note, completion, home:"(main)", home_id:"(main)"} ]) as $main_done
| ((.secondmate_landed.records) // []) as $mate_done
| ($main_done + $mate_done) as $all_landed_rows
| ([ $all_landed_rows | group_by(.home_id)[]
Expand Down Expand Up @@ -383,7 +385,7 @@ MODEL=$(printf '%s' "$SNAP" | jq \
| select(.kind != "secondmate")
| select(.backlog.current_role != "program")
| select(.backlog.current_role != "held" or .current_state.state == "working")
| {id, kind,
| {id, callsign:(.callsign // callsign_for(.id)), kind,
state: .current_state.state,
doing: ((.current_state.detail // "") as $d
| (if $d != "" then $d else (.hints.last_event_text // "") end) | trunc(90))
Expand Down Expand Up @@ -441,7 +443,7 @@ MODEL=$(printf '%s' "$SNAP" | jq \
| ([ .scout_reports[]
| . as $r
| select(($all_reports == 1) or (($rel_ids | index($r.id)) != null))
| {id, path} ]) as $reports_all
| {id, callsign:callsign_for(.id), path} ]) as $reports_all
| ([ .tasks[] | select(.kind != "secondmate" and .pr.url != null and .pr.source == "meta") | {id, url:.pr.url} ]) as $recorded_prs_all
| . as $snap
| {
Expand All @@ -452,7 +454,7 @@ MODEL=$(printf '%s' "$SNAP" | jq \
in_flight: (if $all_in_flight == 1 then $in_flight_all else $in_flight_all[:$in_flight_n] end),
secondmates: (if $all_secondmates == 1 then $secondmates_all else $secondmates_all[:$secondmates_n] end),
decisions_open: (if $all_decisions == 1 then $decisions_all else $decisions_all[:$decisions_n] end),
landed: ($done | map({id, what:(.title | trunc(70)),
landed: ($done | map({id, callsign:(.callsign // callsign_for(.id)), what:(.title | trunc(70)),
artifact:(.pr_url // .report_path // .local_note // "-"),owner:.home_id})),
gates: (if $all_queued == 1 then $gates_all else $gates_all[:$gates_n] end),
reports: (if $all_reports == 1 then $reports_all else $reports_all[:$reports_n] end),
Expand Down
59 changes: 32 additions & 27 deletions bin/fm-control.sh
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
# fm-control.sh - the CONTROL PLANE for a firstmate-owned agent: allowlisted
# lifecycle verbs addressed to an exact task id.
# lifecycle verbs addressed to an exact task id or persistent callsign.
#
# Usage: fm-control.sh <task-id> interrupt
# fm-control.sh <task-id> exit [--resumable]
Expand Down Expand Up @@ -65,12 +65,10 @@
# exit/relaunch, fresh spawn, scouts, secondmates, and every other harness keep
# the disposable brief-plus-note behavior above.
#
# Targeting is EXACT: only a bare task id with a state/<id>.meta record in
# THIS home is accepted, and the record must pass the shared endpoint-identity
# validation (bin/fm-backend.sh's fm_backend_validate_task_endpoint). A legacy
# fm-<id> label, an explicit session:window endpoint, and a bare window name
# are all refused - a lifecycle command delivered to the wrong endpoint is far
# worse than a loud refusal.
# Targeting is EXACT: a persistent callsign resolves through the home-owned
# identity registry to exactly one task id before endpoint validation. A bare
# task id remains supported. Missing, ambiguous, archived-only, conflicting,
# explicit session:window, and bare window targets are refused.
#
# A remotely placed secondmate is refused by name: its agent runs on another
# host, so no postcondition this plane verifies could be read for it here.
Expand Down Expand Up @@ -131,6 +129,8 @@ DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}"

# shellcheck source=bin/fm-backend.sh
. "$SCRIPT_DIR/fm-backend.sh"
# shellcheck source=bin/fm-identity-lib.sh
. "$SCRIPT_DIR/fm-identity-lib.sh"
# shellcheck source=bin/fm-busy-lib.sh
. "$SCRIPT_DIR/fm-busy-lib.sh"
# shellcheck source=bin/fm-control-lib.sh
Expand Down Expand Up @@ -179,10 +179,21 @@ VERB=${2:-}
[ -n "$RAW_ID" ] && [ -n "$VERB" ] || { usage >&2; exit 2; }
shift 2

case "$RAW_ID" in
*:*) die "'$RAW_ID' is an explicit backend endpoint; fm-control accepts a callsign or exact task id only, so a lifecycle command can never land on an endpoint this home does not own" ;;
fm-*)
if [ -f "$STATE/${RAW_ID#fm-}.meta" ]; then
die "'$RAW_ID' is a legacy window label, not a callsign or exact task id; pass the exact task id '${RAW_ID#fm-}' or that task's callsign"
fi
;;
esac
ID=$(fm_identity_resolve_selector "$STATE" "$RAW_ID") || exit 1
CALLSIGN=$(fm_identity_display_callsign "$ID")

if ! fm_control_verb_allowed "$VERB"; then
{
if [ "$VERB" = resume ]; then
echo "error: 'resume' is not a control verb: resuming an exited agent is not deterministic across the verified adapters (codex and grok need a session id printed at exit, opencode continues the most recent session for the cwd, and claude, pi, pi-signed, and kimi have no verified pane-resume contract). Use 'relaunch', which carries the brief plus a progress note into a fresh agent on any adapter."
echo "error: resume resolved $CALLSIGN ($ID), but exact-thread resume is not installed for this task. Use 'relaunch' for a fresh replacement, or the resumable-crewmate command when that opt-in capability owns the recorded harness session."
else
echo "error: '$VERB' is not a control verb"
fi
Expand Down Expand Up @@ -262,30 +273,24 @@ case "$NEW_EFFORT" in
*) die "--effort must be one of low, medium, high, xhigh, max" ;;
esac

# --- exact task-id resolution ----------------------------------------------
# --- exact task identity resolution ----------------------------------------

case "$RAW_ID" in
*:*) die "'$RAW_ID' is an explicit backend endpoint; fm-control accepts an exact task id only, so a lifecycle command can never land on an endpoint this home does not own" ;;
esac
if ! fm_task_id_creation_valid "$RAW_ID"; then
die "'$RAW_ID' is not a valid task id"
if ! fm_task_id_creation_valid "$ID"; then
die "resolved task id '$ID' is invalid"
fi
if [ ! -f "$(fm_identity_task_record "$ID")" ]; then
fm_identity_ensure_task_from_meta "$STATE/$ID.meta" "$ID" 1 >/dev/null \
|| die "legacy task $ID could not receive a persistent callsign"
CALLSIGN=$(fm_identity_display_callsign "$ID")
fi
ID=$RAW_ID
CONTROL_LOCK="$STATE/.control-$ID.lock"
trap control_cleanup EXIT
fm_lock_try_acquire "$CONTROL_LOCK" \
|| die "another lifecycle action is already running for task $ID"
CONTROL_LOCK_HELD=1
META="$STATE/$ID.meta"
if [ ! -f "$META" ]; then
case "$RAW_ID" in
fm-*)
if [ -f "$STATE/${RAW_ID#fm-}.meta" ]; then
die "'$RAW_ID' is a window label, not a task id; pass the exact task id '${RAW_ID#fm-}'"
fi
;;
esac
die "no task '$ID' in $STATE (fm-control resolves an exact task id only)"
die "no active task for $CALLSIGN ($ID) in $STATE"
fi

# A remotely placed secondmate records its endpoint on ANOTHER host, so every
Expand Down Expand Up @@ -1056,9 +1061,9 @@ do_relaunch() {
RELAUNCH_ACTIVE=0
rm -f "$RELAUNCH_RESUME_ATTEMPT"
if [ "$RESUME_RELAUNCH" = 1 ]; then
echo "resumed $ID session=$RELAUNCH_RESUME_SESSION harness=codex model=$TARGET_MODEL effort=$TARGET_EFFORT backend=$BACKEND endpoint=$T worktree=$WT"
echo "resumed $CALLSIGN ($ID) session=$RELAUNCH_RESUME_SESSION harness=codex model=$TARGET_MODEL effort=$TARGET_EFFORT backend=$BACKEND endpoint=$T worktree=$WT"
else
echo "relaunched $ID harness=$TARGET_HARNESS from=$PRIOR_RECORDED_HARNESS model=$TARGET_MODEL effort=$TARGET_EFFORT backend=$BACKEND endpoint=$T worktree=$WT"
echo "relaunched $CALLSIGN ($ID) harness=$TARGET_HARNESS from=$PRIOR_RECORDED_HARNESS model=$TARGET_MODEL effort=$TARGET_EFFORT backend=$BACKEND endpoint=$T worktree=$WT"
fi
}

Expand All @@ -1079,7 +1084,7 @@ case "$VERB" in
*) die "task $ID's endpoint reads '$state' rather than a positively classified state; refusing to send a lifecycle key into an unattributed endpoint" ;;
esac
proof=$(do_interrupt)
echo "interrupt-delivered $ID harness=$HARNESS backend=$BACKEND verified=$proof"
echo "interrupt-delivered $CALLSIGN ($ID) harness=$HARNESS backend=$BACKEND verified=$proof"
;;
exit)
if [ "$RESUMABLE_EXIT" = 1 ]; then
Expand All @@ -1091,7 +1096,7 @@ case "$VERB" in
|| die "task $ID stopped, but its prior Codex session binding could not be retired safely"
fi
fi
echo "$result $ID harness=$HARNESS backend=$BACKEND endpoint=$T worktree=$WT"
echo "$result $CALLSIGN ($ID) harness=$HARNESS backend=$BACKEND endpoint=$T worktree=$WT"
;;
relaunch)
do_relaunch
Expand Down
18 changes: 14 additions & 4 deletions bin/fm-crew-state.sh
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
# fixed mapping logic, no heuristics and no LLM. Output is one stable, parseable,
# token-tight line firstmate can read every heartbeat:
#
# state: <working|parked|done|blocked|paused|failed|unknown> · source: <run-step|pane|status-log|remote-endpoint|none> · <detail>
# state: <working|parked|done|blocked|paused|failed|unknown> · source: <run-step|pane|status-log|remote-endpoint|none> · <detail> · identity: <callsign> (<task-id>)
#
# Logic, in order:
# 1. Resolve worktree + backend target + kind from state/<id>.meta. A meta
Expand Down Expand Up @@ -50,7 +50,8 @@
# recorded backend's pane busy state, then the status log's last line only
# when its verb maps to a recognized run-state. Decision-only events such as
# `resolved` never become current state or detail.
# 5. Missing meta or torn-down worktree: report unknown · none. If no run is
# 5. A missing selector refuses before state inspection. A torn-down worktree
# with a still-present task record reports unknown · none. If no run is
# attributed to this crew, a dead endpoint also reports unknown · none rather
# than trusting a stale status log.
#
Expand All @@ -67,15 +68,23 @@ STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
. "$SCRIPT_DIR/fm-tmux-lib.sh"
# shellcheck source=bin/fm-backend.sh
. "$SCRIPT_DIR/fm-backend.sh"
# shellcheck source=bin/fm-identity-lib.sh
. "$SCRIPT_DIR/fm-identity-lib.sh"
# shellcheck source=bin/fm-classify-lib.sh
. "$SCRIPT_DIR/fm-classify-lib.sh"
# shellcheck source=bin/fm-busy-lib.sh
. "$SCRIPT_DIR/fm-busy-lib.sh"
# shellcheck source=bin/fm-nm-run-lib.sh
. "$SCRIPT_DIR/fm-nm-run-lib.sh"

ID=${1:-}
[ -n "$ID" ] || { echo "usage: fm-crew-state.sh <id>" >&2; exit 2; }
RAW_SELECTOR=${1:-}
[ -n "$RAW_SELECTOR" ] || { echo "usage: fm-crew-state.sh <task-id-or-callsign>" >&2; exit 2; }
set +e
ID=$(fm_identity_resolve_selector "$STATE" "$RAW_SELECTOR")

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: Use an indexed callsign-to-task lookup or a resolver that returns the callsign together with the task id, rather than scanning and validating the entire identity registry on every state read. [custom_rule]

Severity Level: Major ⚠️

Why it matters? ⭐

For callsign selectors, fm_identity_resolve_selector iterates over every identity record and validates each candidate, and even exact task-id resolution performs a registry-wide conflict scan. This helper is used on every state read, so repeated polling can cause avoidable filesystem scans and shell processing as the number of retained identity records grows. An indexed lookup or a resolver that returns the resolved identity in one operation would reduce that repeated work while preserving the ambiguity and historical-name checks.

Rule source 📖

CodeAnt dashboard (rule "agent-persona-performance")

Use CodeAnt Skill

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** bin/fm-crew-state.sh
**Line:** 83:83
**Comment:**
	*Custom Rule: Use an indexed callsign-to-task lookup or a resolver that returns the callsign together with the task id, rather than scanning and validating the entire identity registry on every state read.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

IDENTITY_RC=$?
set -u
[ "$IDENTITY_RC" -eq 0 ] || exit 1
CALLSIGN=$(fm_identity_display_callsign "$ID")

META="$STATE/$ID.meta"
LOG="$STATE/$ID.status"
Expand All @@ -93,6 +102,7 @@ SEP=' · '
emit() { # <state> <source> [detail]
local line="state: $1${SEP}source: $2"
[ -n "${3:-}" ] && line="$line${SEP}$3"
line="$line${SEP}identity: $CALLSIGN ($ID)"
printf '%s\n' "$line"
exit 0
}
Expand Down
Loading