Summary

Completes the unified-operator-interface vision per feedback-kora-is-unified-operator-interface: "Kora investigates + attempts fix where safe + DMs you with what happened, what was tried, what's left for you to decide." PR #166 shipped investigate+DM; this bucket ships the attempt-fix layer. After this lands, when fly probe fires unhealthy + envelope is enabled, Kora's investigation can include "I tried restart_machine on i-abc; before=stopped, after=started; here's what's left" instead of just "I recommend you rotate the token."

Bucket spec: 17_cc_bucket_prompts/KR-PROBE-AUTOFIX-EXECUTION_kora_attempts_the_fix.md.

Ship-enabled envelope actions

Zero envelopes are ship-enabled. The fly restart_unhealthy_machine envelope is whitelist-defined in kora_cli/probes/fix_envelopes.py (PR #163) but KORA_PROBE_AUTOFIX_FLY_ENABLED defaults OFF per fail-CLOSED. Operator opts in explicitly per probe; the executor re-checks the env on every call, so flipping the env mid-investigation closes the gate.

K-DG findings (post-#179 baseline)

• Fly API client: existing heartbeat_probes/fly.py uses https://api.machines.dev + KORA_FLY_API_TOKEN bearer. New executor reuses the exact same pattern + adds the POST /v1/apps/{app}/machines/{id}/restart call.
• Envelope plumbing: fix_envelopes.py already declares the fly envelope + per-probe enable env + is_envelope_enabled() accessor. wake_consumer.py already passes envelope_enabled + envelope_fix_name to reasoning context (PR feat(kora): KR-PROBE-WAKE-CONSUMER — wake event → reasoning → DM operator #166).
• Tool registry pattern: PR KR-EMAIL-OUTBOUND-COMPOSE-TOOL — Kora can email operator (R3 Q8a outbound) #179 established the synthetic-Caller dispatch path for reasoning-loop mutating tools — this PR adds a 2nd entry to _REASONING_MUTATING_TOOLS.
• cap_matrix: same finding as PR KR-EMAIL-OUTBOUND-COMPOSE-TOOL — Kora can email operator (R3 Q8a outbound) #179. requires_cap_gate: True for external callers (default-deny). No substrate coord needed.

Defense-in-depth: validation pipeline

Each invocation runs through 5 gates before any Fly API call:

1. probe in known universe (supabase / fly / vercel / sentry / doppler)
2. is_envelope_enabled(probe) — re-reads the env (canonical truth)
3. action matches the envelope's executor whitelist (only fly + restart_machine|restart_unhealthy_machine in v1)
4. target_id non-empty + matches ^[A-Za-z0-9_-]{1,64}$
5. Per-probe executor pre-check: target resolves to a real machine + state != "started"

Each rejection emits one audit row with rejection_reason + rejection_detail.

Sample audit entry — successful attempt

{
  "emitted_at": "2026-05-23T23:51:04.221000+00:00",
  "seam": "tool.probe_autofix_attempted",
  "details": {
    "probe": "fly",
    "action": "restart_machine",
    "target_id": "1781e9f6c12d83",
    "reason_from_reasoning": "Machine state has been stopped for 3 consecutive probe cycles (15 min); restart is the documented recovery per envelope.",
    "status": "attempted",
    "action_taken": "restart_machine",
    "action_canonical": "restart_unhealthy_machine",
    "fly_app": "kora-runtime",
    "before_state": {
      "id": "1781e9f6c12d83",
      "name": "kora-prod-east-1",
      "state": "stopped",
      "region": "iad",
      "instance_id": "01HZ..."
    },
    "after_state": {
      "id": "1781e9f6c12d83",
      "name": "kora-prod-east-1",
      "state": "started",
      "region": "iad",
      "instance_id": "01HZ..."
    },
    "executor_duration_ms": 842
  },
  "caller_session_id": "mcp:kora_reasoning_self",
  "source": "reasoning"
}

Sample audit entry — envelope disabled rejection:

{
  "seam": "tool.probe_autofix_attempted",
  "details": {
    "probe": "fly",
    "action": "restart_machine",
    "target_id": "1781e9f6c12d83",
    "reason_from_reasoning": "machine flap detected",
    "status": "rejected",
    "rejection_reason": "envelope_disabled",
    "rejection_detail": {
      "enable_env": "KORA_PROBE_AUTOFIX_FLY_ENABLED",
      "fix_name": "restart_unhealthy_machine"
    }
  },
  "caller_session_id": "mcp:kora_reasoning_self",
  "source": "reasoning"
}

Sample DM showing the attempt outcome

After Kora's reasoning loop completes investigation + tool invocation, the wake_consumer (PR #166) sends the operator DM. With this bucket the model now has the autofix result to weave in:

⚠️ Probe alert · fly

Fly probe reports degraded — kora-runtime-staging machine 1781e9f6c12d83
has been in 'stopped' state for the last 3 probe cycles (15 min).

I tried restart_machine on 1781e9f6c12d83 since the envelope is enabled.
Before: state=stopped. After: state=started. Restart completed in 842ms.

Next probe cycle (in ≤5 min) will confirm whether health holds. If the
machine flaps back to 'stopped', that's a deeper issue — check
fly logs for OOM / app-crash patterns rather than another restart.

If the envelope is disabled, Kora's investigation includes:

⚠️ Probe alert · fly

Fly probe reports degraded — machine 1781e9f6c12d83 in 'stopped' state.

I would have attempted a restart but KORA_PROBE_AUTOFIX_FLY_ENABLED
is off (default). To enable autofix for this envelope, set the env to
'true' in Doppler + redeploy. To restart manually now:
  flyctl machines restart 1781e9f6c12d83 -a kora-runtime

Env vars added

Files

• NEW kora_cli/tools/probe_autofix.py (~510 lines) — validation pipeline + Fly executor + audit emission
• NEW tests/kora_cli/tools/test_probe_autofix.py (24 tests)
• MOD kora_cli/listeners/mcp_tools.py — ATTEMPT_PROBE_AUTOFIX_TOOL descriptor + _dispatch_attempt_probe_autofix + added to ST2_TOOL_DESCRIPTORS + ST2_TOOL_DISPATCH
• MOD kora_cli/reasoning/tool_registry.py — added to REASONING_TOOL_ALLOWLIST + _REASONING_MUTATING_TOOLS; "Deliberate scope expansion KR-1 ST2: Identity swap (DEFAULT_AGENT_IDENTITY + SOUL.md scaffold + repo metadata) #2" docstring
• MOD kora_cli/audit/jsonl_sink.py — tool.probe_autofix_attempted SeamName Literal entry
• MOD kora_docs/00_canonical_current_state/kora_system_prompt.md — tool usage guidance + mutation-boundary "two exceptions"
• MOD tests/kora_cli/reasoning/test_anthropic_engine_tool_use.py — bump 6→7 tool count assertions

Test plan

• 24 autofix tests pass: validation pipeline (unknown probe / envelope disabled / probe-without-envelope / action-not-in-envelope / target_id-invalid×3) + Fly executor (token unset / target not found / target already healthy / happy path / staging app / GET transport raise / POST transport raise / HTTP 500) + audit shape + registry integration (advertised, mutating subset, synthetic Caller dispatch, requires_cap_gate True)
• Regression: 317 passed across tools + audit + reasoning + probes + mcp_tools
• ruff check clean on all changed files

🤖 Generated with Claude Code