菜单
Use when configuring an ap2 daemon — discovering or tuning an `AP2_*` environment knob, authoring `.cc-autopilot/config.toml` keys (`[core]` / `[components.*]` / `[agent_backends]`), or setting up the Codex agent backend.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when operating an ap2 board — running an `ap2 <verb>` operator-CLI command (start/stop/status/add/approve/unfreeze/rollback/cron/sandbox/…), or reaching for an `autopilot` custom MCP tool (`report_result`, `board_edit`, `operator_queue_append`, `cron_propose`, …) from an agent toolset.
Use when authoring or revising an ap2 project's `goal.md` (Mission / Done-when / Current focus / Non-goals / Constraints, the delete-test, and the TB-161/TB-164/TB-235 queue-time validators) or running the retrospective `ap2 audit` review of what shipped after a walk-away window.
Use when inspecting ap2 event types, the events.jsonl timeline, prose-judge verification diagnostics, `ap2 logs` / stats-dashboard output, or the `ap2 status` components block (which subsystems are wired and their on/off state).
Use when an ap2 daemon hit trouble — a task failed / froze / retry-exhausted, the daemon restarted with an Active task, a pipeline or agent crashed, the watchdog went quiet, or you need to intervene (`ap2 unfreeze` / `ap2 delete`) or answer 'why did TB-N fail / what just happened?'.
Check status + recent work of an ap2 daemon for a specific project (board state, daemon liveness, recent events, recent commits, last task summary).
Add a task to an ap2 sandbox project's Backlog by authoring a briefing markdown file and passing it to `ap2 add --briefing-file` (locks TASKS.md, issues a fresh TB-N, no ID collisions). Auto-detects whether to run as the sandbox user directly or escalate via sudo from the main user. Also the operator-facing reference for the task-agent contract, authoring `## Verification` bullets (the `Prose:` prefix + the four shell-bullet pitfalls), and `ap2 classify` impact verdicts — mirroring the daemon-canonical authoring rules in `ap2/ideation.default.md`.
| name | ap2-config |
| description | Use when configuring an ap2 daemon — discovering or tuning an `AP2_*` environment knob, authoring `.cc-autopilot/config.toml` keys (`[core]` / `[components.*]` / `[agent_backends]`), or setting up the Codex agent backend. |
The operator-facing configuration reference for an ap2 daemon. Discover or tune any tunable here — an operator should never have to hunt through the ap2 source for a knob.
Two surfaces, split along the 12-factor cut-line (TB-413). Behavioral tunables and secrets/deployment-identity live in different files now; pick the right one:
.cc-autopilot/config.toml — the SOLE source for behavioral tunables.
Loop cadence + per-run timeouts, agent model/effort, verification, the
briefing validator, the auto-approve / auto-unfreeze gates, ideation,
watchdog, attention, janitor, the per-agent-kind backend map — author them
here (typed [core.*] / [components.<name>.*] / [agent_backends]
tables) or run ap2 config set <key> <value> (e.g. ap2 config set core.task_max_turns 500). See Config keys (TOML) below..cc-autopilot/env — SECRETS + DEPLOYMENT-IDENTITY only. Credentials
/ integration secrets and the per-daemon deployment identity an operator
running several daemons against one project sets per deployment
(config.ENV_PERMITTED_KEYS: Mattermost channels + auth, web host/port,
sandbox user, project name, channel-file path, tick intervals, the
integration secrets). Nothing here changes the daemon's behavior beyond
which credentials / channels / ports / identity it wires up. The fresh-
project ap2 init env scaffold (ap2.init.ENV_TEMPLATE) documents exactly
this allowlist and nothing else.No flat-AP2_<tunable> override anymore (TB-413). Setting a behavioral
tunable's flat env name (e.g. AP2_TASK_MAX_TURNS=999) no longer overrides
config.toml — the reverse-FLAT_TO_SECTIONED override path was removed, so
such a name is simply IGNORED (and emits no env_deprecated event). Only the
ENV_PERMITTED_KEYS allowlist members still resolve from env. The
Configuration knobs catalogue below still enumerates every flat AP2_*
name (it is the operator-facing name → config.toml key reference, and the
docs-drift gate requires it), but for a behavioral tunable that name is now a
lookup key into config.toml, not a live env override.
Two docs-drift gates in ap2/tests/test_docs_drift.py keep this skill in
lock-step with the source: test_every_env_knob_documented (every AP2_*
knob read in ap2/*.py carries a backtick-fenced mention here) and
test_every_config_key_documented (every ConfigKey declared on a
component or core schema is documented here). A source-side knob / key
addition that skips this skill trips one of those gates until docs catch
up.
This catalogue enumerates every flat AP2_* name the ap2 source consults
(grep -nE 'AP2_[A-Z_]+' ap2/*.py is the source-of-truth — the
test_every_env_knob_documented gate in ap2/tests/test_docs_drift.py
fails CI if a new knob is added and not listed here).
Where each name actually resolves (TB-413). The flat name doubles as the operator-facing lookup key, but only two classes still read from env:
config.ENV_PERMITTED_KEYS) — the
only knobs .cc-autopilot/env is for. Set them in shell, in
<project>/.cc-autopilot/env, or in ~claude-agent/.zshenv. This is what
the ap2 init env scaffold documents..cc-autopilot/config.toml (the core.<key> / components.<name>.<key>
path each row names; author it there or via ap2 config set). The flat
AP2_<tunable> env name is IGNORED post-TB-413 — it no longer
overrides config.toml and emits no env_deprecated event. The rows below
keep the flat name so an operator who knows the old name can find its TOML
key (cross-referenced in Config keys (TOML)), not because setting the
env var still works.12-factor exempt set + CI gate (TB-338). The subset of knobs that
NEVER migrate to TOML — Mattermost auth / channel identity, integration
secrets (AP2_WEBHOOK_URL), deployment-environment paths
(AP2_CHANNEL_FILE_PATH), sandbox-identity placeholders (AP2_DIR,
AP2_REAL_SDK) — is enumerated in
ap2/config_compat.py::_KNOBS_STAYING_ENV_ONLY. The
test_tb338_env_only_cut_line gate enforces this cut-line on every
PR: any new os.environ.get("AP2_…") read added outside the exempt
set + the ap2/config.py / ap2/env_reload.py bootstrap path fails
CI until the author migrates via cfg.get_*_value or explicitly
documents the new knob in _KNOBS_STAYING_ENV_ONLY with a one-line
justification:
12-factor exempt set + CI gate (TB-338). The subset of knobs that
NEVER migrate to TOML — Mattermost auth / channel identity, integration
secrets (AP2_WEBHOOK_URL), deployment-environment paths
(AP2_CHANNEL_FILE_PATH), sandbox-identity placeholders (AP2_DIR,
AP2_REAL_SDK) — is enumerated in
ap2/config_compat.py::_KNOBS_STAYING_ENV_ONLY. The
test_tb338_env_only_cut_line gate enforces this cut-line on every
PR: any new os.environ.get("AP2_…") read added outside the exempt
set + the ap2/config.py / ap2/env_reload.py bootstrap path fails
CI until the author migrates via cfg.get_*_value or explicitly
documents the new knob in _KNOBS_STAYING_ENV_ONLY with a one-line
justification:
Hot-reload vs restart (TB-271). Most tunable knobs (timeouts,
max-turns, model/effort, auto-approve / auto-unfreeze thresholds,
verify gate, tick intervals, ideation knobs, watchdog thresholds)
hot-reload — the daemon re-sources .cc-autopilot/env at the top of
every _tick, refreshes the tunable Config fields in-place, and
overwrites os.environ for file-sourced keys. A bumped knob takes
effect on the next tick (≤30s) without ap2 stop && ap2 start. The
canonical set is env_reload.HOT_RELOADABLE_KNOBS; the reload emits
an env_reloaded event with the changed keys for the audit trail.
TB-323 extended the watcher to .cc-autopilot/config.toml as well — a
bumped mtime on EITHER file triggers the next-tick HOT_RELOADABLE-
filtered refresh, so an operator editing the TOML to bump a tunable
gets the same propagation an env-file edit enjoys. (The TOML values
themselves are not re-parsed by the reload helper — os.environ is
the authoritative source for the refresh pass; the structured-config
layer's env-override / back-compat shim already wrote there at
daemon-start.)
A small fixed-knob set (env_reload.FIXED_KNOBS — AP2_WEB_PORT,
AP2_WEB_DISABLED, AP2_MM_CHANNELS) still requires a restart:
each configures a stateful resource (a bound HTTP socket, a
subscribed MM channel set) wired up once at daemon-start and not
re-applied by the reload. TB-260's WARN: .cc-autopilot/env modified ... ap2 stop && ap2 start line persists for the fixed-knob set and
clears automatically after a hot-reload that only touched
hot-reloadable knobs. "Shell export wins" still holds for keys
never sourced from the file: a export AP2_FOO=bar in the
operator's shell takes precedence over a AP2_FOO=baz later added
to the file, even on reload (you'd need to either un-export and
restart, or set the value via the file before daemon-start).
Loop cadence + per-run timeouts.
AP2_TICK_S (30) — main-loop tick interval.AP2_MM_TICK_S (10) — Mattermost polling tick interval (separate
loop, TB-122).AP2_TASK_TIMEOUT_S (1200) — per-task SDK query timeout.AP2_TASK_MAX_TURNS (200) — max turns per task agent (raised from
50 in TB-278 after TB-122 hit error_max_turns at 51 turns; this
project's own env bumps further to 500 for heavy refactors).AP2_CONTROL_TIMEOUT_S (1200) — per-control-agent timeout (cron,
ideation, MM handler). Raised from 300s in TB-278 — xhigh-effort
ideation routinely blew the old 5-min wall.AP2_CONTROL_MAX_TURNS (15) — max turns per control agent (cron
AP2_IDEATION_MAX_TURNS (100) — max turns for the ideation agent
(raised from 30 in TB-278 after a goal.md rewrite mid-cycle hit
error_max_turns at 31 turns; ideation's Step 0 / 0.5 / 1.5 chain
runs deeper than other control jobs).AP2_MAX_RETRIES (3) — failed-task retries before Frozen.AP2_EVENT_CONTEXT (50) — count of recent events inlined into agent
prompts.Agent model + effort. Per-run knobs that override the per-job default.
AP2_AGENT_MODEL (claude-opus-4-7) — model for task agents and
the SDK-judge plumbing (verifier, janitor).AP2_AGENT_EFFORT (xhigh) — global effort level. Each
sub-job has its own override that falls back here:
AP2_STATUS_REPORT_EFFORT, AP2_VERIFY_JUDGE_EFFORT,
AP2_JANITOR_JUDGE_EFFORT.AP2_THINKING_BLOCK_EFFORT_DROP_DISABLED (unset → enabled) — kill
switch for the TB-356 graceful-degradation path. By default, when a
task run fails with the bundled-CLI thinking-block-immutability 400
(... thinking or redacted_thinking blocks in the latest assistant message cannot be modified, surfaced as a generic task_error), the
daemon steps THAT task's effort down one tier on the automatic retry
(xhigh→high→medium→low, floored at low) and emits an
effort_downshift event. The first attempt always runs at full
AP2_AGENT_EFFORT; only this specific 400 triggers a one-tier drop
per occurrence (other failure classes retry at unchanged effort). Set
to 1 / true / yes / on to disable — constant effort, blind
retry as before.AP2_VERIFY_JUDGE_MAX_TURNS (20), AP2_JANITOR_JUDGE_MAX_TURNS (12)
— max turns for the per-bullet prose-judge and the janitor chore-judge.Verification.
AP2_VERIFY_CMD — project-wide regression gate (e.g.
uv run pytest -q). Unset = no project-wide gate.AP2_VERIFY_JUDGE_DISABLED — hard off-switch for the per-task
verifier's optional LLM prose-bullet judge. TB-382 had modeled the
prose judge as a verifier_judge component; TB-386 demoted it back
into the core verify runner (a judge invoked only as an internal
sub-step of verify_task is not a loop-level participant), so this is
now a plain config knob read directly by verify.py::verify_task via
os.environ.get. When set to a truthy value (1 / true / yes),
verify_task skips the SDK judge and prose bullets record as
unverified (soft, non-gating) while the deterministic shell bullets
still gate — so a deployment can verify with shell bullets alone. Prose
judging is on by default; mirrors AP2_VALIDATOR_JUDGE_DISABLED.AP2_VERIFY_TIMEOUT_S (600) — timeout for the project-wide gate.
ap2 doctor warns when set below observed-typical successful verify
duration (TB-252; reads verify_passed events for the last 7 days
or 20 samples, whichever is larger; uses max() of durations so the
worst-case successful run sizes the recommendation).Briefing validator (LLM-judge dependency coherence, TB-235). Check
#7 in ap2/briefing_validators.py::_validate_briefing_structure (TB-262
split out of ap2/tools.py) runs a Haiku-4.5
judge over a freshly-authored briefing AFTER the six deterministic
checks (TB-154 canonical sections, TB-91/TB-102 parseable Verification,
≥1 bullet, TB-161 goal-anchor, TB-164 Why-now, TB-171 no-Manual)
pass. The judge identifies "hard predecessors" the briefing's prose
names implicitly (e.g. "ap2/_shared.py must already exist — created
by the _locked extraction") and the validator rejects when any judge-
named TB-N is missing from the task's @blocked: codespan. Closes
the dependency-coherence hole that under AP2_AUTO_APPROVE=1
(TB-223) would let ideation auto-promote a task out of dispatch
order — TB-220's prose vs codespan mismatch is the canonical
historical instance. Fail-open by design: on judge timeout / parse
failure / SDK error the validator logs a validator_judge_timeout
or validator_judge_fail event and lets the briefing through (the
cron status-report surfaces a climbing skip rate so operators
notice). The check fires on both do_operator_queue_append
(primary surface — ideation, MM handler, operator CLI all hit it)
and do_board_edit (legacy direct-board-mutation path) for shape
symmetry.
AP2_VALIDATOR_JUDGE_DISABLED — hard off-switch. When set to a
truthy value (1 / true / yes), check #7 is bypassed
entirely and the validator falls back to the six deterministic
checks. Operator escape hatch if the judge is causing false-
positives during a specific workflow; the deterministic gates
still fire so the briefing-shape contract is preserved.AP2_VALIDATOR_JUDGE_TIMEOUT_S (default 60) — wall-clock timeout
for the per-briefing judge call. Exceeded → log
validator_judge_timeout event + skip the check. TB-269 bumped the
default from 15 → 60 after the TB-257 investigation artifact
(.cc-autopilot/insights/validator-judge-timeout-2026-05-18.md)
measured the real SDK call at 17.6-46.8s wall-clock — the previous
20s ceiling (15s default + 5s outer-thread grace) sat below the
median completion of even the smallest measured briefing, so the
axis-1 dep-coherence gate was silently fail-open on essentially
every operator queue-append. The doctor surface
validator_judge_timeout_audit in ap2/doctor.py (TB-269; axis-1
mirror of TB-252's verify_timeout_audit) closes the calibration-
drift loop — it reads validator_judge_passed events from
.cc-autopilot/events.jsonl and surfaces a WARN with a one-line
fix recommendation if a future workload shift takes the observed-
typical successful call duration back above the configured floor.
TB-270 ships the complementary axis-1 lever the same artifact named
as the secondary factor (prompt-too-heavy):
_slice_briefing_for_dep_judge(briefing_text) in
ap2/briefing_validators.py (the dep-coherence judge lived in the
flat module ap2/validator_judge.py until TB-316 moved it to a
validator_judge component, then TB-386 demoted it back into the core
briefing-validation runner) narrows the user payload's
briefing_markdown field to the briefing's ## Goal + ## Scope
sections only (Design / Verification / Out-of-scope are bytes the
judge wouldn't have used to change its hard-predecessor verdict).
Shrinks typical input from ~6KB → ~1-2KB and the SDK wall-clock
proportionally — independent of the timeout knob, so the two
levers compound. Defensive fallback in the helper returns the full
briefing_text on briefings missing either canonical heading or
with empty section bodies, guaranteeing the judge is never blind
on legacy / hand-edited shapes.AP2_VALIDATOR_JUDGE_MAX_TURNS (default 2) — TB-249 canonical
budget knob. Bounds the judge's SDK turn count. The validator is a
single-shot JSON-emitting judge: one assistant message (the verdict)
2 keeps the call
bounded and the cost ≤$0.005 at Haiku rates. Mirrors the
AP2_VERIFY_JUDGE_MAX_TURNS / AP2_JANITOR_JUDGE_MAX_TURNS knob
pattern (the SDK's native budget primitive).AP2_VALIDATOR_JUDGE_MAX_TOKENS — deprecated alias kept for
one-cycle backward compatibility (TB-249). If set AND
AP2_VALIDATOR_JUDGE_MAX_TURNS is unset, the value is reused as
max_turns, ceiling-capped at 5 (so a stale 500 from the pre-
TB-249 default doesn't translate into a 500-turn runaway). Emits a
one-shot-per-process validator_judge_deprecated_knob event the
first time the alias resolves; a future TB removes the alias once
operator engagement confirms no env files still carry it. Migration:
rename to AP2_VALIDATOR_JUDGE_MAX_TURNS with a value in [1, 5]
(default 2) — the old 500 (output-token cap) translates to a
turn budget of 5 after the cap.AP2_VALIDATOR_JUDGE_NOISY_THRESHOLD (default 5) — TB-243 surface
threshold. When the rolling 24h sum
validator_judge_fail_count_24h + validator_judge_timeout_count_24h
is ≥ this number, ap2 status appends [noisy] to its
validator-judge: sub-line and the web home Automation card's
"Validator judge (24h)" row gets the warn-tint (amber). Below the
threshold both surfaces stay in the neutral palette so a single
transient SDK blip doesn't tint the card. Closes the silent-
degradation hazard left by the fail-open design above: an
operator with AP2_AUTO_APPROVE=1 whose judge has been quietly
timing out for the last N briefings sees the warn-tint before the
next audit. Unset / empty / non-int / non-positive → default
(matches the TB-224 / TB-234 token-cap parse semantics). TB-272
promotes the same threshold to a load-bearing safety floor: the
auto-approve dispatch path now pauses (emits
auto_approve_skipped reason=validator_judge_noisy) when the
rolling-24h sum crosses this threshold — see
AP2_AUTO_APPROVE_NOISY_PAUSE_DISABLED below for the opt-out.AP2_AUTO_APPROVE_NOISY_PAUSE_DISABLED — TB-272 opt-out for the
validator-judge noisy-state auto-approve pause. Unset by default
→ pause ACTIVE (the safety-floor closure for the axis-1+3
cross-cut hazard goal.md L82-88 names: the TB-235 dep-coherence
judge that the auto-approve safety claim depends on can silently
fail-open at high rate while AP2_AUTO_APPROVE=1 continues
stripping @blocked:review and dispatching ideation proposals).
When the rolling 24h sum
validator_judge_fail_count_24h + validator_judge_timeout_count_24h
crosses AP2_VALIDATOR_JUDGE_NOISY_THRESHOLD (default 5; TB-243),
the daemon refuses to auto-promote auto_approved Backlog tasks
and emits auto_approve_skipped reason=validator_judge_noisy fail_count_24h=<N> timeout_count_24h=<M> threshold=<T> per
preempted promotion attempt. The pause-reason discriminator
surfaces as validator_judge_noisy on the existing TB-227 ap2 status text/JSON + web home Automation card + TB-228 cron
status-report digest renderers (no new operator-facing surfaces).
Resume: the rolling-24h window self-clears as old events age out,
OR the operator runs ap2 ack auto_approve_unfreeze (same verb
consecutive_freezes uses — no new ack token), OR they set this
knob to a truthy value (1 / true / yes, matching the
sibling auto-approve knobs' parse). Set the knob when you
explicitly trust the upstream judge degradation surface and want
the pre-TB-272 cosmetic-only TB-243 behavior — the [noisy]
badge stays on ap2 status / web home but the dispatch path
isn't gated on it. Hot-reloadable (TB-271) so the operator can
flip it without a daemon restart.Ideation.
AP2_IDEATION_DISABLED — set to 1/true to opt out of empty-board
ideation entirely.AP2_IDEATION_COOLDOWN_S (7200) — minimum gap between ideation runs.AP2_IDEATION_TRIGGER_TASK_COUNT (3) — fire ideation when Ready+Backlog
count is BELOW this threshold (Active is still a hard gate). Set to
1 for the legacy "fire only when the working queue is fully empty"
behavior; raise it (e.g. 5) for projects with very fluid scope.
Invalid (non-int, non-positive) values fall back to the default.AP2_IDEATION_SCRUB_MODEL (default claude-haiku-4-5-20251001) —
TB-284: model for the post-write scrub that strips exhaustion-
asserting sentences ("this focus is essentially done", "once Y ships
nothing remains") from ideation_state.md after each ideation cycle.
The scrub keeps verdict language from priming the next cycle to
repeat the verdict. Haiku-4.5 is the cost-target floor since the
task is sentence-level classification, not deep reasoning; operators
can swap models for cost / quality trade-offs without a daemon
restart (knob is hot-reloadable). On any SDK error the scrub
fail-opens and leaves the file unchanged — structure (axis
breadcrumbs, proposed-task lists) is more valuable to keep than
verdict sentences are to remove on any single cycle. See
ap2/ideation_scrub.py for the prompt contract.Operator-in-the-loop relaxations (TB-223). Three layered safety
knobs that let an operator who trusts the upstream gates dispatch
ideation-proposed tasks without running ap2 approve on each one.
Defaults are unset / conservative — current behavior is preserved for
operators who haven't opted in. Cross-references goal.md's
Current focus: end-to-end automation axis on the manual-approval
bottleneck: a representative ap2 session approves 10-20 tasks per
cycle, which contradicts the Mission's "walk away for a week without
intervention" promise. The trio is layered so an operator can dial
trust precisely: AP2_AUTO_APPROVE_DISABLED is the master kill switch,
AP2_AUTO_APPROVE_GATE_TAGS is the per-shape opt-out (operator names
tag categories that retain manual review even in auto-approve mode),
and AP2_AUTO_APPROVE_FREEZE_THRESHOLD is the systemic-regression
circuit-breaker (auto-promote halts when consecutive task failures
land in Frozen).
AP2_AUTO_APPROVE_DISABLED — master kill switch. Unset by default
→ auto-approve is ON (TB-430 flipped auto-approve to
autonomous-by-default). When unset, ideation-authored add_backlog
rows omit the @blocked:review codespan so the daemon's next-tick
auto-promote dispatches the task immediately. Set to a truthy value
(1 / true / yes, matching the *_DISABLED kill-switch
convention of janitor / cron / ideation / auto_unfreeze) to OPT OUT
and restore operator-in-the-loop (@blocked:review) semantics — the
legacy approve-every-task behavior for operators who haven't verified
the upstream gates (briefing structural validation, goal-alignment
validation, per-task verification, retry budget, rollback). The
sectioned form is AP2_COMPONENTS_AUTO_APPROVE_DISABLED. The operator
decision-log entry in ap2 logs still surfaces what auto-approval
shipped (the auto_approved event — see the ap2-observability
skill's ## Event schema), so the audit trail is preserved for
offline review.AP2_AUTO_APPROVE — deprecated (pre-TB-430 opt-in master switch).
Still honored as a transitional override for existing deployments:
a truthy value forces auto-approve ON, a falsy value (0 / false /
no / off) forces it OFF — both emit a one-time DeprecationWarning
pointing at AP2_AUTO_APPROVE_DISABLED. Migrate by deleting
AP2_AUTO_APPROVE (keeps the new default-ON posture) or, to stay
opted out, replacing AP2_AUTO_APPROVE=0 with
AP2_AUTO_APPROVE_DISABLED=1.AP2_AUTO_APPROVE_DRY_RUN — TB-232 monitor-only on-ramp. Unset
by default. When set to a truthy value alongside
AP2_AUTO_APPROVE=1, the auto-approve gate chain (tags +
freeze-threshold + token caps) still runs but the WRITE step is a
no-op on the board row: instead of stripping @blocked:review and
emitting auto_approved, the daemon emits a would_auto_approve
audit event (same task + knob payload, plus dry_run=true) and
leaves the codespan intact for operator-manual ap2 approve. Use
this to observe the loop's decisions without committing to the
binary cliff. Enablement on-ramp: set both
AP2_AUTO_APPROVE=1 AND AP2_AUTO_APPROVE_DRY_RUN=1, leave the
daemon running for ≥24h, read ap2 status --json and grep
events.jsonl for would_auto_approve events to confirm the
gate's decisions match your judgment, then unset
AP2_AUTO_APPROVE_DRY_RUN (keep AP2_AUTO_APPROVE=1) to engage
real dispatch. The would_auto_approve_count_24h field on
collect_auto_approve_state (surfaced via ap2 status + web home)
rises as decisions accumulate so you can confirm at a glance the
gate is exercising decisions before flipping the switch. TB-238
also surfaces the same count as a trailing *Dry-run window:*
sub-block on the scheduled status-report Mattermost post's
## Automation loop activity section, so a walk-away operator
sees the readiness signal in their primary return surface
without alt-tabbing to ap2 status --json.AP2_AUTO_APPROVE_GATE_TAGS (default #breaking-change,#high-risk)
— comma-separated list of tag strings. When auto-approve is on, a
proposed task carrying ANY of these tags retains its
@blocked:review codespan so it still requires ap2 approve. This
is the operator's escape hatch for categories of work they don't
trust to auto-ship; the defaults align with the tags ideation itself
uses to self-mark elevated-risk proposals. Operators may type the
tag with or without the leading # (both parse identically); empty
string falls back to the default set.AP2_AUTO_APPROVE_FREEZE_THRESHOLD (default 3) — integer count.
When N consecutive task_complete events have status in
{verification_failed, blocked, error, failed} AND end in
retry_exhausted (the failure chain actually froze a task rather
than looping a single TB through retries), the daemon halts
auto-promotion of auto_approved tasks. Operator-approved tasks
(those promoted via ap2 approve → ideation_approved event)
continue to dispatch normally — the freeze is targeted at the auto
layer, not blanket. Operator unfreezes via ap2 ack auto_approve_unfreeze --reason "<one-line rationale>" (uses the
existing TB-106 ack pattern — the daemon scans operator_ack
events' note field for the auto_approve_unfreeze token and
resets the failure counter). Setting the threshold to 0 (or any
non-positive int) disables the circuit-breaker entirely — the
explicit escape hatch for operators who trust the upstream gates
beyond this layer.Cost + blast-radius guards (TB-224). Two layered token caps and a
single-event task_error halt that ride on top of TB-223's auto-approve
gate. Without these, AP2_AUTO_APPROVE=1 trades manual review for
unbounded token spend — a "successful-but-wasteful" loop can satisfy
verification while burning tokens indefinitely, and a task_error
cascade (SDK timeout, agent OOM, kernel SIGKILL) needs operator
attention not a silent retry. Defaults are unset on both knobs —
operators who haven't done the cost-budgeting math for their project
don't get a hardcoded cap surprising them. The recommended pattern:
set both caps BEFORE flipping AP2_AUTO_APPROVE=1. Cross-references
goal.md's Current focus: end-to-end automation axis 3 ("Cost and
blast-radius guards").
AP2_AUTO_APPROVE_PER_TASK_TOKEN_CAP — integer cap on combined
input_tokens + output_tokens per task. Unset by default → no
cap. When set to a positive integer, the daemon checks each
task_run_usage event (TB-165, emitted at every terminal path) for
auto-approved tasks; an event whose combined tokens exceed the cap
trips a per_task_cap halt — the daemon emits
auto_approve_halted reason=per_task_cap used=<N> cap=<M> and
pauses auto-promote of auto_approved tasks until operator emits
ap2 ack auto_approve_window_resume. Catches the single-runaway
pattern (one task in an infinite tool-call loop). Manual
ap2 approve continues to dispatch even while halted — the pause
is targeted at the auto-approved bucket only.AP2_AUTO_APPROVE_WINDOW_TOKEN_CAP — integer cap on cumulative
input_tokens + output_tokens across all auto-approved tasks in a
rolling 24-hour window. Unset by default → no cap. Computed
by summing task_run_usage token fields over tasks identified as
auto-approved (via TB-223's auto_approved audit event) within
now - 24h. No new state file; tail-scan of events.jsonl, same
shape the cron status-report uses. When the sum exceeds the cap,
the daemon emits auto_approve_halted reason=window_cap window_used=<N> cap=<M> and pauses auto-promote. The rolling-24h
shape matches the operator's natural rhythm without calendar-day
timezone ambiguity. Catches the drift pattern: 50 small tasks each
within the per-task cap but cumulatively unbounded.task_error single-event halt — distinct from
verification_failed (which TB-223's FREEZE_THRESHOLD requires
N=3 of). A task_error event indicates an infrastructure failure
(SDK timeout, agent OOM, briefing read failure) per events.jsonl
conventions; one occurrence is enough to halt auto-promote
because infrastructure failures aren't statistical noise — they
need operator attention immediately. When a task_error lands for
an auto_approved task, the daemon emits
auto_approve_halted reason=task_error task=TB-N error_excerpt=<...> AND appends a ## Decisions needed from operator bullet to .cc-autopilot/ideation_state.md naming the
failing TB-N + error excerpt (so ap2 status and the web home
page surface it without waiting for the next ideation cron).ap2 ack auto_approve_window_resume --reason "<rationale>" clears any of the three halt reasons above (one ack
covers all three since they share the same auto-promote-paused
state). Different verb from TB-223's auto_approve_unfreeze
because the two halts have semantically-distinct entry paths
(cumulative-regression vs. cost/blast-radius) and the audit trail
benefits from one log line per class of issue. Reuses the existing
TB-106 ack pattern (the daemon scans operator_ack events' note
field for the auto_approve_window_resume token and resets the
halt state).Audit events: auto_approve_halted fires once per triggering
episode (deduped via tail scan); auto_approve_skipped fires once
per preempted auto-promote tick (with the would-have-promoted TB-N)
so the cumulative skipped-count is visible in ap2 logs for
operators tuning the cap values.
Pre-flight surface for cap misconfiguration (TB-234). ap2 doctor
has an auto-approve safety floor audit section that fires WARN when
AP2_AUTO_APPROVE is set to a truthy value (1 / true / yes) but
AP2_AUTO_APPROVE_PER_TASK_TOKEN_CAP and/or
AP2_AUTO_APPROVE_WINDOW_TOKEN_CAP is unset, empty, zero, or
non-integer. With both caps disabled, an additional summary WARN names
the configuration as "safety floor OFF" and cross-links goal.md
L102-113. WARN, not FAIL — the operator may have a reason to run
uncapped for a short window — but loud enough that an ap2 doctor
run after flipping AP2_AUTO_APPROVE=1 reveals the gap before the
SDK bill arrives. When auto-approve is unset (the default), the section
emits a single INFO line stating manual approval is required per task.
The audit is purely diagnostic: no events written, no daemon state
mutated. Pair with ap2 status's continuous automation_status
surface (TB-227) — doctor is the one-shot pre-flight, status is the
ongoing snapshot.
Auto-unfreeze on agent-diagnosed briefing-shape fixes (TB-225).
Self-heals the recurring class of retry-exhausted Frozen tasks whose
root cause is a briefing-shape regression the agent already diagnosed
in its task_complete status=blocked summary. Two known prod examples
the brief calls out: TB-204 (grep -lE → grep -rlE on a directory
target — missing the -r flag returns nothing), TB-207 (literal-
backtick in shell bullets truncates the shell command at the first
backtick). Both shapes are catalogued in
ap2/ideation.default.md's ## Shell-bullet pitfalls to AVOID
section. With this gate on, the daemon parses the agent's structured
BriefingFix: prefix, verifies the briefing-line literal match,
patches the briefing via the operator-queue update op, and unfreezes
the task — all without operator-manual ap2 unfreeze. Defaults are
unset / conservative — feature is opt-in only. Cross-references
goal.md's Current focus: end-to-end automation axis 2
("Failure-recovery operator dependency").
The canonical agent-prefix contract (task agents emit this line as
part of their report_result(status="blocked", summary=...) payload
when they diagnose a briefing-shape regression as the root cause):
BriefingFix: <shape> at <briefing_path>:<line>: <from> -> <to>
Worked example:
BriefingFix: grep_missing_r_on_dir at .cc-autopilot/tasks/foo.md:23: grep -lE 'pattern' ap2/tests/ -> grep -rlE 'pattern' ap2/tests/
The parser (ap2._shared.parse_blocked_summary_fix_shape) is
strictly structured — no regex-on-prose guessing — so an agent that
authors free-text diagnoses (no BriefingFix: line) falls through
to today's manual-unfreeze path identically.
See also skills/ap2-task/SKILL.md § "Reporting failures
(task_complete blocked summaries)" — the upstream emitter contract
the per-task agent reads at run time, with one fenced worked example
per bootstrap fix-shape (TB-229).
AP2_CRON_DISABLED — TB-381 component-level kill switch for the
cron scheduler (the ap2/components/cron/ component that owns the
due-check loop + per-job handler dispatch + cron_* lifecycle
events). Unset by default → cron fires on schedule. When set to
a truthy value (1 / true / yes / on, case-insensitive) the
scheduler's tick hook self-gates at the top of Phase.CRON_DISPATCH
and no cron job runs. Mirrors AP2_JANITOR_DISABLED /
AP2_AUTO_UNFREEZE_DISABLED polarity / naming (suppress-polarity /
default_enabled=True), so ap2 status renders the on/off state
correctly. The interval engine (cron.yaml / cron_state.json,
job schedules) and the cron_propose / cron_edit write-path are
unchanged — this knob only stops the daemon-side scheduler from
dispatching.AP2_AUTO_UNFREEZE_DISABLED — TB-320 component-level kill switch
for the auto-unfreeze sweep. Unset by default → sweep runs.
When set to a truthy value (1 / true / yes / on,
case-insensitive), _maybe_auto_unfreeze short-circuits at the
top of the tick hook before any other guard runs and emits an
auto_unfreeze_disabled event once per process (sticky dedup;
resets only on daemon restart). Mirrors AP2_JANITOR_DISABLED /
AP2_VALIDATOR_JUDGE_DISABLED polarity / naming. The registry's
Manifest.is_enabled filter for the auto_unfreeze component
uses the same knob (suppress-polarity / default_enabled=True),
so ap2 status renders the on/off state correctly. Coarser-
grained than AP2_AUTO_UNFREEZE_FIX_SHAPES (which selects which
shapes are auto-patched); this knob disables the entire sweep
regardless of allowlist contents.AP2_AUTO_UNFREEZE_FIX_SHAPES — comma-separated allowlist of
fix-shape tokens. Unset by default → feature disabled. The
daemon refuses to auto-apply any shape that isn't in this
allowlist; unknown shapes still require manual ap2 unfreeze.
The env-knob string IS the trust contract: operators audit each
shape and opt in by listing tokens. Recommended bootstrap list
(each names a known pitfall in
ap2/ideation.default.md's ## Shell-bullet pitfalls to AVOID
section):
grep_missing_r_on_dir — grep -lE 'pattern' <dir>/ returns
nothing without -r. Fix: grep -rlE 'pattern' <dir>/.bare_python_to_uv_run — python -c '...' exits 127 in the
daemon environment. Fix: uv run python -c '...'.literal_backtick_in_shell_bullet — a bullet with literal
backticks like `grep ... | wc -l` truncates at the first
backtick. Fix: drop the wrapping backticks; the bullet body IS
the command.bare_path_to_test_f — a bullet whose body is a bare path
(e.g. reports/foo.md) tries to execute the file (exit 126).
Fix: test -f reports/foo.md.AP2_AUTO_UNFREEZE_MAX_PER_TASK (default 1) — integer cap on
auto-unfreeze attempts per task before fallback to manual
ap2 unfreeze. Bounds oscillation when the patched briefing
ALSO fails. 0 disables the per-task cap (unbounded retries —
intentionally not the default; disabling should be an explicit
operator decision).AP2_AUTO_UNFREEZE_MAX_PER_DAY (default 3) — rolling 24h cap
on total auto-unfreeze applications across all tasks. When
exceeded, the daemon halts further auto-unfreeze attempts on the
tick AND appends a ## Decisions needed from operator bullet to
.cc-autopilot/ideation_state.md so ap2 status surfaces the
systemic-regression signal. 0 disables the per-day cap.AP2_AUTO_UNFREEZE_DRY_RUN — TB-233 monitor-only on-ramp.
Unset by default. When set to a truthy value (1 / true /
yes, case-insensitive) alongside a non-empty
AP2_AUTO_UNFREEZE_FIX_SHAPES, the auto-unfreeze guard chain
(allowlist + per-task cap + per-day cap + briefing-line match)
still runs but the WRITE step is a no-op: instead of calling
_apply_auto_unfreeze_patch (which queues update + unfreeze
ops on the operator queue and mutates the briefing file), the
daemon emits a would_auto_unfreeze audit event with the same
payload shape as auto_unfreeze_applied plus the
file + line fields from the parsed BriefingFix: prefix.
The per-day-count + per-task-prior counters do NOT increment in
dry-run (no real application). Use this to observe the loop's
decisions on the live Frozen set without committing to the binary
cliff. Enablement on-ramp: set both
AP2_AUTO_UNFREEZE_FIX_SHAPES=<shapes> AND
AP2_AUTO_UNFREEZE_DRY_RUN=1, leave the daemon running for a
window (e.g. ≥24h), read ap2 logs --type would_auto_unfreeze to
confirm the gate's decisions match your judgment, then unset
AP2_AUTO_UNFREEZE_DRY_RUN to engage real patching. Sibling
on-ramp to AP2_AUTO_APPROVE_DRY_RUN (TB-232) on the axis-1
auto-approve side. Pre-flight diagnostic (TB-239): ap2 doctor
emits a WARN in the auto-unfreeze safety floor section when
AP2_AUTO_UNFREEZE_DRY_RUN=1 is set without
AP2_AUTO_UNFREEZE_FIX_SHAPES — _maybe_auto_unfreeze early-
returns on empty allowlist BEFORE the dry-run check, so the
observation knob is a silent no-op without the allowlist. Run
ap2 doctor after flipping the dry-run knob to confirm both env
vars are wired. Operator's primary readiness surface (TB-238):
the scheduled status-report Mattermost post's
## Automation loop activity section grows a trailing
*Dry-run window:* sub-block while either dry-run knob is on,
listing the 24h rolling count of would_auto_unfreeze
(and/or would_auto_approve) events. Watch the count rise post-by-
post for confidence the gate is exercising decisions before
flipping the knob off; the sub-block is omitted entirely when
both dry-runs are off so default-off projects stay byte-identical
to TB-228 output.Audit events: auto_unfreeze_applied (success — payload task,
shape, from, to); auto_unfreeze_skipped (any guarded skip —
payload task + reason token; one of
shape_not_in_allowlist, briefing_mismatch,
briefing_path_missing, per_task_cap, per_day_cap,
queue_error, sweep_error). The knob_unset baseline does NOT
emit per-tick — the feature is opt-in and operators who haven't
set AP2_AUTO_UNFREEZE_FIX_SHAPES shouldn't see noise.
Why operator-curated allowlist (not heuristic detection): arbitrary briefing edits by the daemon are blast-radius-unsafe. The allowlist lets the operator audit each fix-shape and opt in specifically; shapes can be removed instantly if one misfires by editing the env string. New shapes never auto-promote — the operator opens new shapes by editing the env value, the daemon never invents them.
Why the briefing-line literal match check: the agent's diagnosis may
be stale if the briefing was operator-edited between failure and
freeze handling (e.g. the operator hand-edited it trying to fix it
themselves). Verifying the from pattern is literally present on
the named line before patching closes the data-race window. A
mismatch emits auto_unfreeze_skipped reason=briefing_mismatch and
leaves the task Frozen — fail-safe.
Ideation-exhaustion halt (TB-226 axis 4; collapsed TB-342; merged
to core TB-345). Two env knobs gate the ideation-exhaustion halt
(now core ideation lifecycle in ap2/ideation_halt.py). See
### Focus state (axis 4) below for the architecture + the resume
verb (ap2 update-goal) vs. the ap2 ack roadmap_complete dismiss
verb (TB-340: ack dismisses the nag, never resumes ideation; TB-342:
editing goal.md is the sole resume signal post-collapse).
AP2_IDEATION_HALT_EMPTY_CYCLES (default 3, min 1, max 20) —
ideation-exhaustion halt threshold: number of consecutive empty
(0-proposal) ideation cycles since the last goal_updated before
the daemon emits roadmap_complete and parks the ideation trigger.
TB-283 collapsed the pre-existing two-path advance mechanism
(LLM-judge against Done when: bullets + empty-cycles heuristic) to
the single empty-cycles signal; TB-345 merged the detector into the
core ap2/ideation_halt.py module. Invalid (non-int / empty) values
fall back to the default; values outside the clamp range are pinned
to the nearest bound, i.e. clamped to [1,20] (so a typo 0
doesn't disable the halt and 999 doesn't wedge it permanently).
Replaces the deprecated alias AP2_FOCUS_ADVANCE_EMPTY_CYCLES
(deprecated alias — kept as a back-compat alias for one release,
mapping to the same core.ideation_halt_empty_cycles path).AP2_IDEATION_HALT_DISABLED — kill switch for the
ideation-exhaustion auto-halt. Set to 1 / true / yes / on
(same convention as AP2_IDEATION_DISABLED) to prevent the daemon
from auto-emitting roadmap_complete even when the threshold trips;
the daemon surfaces a ## Decisions needed from operator
(decisions-needed) bullet instead so the operator can halt manually
(by editing goal.md). Default unset → false → auto-halt enabled.
Replaces the deprecated alias AP2_FOCUS_AUTO_ADVANCE_DISABLED
(deprecated alias — kept as a back-compat alias for one release,
mapping to the same core.ideation_halt_disabled path).Watchdog (auto-diagnose).
AP2_AUTO_DIAGNOSE_IDLE_THRESHOLD_S (10800 = 3h) — idle duration
before the watchdog posts a DiagnoseReport.AP2_AUTO_DIAGNOSE_COOLDOWN_S (21600 = 6h) — minimum gap between
watchdog posts (re-fire spam guard).Attention surface (TB-282 / TB-287 / TB-288 / TB-289 / TB-290 / TB-297).
The five attention detectors (task_stuck, task_frozen,
validator_judge_noisy, auto_approve_paused, cost_cap_approach)
each read fresh from os.environ at detection time — see
AP2_TASK_STUCK_THRESHOLD_S / AP2_ATTENTION_DEBOUNCE_S /
AP2_TASK_FROZEN_RECENCY_S / AP2_AUTO_APPROVE_COST_APPROACH_PCT
described in the ap2-observability skill's "Proactive attention
surface" section. The
knob below controls the push-side cadence (immediate vs the
status-report cron's tick rate):
AP2_ATTENTION_IMMEDIATE_PUSH — TB-297 opt-in immediate-Mattermost-
push on attention_raised emission. Unset by default → push
OFF so the status-report cron remains the routine push
surface (TB-282's ## Attention needed section already carries
the same conditions there). Set to a truthy value
(1 / true / yes / on, case-insensitive) to enable. With
the knob ON, the daemon's _maybe_push_attention helper posts a
one-line [<project_name>] ⚠ <summary> message to
AP2_MM_CHANNELS[0] AFTER each fresh attention_raised event
appends — per-(type, key) push debounce reuses the
AP2_ATTENTION_DEBOUNCE_S window structurally (the push runs
only when a fresh event emits, which already honors the
detector-debounce). Missing-destination handling mirrors the
watchdog: one sticky attention_push_no_destination audit event
per state-file lifetime when AP2_MM_CHANNELS is unset (flag
lives in .cc-autopilot/attention_push_state.json, gitignored;
resets to false on the next successful push). Audit events:
attention_pushed on success; attention_push_error on
_mm_post failure; attention_push_no_destination on the
missing-channel sticky-warn path. The push knob is operator
opt-in once they've sampled their own detector cadence — set
this when the post-trip auto_approve_paused /
cost_cap_approach / time-sensitive conditions in your project
warrant inside-one-tick visibility rather than up-to-the-next-cron-tick-wait
visibility. Hot-reloadable (TB-271) so an operator flipping the
knob takes effect on the next tick without a daemon restart.Janitor (chore-judge, TB-178).
AP2_JANITOR_MAX_FINDINGS_LLM (10) — cap on per-cycle findings sent
to the SDK judge. 0 disables the judge call entirely (the janitor
emits rule-based findings only).AP2_JANITOR_DISABLED (TB-309) — kill switch for the entire janitor
component (declared in ap2/components/janitor/manifest.py). Set
truthy (1, true, yes) to disable; default unset = enabled.
Distinct from AP2_JANITOR_MAX_FINDINGS_LLM=0 (which keeps the
deterministic detector running but disables the LLM judge); this
flag skips the janitor entirely. Reserved for the axis-(2) daemon
tick-hook walk landing in a later TB — for TB-309 the schema field
is declared but the daemon does not yet consult it before
dispatching the janitor cron job.Channel adapters (axis 3).
AP2_CHANNEL_FILE_PATH (TB-312) — target path for the
FileAppendChannelAdapter (one of three core-shipped sibling
adapters in ap2/channel.py). Defaults to
<cwd>/.cc-autopilot/channel.log when unset. Operators wiring a
non-Mattermost delivery (or piping ap2's outbound digests into a
local log file for grep / tail) point this at the destination
they want appended. Hot-reloadable: read fresh from os.environ
on every .post(...) call so a hot-swapped env value (TB-271)
takes effect on the next adapter dispatch.AP2_WEBHOOK_URL (TB-312) — destination for the
WebhookChannelAdapter (POSTs {"text": <text>, **meta} as JSON
to the URL). Unset → adapter returns None without raising, the
caller's audit event notes the no-destination state. Compatible
with Slack incoming webhooks, Discord webhooks, internal HTTP
collectors. Read fresh per .post() call (same hot-reload
semantics as AP2_CHANNEL_FILE_PATH).Mattermost.
AP2_MM_CHANNELS — comma-separated MM channel IDs to poll for
@claude-bot mentions. TB-312 polarity note: AP2_MM_CHANNELS
is also the env_flag on the mattermost component's manifest
with default_enabled=False. Unset / empty → component is
disabled, registry.channel_adapters(cfg) returns no Mattermost
adapter, the watchdog / attention-push paths emit the
*_no_destination audit event family they already used pre-TB-312
when _first_mm_channel() returned "". Any non-empty value
enables both delivery (the MattermostChannelAdapter is
registered) AND polling (the daemon's _mm_loop walks the
registry's inbound_poll hook and reaches
check_new_messages). The env-knob name is verbatim-preserved
per goal.md L64-67 — DO NOT rename this key without an operator-
visible migration.AP2_MM_REPORT_CHANNEL (TB-190) — explicit channel ID for
status-report posts. Unset → falls back to AP2_MM_CHANNELS[0].AP2_PROJECT_NAME (TB-280) — operator-facing project identity that
leads the status-report Mattermost headline (**[<project_name>] Autopilot Status Report** — <now>). Defaults to project_root.name
so a project at /home/user/code/stoch posts under [stoch]
without configuration; override when the directory name is generic
(main, proj) or carries a layout suffix the operator doesn't
want surfaced. Hot-reloadable — a rename takes effect on the next
tick without ap2 stop && ap2 start.AP2_MM_MENTION (@claude-bot) — pattern that triggers handler
dispatch.AP2_MM_BOT_USER_ID — bot's user ID (used for self-message
filtering so the handler doesn't loop on its own replies).AP2_MM_TEAM_ID — Mattermost team ID (sandbox install-channel
helper uses this).Local web UI (ap2 web, daemon-spawned read-only HTTP). Deployment-
identity knobs — set per daemon in .cc-autopilot/env, not config.toml.
AP2_WEB_HOST — bind host for the daemon-spawned web UI. Deployment-
identity (on config.ENV_PERMITTED_KEYS); an operator binding to a
specific interface sets it per deployment.AP2_WEB_PORT (7820) — bind port. Malformed values fall back to
the default rather than crashing daemon startup.AP2_WEB_DISABLED — set to 1/true/yes/on to skip starting
the daemon-spawned web UI.Sandbox / deployment identity.
AP2_SANDBOX_USER — sandbox user identity for the deployment. Deployment-
identity (on config.ENV_PERMITTED_KEYS); env-only, never a config.toml
tunable.Agent backend selection ([agent_backends] / AP2_AGENT_BACKEND_<KIND>,
TB-358). Every agent kind runs on a pluggable backend — claude (the
default; claude_agent_sdk against the bundled Claude Code binary) or codex
(OpenAI's openai_codex SDK). select_adapter(kind, cfg) resolves a kind's
backend via Config.get_agent_backend(kind), precedence high → low:
AP2_AGENT_BACKEND_<KIND> env override — <KIND> upper-cased onto the
suffix (e.g. AP2_AGENT_BACKEND_TASK=codex,
AP2_AGENT_BACKEND_STATUS_REPORT=codex). Call-time-evaluated, so a
mid-process export propagates on the next dispatch; a blank value is treated
as unset.[agent_backends] TOML table in .cc-autopilot/config.toml
(task = "codex", …).DEFAULT_AGENT_BACKEND = "claude" — an unmapped kind, and an all-default
install, resolves to claude.Selectable kinds (ap2.adapters.select.AGENT_KINDS): task, ideation,
status_report, cron, mattermost, plus the verifier_judge,
ideation_scrub, validator_judge, janitor_judge adapter-routed
agent-kind calls — each
independently routable. An unknown / typo'd backend id degrades to claude
rather than crashing dispatch. Whichever backends the resolved map references
must have their credentials present at daemon start (next).
Model pin caveat (AP2_AGENT_MODEL / [core] agent_model, TB-396).
agent_model is a SINGLE global model applied to whichever backend a kind
resolves to — there is no per-backend model knob (yet; deferred). Its default is
provider-neutral (unset → resolves to None), so each backend self-defaults
(Claude's CLI default, codex's native default) and a codex-routed kind isn't
handed a Claude model out of the box. If you PIN it, the pinned value must be
valid for EVERY backend in your [agent_backends] map: a claude-* id pinned
via AP2_AGENT_MODEL will fail a codex-routed kind (the live codex turn rejects
the unknown model). So either leave it unset, or — if you mix backends — set a
model each backend accepts (or repoint the affected kind back to claude).
Daemon-start auth gate (_require_oauth_token, TB-79 → TB-358 →
TB-370). Before forking, the daemon walks the resolved per-kind
backend map and requires exactly the credentials that set implies:
CLAUDE_CODE_OAUTH_TOKEN
(present-only check; the SDK control protocol silently times out at
initialize without it). An all-claude install — the default —
needs only this, exactly as pre-axis-5.OPENAI_API_KEY — metered OpenAI API billing; orcodex login
(browser) / codex login --device-auth (headless), stored at
$CODEX_HOME/auth.json (default ~/.codex/auth.json) with
"auth_mode": "chatgpt" plus auto-refreshing access+refresh
tokens. This is the subscription path — no per-call billing — and
matches ap2's own Claude posture (OAuth subscription, not an API
key; goal.md Constraints).The codex check is a presence-only pre-flight, the exact analog of
the Claude side: it reads auth.json only to confirm the file exists
and is auth_mode: chatgpt. It does NOT shell out to codex, hit the
network, validate, or refresh the token (token contents are never
read or logged) — openai_codex rotates the refresh token (~every 8
days) at runtime. A codex kind with neither OPENAI_API_KEY nor a
chatgpt auth.json fails the gate with a message naming both options
(set OPENAI_API_KEY, or run codex login).
Installing the codex backend (the codex extra). Credentials alone
are not enough — a codex-backed kind needs the openai_codex handle
installed too, and that ships as an opt-in extra so the default install
stays Claude-only. The base pip install autopilot2 / uv sync
resolves only claude-agent-sdk (the always-installed backend); to run
a codex-backed kind you must additionally install the extra:
pip install 'autopilot2[codex]'
# or, in a uv-managed checkout:
uv sync --extra codex
The extra pulls the openai-codex distribution (OpenAI's official Codex
SDK, which bundles the Codex CLI binary) that provides the
import openai_codex handle CodexAdapter lazily imports at first
dispatch (matching the daemon-start gate's uv pip install openai-codex
remediation hint). A live codex-backed kind therefore needs both
the codex extra installed and an OpenAI/codex credential (the
auth gate above — OPENAI_API_KEY or a chatgpt auth.json). Without
the extra the codex-handle gate refuses to start; without a credential
the auth gate does.
Closes goal.md L115-138's axis 4 design — the operator's intent /
priority surface for what the daemon should work on. The operator
authors one or more ## Current focus: headings in goal.md
(priority order, top → bottom); the daemon's runtime detector flags
ideation as exhausted when proposals stop landing. The daemon never
mutates goal.md itself (goal.md L187-191 "Goal.md auto-rotation"
Non-goal).
Multi-focus prose, not a state machine (TB-342).
The operator can list several ## Current focus: headings as
priority-ordered prose / intent — the ideation agent reads the whole
goal file every cycle and the goal-anchor validator accepts ANY of
those headings as a proposal anchor. The daemon does NOT sequence
foci with a pointer walk: pre-TB-342 it advanced an in-memory
pointer from focus 1 → focus 2 once empty-cycles tripped, but
ideation never actually scoped itself to the "active" focus (the
ideation prompt was never told which focus was active), so the walk
changed nothing about what got proposed. TB-342 collapsed that
rotation theatre into a single ideation-exhaustion detector — same
end state, less wasted SDK spend (the halt now fires after
threshold empty cycles instead of num_foci × threshold).
Pointer file.
.cc-autopilot/focus_pointer.json carries the runtime state
(empty_cycles, roadmap_complete_ack_idx, roadmap_complete_emitted,
updated_ts, schema). Fenced from task agents
(TASK_AGENT_FENCED_PATHS) and gitignored so rollbacks (TB-111)
don't re-fire stale roadmap_complete events. Schema-versioned via
the schema: 1 field so a future migration can branch cleanly. The
pre-TB-342 multi-focus rotation fields (active_index,
active_title, exhausted_titles) went away with the pointer walk.
Exhaustion heuristic (empty-cycles, sole signal).
Each tick, _maybe_advance_focus(cfg, sdk) runs as step 0.6 of
_tick (after the auto-unfreeze sweep, before cron / pipeline /
dispatch / ideation). One signal drives the halt: the daemon counts
consecutive recent ideation cycles that produced 0 proposals. Each
cycle is delimited by an ideation_empty_board entry marker
(daemon-emitted at cycle start regardless of outcome) and one of
ideation_complete or ideation_cycle_summary (agent-emitted exit
marker — _complete when the cycle proposed at least one task,
_cycle_summary when no proposals). The counter increments at the
exit marker if no ideation_proposal_recorded fired within the
cycle; resets to 0 if any proposal fired. ideation_timeout /
ideation_error exits don't count (infrastructure failure ≠
"ideation reasoned and found nothing"). The counter ALSO resets at
the most recent goal_updated event — the operator-edits-goal.md
signal that fires from the ap2 update-goal drain handler; pre-edit
empty cycles don't count against the post-edit runway. When the count
reaches AP2_IDEATION_HALT_EMPTY_CYCLES (default 3, clamped to
[1, 20]), the daemon emits roadmap_complete and parks the
ideation trigger.
The intuition: ideation reads the full goal.md + the recent task
arc every cycle. If multiple consecutive cycles can find nothing
substantive worth proposing, ideation has itself implicitly judged
the goal exhausted — that's the load-bearing signal. Per-focus
Progress signals: bullets (if present) feed ideation's per-cycle
assessment as advisory context but do NOT gate the halt; ideation's
empty-output behavior is what the daemon reacts to.
Pre-TB-283 the daemon also ran an LLM-judge advance path that
diff-read recent task commits against the operator-authored
per-focus completion bullets (the sub-block now named
Progress signals:) and advanced on a yes verdict. That path
collapsed multi-week foci into ~3-task cycles whenever each commit
shape-satisfied one bullet, without ever actually verifying
substantive progress (the judge had no way to execute the code it
was reading diffs of). TB-283 deleted it; TB-285 renamed the
sub-block to clear the gating connotation that the prior name
carried.
On halt, the daemon emits roadmap_complete exhausted_count=<n> trigger=empty_cycles_heuristic and writes the updated pointer
(roadmap_complete_emitted=True, dismissal marker cleared). The
focus_advanced event the pre-TB-342 rotation pass emitted is no
longer fired; the pointer_past_last trigger value the pre-TB-342
halt emitted is gone — the trigger is empty_cycles_heuristic
across the board now (the empty-cycles heuristic IS the halt).
Kill-switch.
AP2_IDEATION_HALT_DISABLED=1 short-circuits the auto-halt
even when criteria are met. The daemon surfaces a ## Decisions needed from operator bullet so the operator halts manually (by
editing goal.md). The next tick re-emits the bullet if criteria
still trip — acceptable noise floor. Use this for full-manual
governance when the operator wants per-halt review. TB-345 renamed
this knob from AP2_FOCUS_AUTO_ADVANCE_DISABLED (kept as a
deprecated back-compat alias for one release).
Operator workflow.
The lifecycle is fully covered by existing verbs — no dedicated
ap2 advance / ap2 rewind-focus command exists or is needed:
## Current focus:
headings (or rework existing ones) in goal.md and apply via
ap2 update-goal --file PATH. The drain handler emits
goal_updated, calls goal.reset_pointer_on_goal_updated to clear
roadmap_complete_emitted + empty_cycles + the dismissal marker,
and ideation resumes on the next tick. The empty-cycles counter
also resets at the goal_updated cutoff, so the runtime read and
the on-disk pointer agree.roadmap_complete, then run ap2 ack roadmap_complete --reason "...". This DISMISSES the recurring nag via the pointer's
roadmap_complete_ack_idx marker (read by
goal.roadmap_complete_notice_dismissed); ideation STAYS PARKED.
The ack is NOT a resume verb — the pre-TB-340 implementation
wrongly folded it into roadmap_exhausted so it un-parked
ideation, resuming wasteful ~$1-3 SDK cycles against an already-
exhausted goal every cooldown.ap2 ideate --force bypasses
the gate for one cycle. Useful when you just extended goal.md
and don't want to wait for the next natural cooldown..cc-autopilot/focus_pointer.json. The
file is gitignored runtime state; a manual edit (even with the
daemon paused) does not emit a goal_updated event, so the
empty-cycles counter's reset cutoff doesn't move and pre-edit
empty cycles keep counting against the post-edit runway. Use
ap2 update-goal to refresh the goal file instead; the drain
handler is the only legitimate operator path that moves the
pointer's halt state.ap2 pause for full stop (in-flight
tasks finish, no new dispatch). Distinct from roadmap-complete:
the parked-ideation state still dispatches operator-added
Backlog tasks; pause stops everything.AP2_IDEATION_HALT_DISABLED=1 as above. The daemon never
halts on its own; the operator halts manually via the decisions-
needed bullet.Roadmap-complete: ideation parks (TB-275).
When the empty-cycles threshold trips, the daemon emits
roadmap_complete exhausted_count=<n> trigger=empty_cycles_heuristic
(once, suppressed via the pointer's roadmap_complete_emitted
flag). From then on, the IDEATION TRIGGER skips: _maybe_ideate
emits ideation_skipped reason=roadmap_complete and bumps the
cooldown (TB-246), so a walk-away weekend that exhausts the goal
stops piling speculative proposals against an already-exhausted
context (without this gate, a 60-min cooldown × 48h weekend wastes
up to ~48 ideation SDK calls). The skip-gate is a sibling to
TB-174's focus-exhausted gate (same ideation_skipped event shape
with a different reason field; force_ideate bypasses both so
ap2 ideate --force works on the operator's recovery path).
TASK DISPATCH IS NOT AFFECTED (TB-275): already-queued Backlog
tasks — operator-added via ap2 add, operator-approved via
ap2 approve, or previously auto-approved by ideation — continue
to auto-promote and dispatch normally. Once ideation is gated, no
new speculative work can enter the Backlog anyway, so everything
in the queue is operator-originated or already-proposed and should
always drain. A genuine full-stop is ap2 pause, a separate
explicit mechanism. RESUMING ideation is editing goal.md (TB-342
collapsed the pre-existing rewind-focus recovery path): the
ap2 update-goal drain handler emits goal_updated and calls
reset_pointer_on_goal_updated, which clears
roadmap_complete_emitted so goal.roadmap_exhausted returns False
naturally and ideation re-arms on the next tick. ap2 ack roadmap_complete --reason "..." does NOT resume — it sets the
pointer's roadmap_complete_ack_idx dismissal marker, read ONLY by
goal.roadmap_complete_notice_dismissed, which quiets the recurring
operator nag on the ap2 status / web / cron surfaces; ideation
STAYS PARKED. _maybe_advance_focus clears that marker on each
fresh roadmap_complete emit, so a dismissal can't go stale across
an extend→re-exhaust cycle at the same foci count (the 2026-05-29
bug, where a stale ack_idx from a prior episode defeated the cheap-
skip and ideation auto-resumed wasteful SDK cycles). The pre-TB-340
implementation instead folded an events-jsonl ack-scan (the same
shape TB-223's auto_approve_unfreeze / TB-224's
auto_approve_window_resume use) into roadmap_exhausted itself,
so the ack wrongly un-parked ideation.
Status-report push surface (TB-244).
The roadmap_complete event surfaces in the status-report
Mattermost cron post — the operator's primary walk-away channel.
The routine renders a ## Focus rotation activity sub-block
(parallel to TB-228's ## Automation loop activity digest) listing
one bullet per roadmap_complete event in the inter-report window,
with the two-verb hint (ap2 update-goal resumes; ap2 ack roadmap_complete dismisses — TB-340 / TB-342) rendered verbatim on
the halt line so the operator can copy-paste it from the post
(suppressed once the operator dismissed THIS episode). Closes
the push-surface gap TB-242 left open: the pull surfaces
(ap2 status text/JSON + web home) showed the focus list +
halt state on-demand, but a roadmap_complete halt at 03:00Z used
to wait for the operator's next manual ap2 status to surface. Now
the next status-report cron post carries it. Omit-on-empty: the
sub-block is suppressed when no roadmap_complete events landed in
the window. The _STATUS_REPORT_AUTOMATION_INTERESTING_TYPES
frozenset in ap2/status_report.py also lists roadmap_complete so
a lone halt event keeps the routine's skip-gate from firing.
(Historical note: pre-TB-342 the digest also rendered
focus_advanced bullets for the multi-focus rotation pointer walk,
showing (N of M) positions. TB-342 collapsed the rotation theatre;
the digest now carries only the halt line.)
Why never auto-mutate goal.md.
Goal.md L187-191 names goal.md auto-rotation as a Non-goal. The
operator owns the focus list; the daemon halts when ideation runs
empty but never writes the file. Adding / reordering / retiring
foci stays ap2 update-goal-only. This keeps the surface symmetric
with the other operator-only paths (cron mutation via ap2 cron edit, classify-verdict via ap2 classify, ack via ap2 ack).
Outbound delivery — auto-diagnose digests (auto_diagnose_fired),
pending-review reminders (pending_review_reminder), attention
immediate-pushes (attention_pushed) — flows through registered
ChannelAdapters rather than calling Mattermost helpers directly.
Contract. Every adapter subclasses ap2.channel.ChannelAdapter
and implements:
class MyChannelAdapter(ChannelAdapter):
name = "my-channel"
def post(self, text: str, **meta) -> dict | None:
... # deliver text via the channel-specific transport
name is the short identifier the registry uses for ordering. The
**meta shape is intentionally open — today's call sites pass
channel (the resolved Mattermost channel id, when applicable) and
thread_id (for reply-targeting). Adapters that don't consume a
given key MUST ignore it, never raise — forward-compat as new
delivery channels join the list.
Return value: a small dict describing the delivery (typically
{"adapter": name, "post_id": ...}) on success, None for a
best-effort no-op when the adapter is unconfigured (e.g. webhook
adapter with AP2_WEBHOOK_URL unset). Raising signals a hard
failure; the caller's per-adapter try/except emits a *_error
audit event and continues iterating.
Registration. Components register their adapter under
Manifest.hook_points["channel_adapter"] (either a class — the
registry instantiates fresh per call — or a module-level
singleton). The registry walks enabled manifests and returns the
adapter list via default_registry().channel_adapters(cfg) in
deterministic component-name-sorted order so dispatch is
reproducible across daemon restarts.
Core-shipped sibling adapters (in ap2/channel.py, not bound
to any component manifest by default — operators can wire them via
a project-specific component or call _deliver(...) directly for
unit / smoke contexts):
StdoutChannelAdapter — prints [stdout] <text> to stdout.
Useful for ap2 start --foreground smoke runs.FileAppendChannelAdapter — appends <text>\n to the file at
AP2_CHANNEL_FILE_PATH (default
<cwd>/.cc-autopilot/channel.log). Parent dir auto-created.WebhookChannelAdapter — POSTs {"text": text, **meta} as JSON
to AP2_WEBHOOK_URL. Slack incoming webhooks, Discord, generic
HTTP collectors. 10s fixed timeout — a slow webhook must not
hold up the watchdog tick.Mattermost. The Mattermost adapter (MattermostChannelAdapter)
lives under ap2/components/mattermost/__init__.py because the
HTTP client, channel/team/bot env knobs, and the mattermost_reply
MCP tool all move together (goal.md L184-186). The adapter routes
through ap2.tools._mm_post (a backwards-compat shim that defers
to the component's _mm_post) so pre-TB-312 tests monkeypatching
tools._mm_post keep working unchanged. See the AP2_MM_CHANNELS
polarity note in ## Configuration knobs → Mattermost above for the
enable / disable rules.
The structured-config (env → TOML) focus (goal.md L266-403) is
migrating the per-project tunable surface from the flat
AP2_* env-knob set above to typed TOML keys declared on each
component's Manifest.config_schema. The reference below enumerates
every key TB-321/322 landed; ap2 init writes the same set to
<project>/.cc-autopilot/config.toml as commented-out lines (the
ap2.init.CONFIG_TEMPLATE constant, rendered at module-import time
from aggregate_schemas(default_registry()) so the scaffold stays
in lock-step with the schema). The
test_every_config_key_documented gate in
ap2/tests/test_docs_drift.py fails CI if a new ConfigKey is
declared and not listed here OR in
ap2.init._CONFIG_TEMPLATE_EXEMPT_KEYS.
TOML layout (goal.md L307-310):
[core.<field>] # non-component tunables (verifier,
# ideation, watchdog, etc.) — typed by
# `ap2.core_config_schema.CORE_CONFIG_SCHEMA`
# (TB-337). `validate_config` rejects
# unknown `[core.*]` keys at daemon-start
# with a clear "did you mean ...?" hint.
[components.<name>.<key>] # per-component knobs declared on
# `Manifest.config_schema`.
[agent_backends] # per-agent-kind backend map (TB-358):
# `<kind> = "claude" | "codex"`. NOT a
# `ConfigKey` — stashed verbatim by
# `config_loader.from_toml`; see the
# dedicated subsection below.
Precedence (high → low, applied by
ap2.config_compat.apply_env_overrides at daemon-start):
sectioned env (`AP2_<SECTION>_<KEY>`)
> flat env (`AP2_<FLAT>` — ENV_PERMITTED_KEYS allowlist only, TB-413)
> this TOML file (`.cc-autopilot/config.toml`)
> in-source defaults.
ap2/config_compat.FLAT_TO_SECTIONED is the operator-facing name → TOML-key
map: it tells you which config.toml path a flat AP2_* name corresponds
to. TB-413 gates the flat-env OVERRIDE that map used to grant to the
config.ENV_PERMITTED_KEYS allowlist — only a flat name that is a secret /
deployment-identity / runtime-fixed knob (the FLAT_TO_SECTIONED ∩ ENV_PERMITTED_KEYS set: AP2_TICK_S, AP2_MM_TICK_S, AP2_WEB_PORT,
AP2_WEB_DISABLED, AP2_PROJECT_NAME) still wins over the TOML value. A
flat name for a behavioral tunable is IGNORED (config.toml is its sole
source) and fires no env_deprecated event (the emission was retired in
TB-413 — an ignored override has nothing to deprecate). The sectioned env
form (AP2_<SECTION>_<KEY>, e.g. AP2_CORE_TASK_MAX_TURNS) remains the
highest-precedence override for power users; config.toml is the
forward-canonical authoring shape.
The hot-reload watcher (TB-271 extended by TB-323) tracks
.cc-autopilot/config.toml's mtime alongside .cc-autopilot/env,
so a bumped tunable propagates on the next tick (≤30s) for
hot-reloadable keys; non-hot keys still need ap2 stop && ap2 start.
The [core.*] namespace carries the 21 non-component knobs the
daemon's runtime needs: tick intervals, per-call timeouts, retry
budgets, agent runtime (model + effort + max-turns), the ideation
cluster, project identity, and the web server's lifecycle pair.
Schema declared in ap2/core_config_schema.py::CORE_CONFIG_SCHEMA;
validate_config walks both [core.*] and [components.<name>.*]
sub-tables against the union at daemon-start and rejects unknown /
mistyped keys with a clear named-path error (e.g. [core] web_prot = 8080: unknown key (did you mean \core.web_port`?)`).
Hot-reloadability mirrors env_reload.HOT_RELOADABLE_KNOBS /
FIXED_KNOBS: lifecycle knobs (core.web_port, core.web_disabled)
wire a stateful resource at daemon-start and need ap2 stop && ap2 start; everything else propagates on the next tick after a
.cc-autopilot/env or .cc-autopilot/config.toml mtime bump.
core.agent_effort — str, default "" (hot-reloadable). Global
reasoning-effort label (low | medium | high | xhigh |
max) passed as extra_args={"effort": <value>} to the SDK
options. Per-job sub-knobs (AP2_STATUS_REPORT_EFFORT,
AP2_VERIFY_JUDGE_EFFORT, AP2_JANITOR_JUDGE_EFFORT) override for
their respective agents. Mirrors AP2_AGENT_EFFORT.core.agent_model — str, default provider-neutral / unset (resolves to
None, hot-reloadable). Model name passed to the agent backend for task /
control / verifier / janitor agents. The default is unset, so each backend
self-defaults (Claude's CLI default, codex's native default) and a
codex-routed kind isn't handed a Claude id (TB-396). The dispatch sites build
cfg.get_core_value("agent_model") or None, so an empty-string env coerces to
None too. Pin a model via AP2_AGENT_MODEL / this key — it applies to
whichever backend a kind resolves to, so it must be valid for every backend in
your [agent_backends] map (see the Model pin caveat under Agent
backend selection). Read fresh from os.environ at each SDK invocation so
hot-reload propagates immediately.core.auto_diagnose_cooldown_s — int, default 21600 (hot-reloadable).
Idle-watchdog re-fire cooldown in seconds (TB-71). After an
auto_diagnose_fired post, _maybe_auto_diagnose suppresses further
diagnostics for this window so a persistently-idle board doesn't spam
the channel every tick. Default 21600 (6h). Mirrors
AP2_AUTO_DIAGNOSE_COOLDOWN_S.core.auto_diagnose_idle_threshold_s — int, default 10800
(hot-reloadable). Idle-watchdog trigger threshold in seconds (TB-71).
_maybe_auto_diagnose posts a diagnostic to Mattermost once the board
has made no forward progress for this long, surfacing a wedged daemon
the operator would otherwise miss. Default 10800 (3h). Mirrors
AP2_AUTO_DIAGNOSE_IDLE_THRESHOLD_S.core.control_max_turns — int, default 15 (hot-reloadable). Max
turns per control-agent (mattermost / cron) SDK query. Tighter
than core.task_max_turns because control agents do focused
decide-then-route work, not implementation. Mirrors
AP2_CONTROL_MAX_TURNS.core.control_timeout_s — int, default 1200 (hot-reloadable).
Per-control-agent (mattermost / cron / ideation) SDK query timeout
in seconds. Default raised to 20min in TB-278 after xhigh-effort
ideation cycles routinely blew the old 5-min wall. Mirrors
AP2_CONTROL_TIMEOUT_S.core.event_context_size — int, default 50 (hot-reloadable).
Number of most-recent events from .cc-autopilot/events.jsonl the
daemon injects into each agent briefing as the Recent events
context tail. Mirrors AP2_EVENT_CONTEXT.core.ideation_cooldown_s — int, default 7200 (hot-reloadable).
Minimum seconds between ideation cron fires when the board stays
empty. Throttles the cycle so the agent isn't hammered every tick
on a quiet project. Mirrors AP2_IDEATION_COOLDOWN_S.core.ideation_disabled — bool, default false (hot-reloadable).
Kill switch for the empty-board ideation cron. Truthy value opts
the project out of automatic backlog refill. Mirrors
AP2_IDEATION_DISABLED.core.ideation_halt_disabled — bool, default false
(hot-reloadable). Kill switch for the ideation-exhaustion auto-halt;
when truthy the daemon surfaces a decisions-needed bullet instead of
auto-emitting roadmap_complete. Mirrors AP2_IDEATION_HALT_DISABLED
(deprecated alias AP2_FOCUS_AUTO_ADVANCE_DISABLED).core.ideation_halt_empty_cycles — int, default 3
(hot-reloadable). Number of consecutive empty (0-proposal) ideation
cycles since the last goal_updated before the daemon emits
roadmap_complete and parks the ideation trigger; clamped to
[1,20]. Mirrors AP2_IDEATION_HALT_EMPTY_CYCLES (deprecated alias
AP2_FOCUS_ADVANCE_EMPTY_CYCLES).core.ideation_max_turns — int, default 100 (hot-reloadable).
Max turns per ideation-agent SDK query. Default raised 30 → 100
in TB-278 after a goal.md rewrite mid-cycle hit error_max_turns
at 31. Mirrors AP2_IDEATION_MAX_TURNS.core.ideation_scrub_model — str, default
"claude-haiku-4-5-20251001" (hot-reloadable). Model name for
ideation_scrub.py's post-write filter that strips
exhaustion-asserting sentences from ideation_state.md after each
ideation cycle. Mirrors AP2_IDEATION_SCRUB_MODEL.core.ideation_trigger_task_count — int, default 3
(hot-reloadable). Fire ideation when Ready+Backlog count is BELOW
this threshold AND Active is empty. Doubles as the per-cycle
proposal-slot budget. Set to 1 for the legacy "fire only when
working queue is fully empty" behavior. Mirrors
AP2_IDEATION_TRIGGER_TASK_COUNT.core.max_retries — int, default 3 (hot-reloadable). Number of
retry attempts per task before it lands Frozen and routes through
the auto-unfreeze / operator-ack path. Mirrors AP2_MAX_RETRIES.core.mm_tick_interval_s — int, default 10 (hot-reloadable).
Mattermost polling tick interval in seconds. The _mm_loop runs
in its own coroutine at a faster tempo than the main tick so
operator pause / add / delete @bot mentions don't sit behind a
30s core.tick_interval_s. Mirrors AP2_MM_TICK_S.core.project_name — str, default "" (hot-reloadable).
Operator-facing project name. Leads every status-report Mattermost
headline (**[<project_name>] Autopilot Status Report**) so a
multi-project operator can identify a post's source. Empty default
falls back to project_root.name. Mirrors AP2_PROJECT_NAME.core.status_report_effort — str, default "" (hot-reloadable).
Per-site reasoning-effort label override for the status-report
cron's control-agent SDK query. Same value space as
core.agent_effort (low | medium | high | xhigh | max).
Empty default = fall through to core.agent_effort at the call
site; the per-site hardcoded fallback is medium. Mirrors
AP2_STATUS_REPORT_EFFORT.core.task_max_turns — int, default 500 (hot-reloadable). Max
turns per task-agent SDK query. Default raised 50 → 200 in TB-278
after TB-122 hit the old wall at 51 turns, then 200 → 500 in
TB-347 to match the validated operating value; bump further only
for unusually heavy projects. Mirrors AP2_TASK_MAX_TURNS.core.task_timeout_s — int, default 3600 (hot-reloadable).
Per-task SDK query timeout in seconds. Bumped 5min → 20min in
TB-278 after xhigh-effort tasks routinely blew the wall, then to
60min (3600s) in TB-347 to match the validated operating value.
Mirrors AP2_TASK_TIMEOUT_S.core.thinking_block_effort_drop_disabled — bool, default false
(hot-reloadable). Kill switch for the TB-356 graceful-degradation
path: by default a task that fails with the bundled-CLI
thinking-block-immutability 400 (... thinking or redacted_thinking blocks in the latest assistant message cannot be modified) has its
effort stepped down one tier on the automatic retry
(xhigh→high→medium→low, floored), emitting an
effort_downshift event. Truthy restores constant-effort blind
retry. Other failure classes never downshift. Mirrors
AP2_THINKING_BLOCK_EFFORT_DROP_DISABLED.core.tick_interval_s — int, default 30 (hot-reloadable). Main
daemon tick interval in seconds. The _main_tick_loop fires
roughly once per tick_interval_s to walk cron, pipeline sweep,
task dispatch, ideation, and watchdog. Lower values shorten
reaction time at the cost of more loop overhead. Mirrors
AP2_TICK_S.core.verify_cmd — str, default "" (hot-reloadable).
Project-wide regression gate shell command. Runs after every
successful task-agent commit; failure routes the task through
retry like any other crash. Empty default = no project-wide gate.
Mirrors AP2_VERIFY_CMD.core.verify_judge_effort — str, default "" (hot-reloadable).
Per-site reasoning-effort label override for the verify-judge SDK
query (the per-task verifier's optional LLM judge step). Same value