feat(opencode): wake for background bash completions

[randomvariable]

Summary

Implements #103.

This adds background-bash wake continuations for OpenCode sessions. When a background bash task completes after the agent has yielded, AFT can prompt the session with the completion summary so unattended work can continue without waiting for the user to send another message.

This pairs with OpenCode plugin transport support in anomalyco/opencode#31238. That OpenCode change ensures plugin-origin session.prompt calls can fall back to the in-process transport when live HTTP is unauthorized.

Changes

• add idle-independent deferred completion fallback, keyed per task
• use session.prompt for wake delivery, with SDK failure validation before ack
• demote failed live-server wake transport and retry via fallback client
• handle push-before-track buffered completions through terminal acceptance side effects
• clear fallback timers through drain/consume/wait/reset/cleanup paths
• expose background wake timing/retry options in assets/aft.schema.json

Config

New/covered bash options:

{
  "bash": {
    "deferred_completion_fallback_ms": 500,
    "wake_retry_max_attempts": 5,
    "wake_debounce_step_ms": 200,
    "wake_debounce_cap_ms": 1000,
    "long_running_reminder_enabled": true,
    "long_running_reminder_interval_ms": 600000,
    "foreground_wait_window_ms": 8000,
    "subagent_background": false
  }
}

Tests

• bun run --filter @cortexkit/aft-opencode typecheck
• bun test packages/opencode-plugin/src/__tests__/resolve-bash-config.test.ts packages/opencode-plugin/src/__tests__/live-server-client.test.ts packages/opencode-plugin/src/__tests__/bg-notifications.test.ts
• bun test packages/opencode-plugin/src/__tests__/e2e/bg-notifications.test.ts
• bun run --filter @cortexkit/aft-opencode build
• git diff --check

Greptile Summary

This PR implements background bash wake continuations for OpenCode sessions, allowing AFT to prompt a session with completion summaries when background tasks finish while the agent has yielded. The implementation uses session.prompt (with SDK failure validation) as the preferred delivery path, with a tiered fallback to promptAsync, and adds an idle-independent deferred completion fallback keyed per task.

• Adds ReminderClass urgency tiers (urgent_failure, timer, completion, pattern_match) so failed tasks can bypass the normal debounce delay and wake the session immediately.
• Introduces deferredCompletionTimer / deferredCompletionDueByTask per-session state so completions that arrive during the same turn as their spawn fire autonomously after deferred_completion_fallback_ms instead of waiting for the next session.idle event.
• Changes probeServerReachable to reject 401/403 unless env-derived credentials make the probe succeed, and changes getLiveServerClient to bypass the per-session cache when per-request headers (e.g., x-aft-delivery-id) are present.

Confidence Score: 5/5

Safe to merge. The core delivery logic, deferred fallback timers, urgency tiers, and hard-stop recovery are all well-covered by both unit and e2e tests.

The wake delivery chain is thoroughly tested with specific assertions on call counts, timing, and state. All three findings are style or minor behavioural nits rather than defects in the critical path.

packages/opencode-plugin/src/bg-notifications.ts — three minor findings in promoteBufferedUnknownCompletions, the deliveryIDResolved mismatch guard, and appendInTurnBgCompletions retry-state reset.

Important Files Changed

Filename	Overview
packages/opencode-plugin/src/bg-notifications.ts	Major rework: adds ReminderClass urgency tiers, per-task deferred completion fallback timers, session.prompt preferred delivery with SDK failure validation, promoteBufferedUnknownCompletions at idle boundary. Three style/logic findings: unused remaining variable, always-false delivery-ID mismatch check, and stale retryDelayMs not cleared in appendInTurnBgCompletions.
packages/opencode-plugin/src/shared/live-server-client.ts	Adds per-request headers param to getLiveServerClient (bypasses cache when present), adds enabled param to useLiveServerWake, tightens probeServerReachable to reject 401/403 unless env credentials make the probe succeed.
packages/opencode-plugin/src/config.ts	Adds four new bash config fields with schema, Zod validation, defaults, and resolved types.
packages/opencode-plugin/src/index.ts	Resolves bash config once per handler invocation and threads the four new wake-tuning fields into each DrainContext.
packages/opencode-plugin/src/tests/bg-notifications.test.ts	Extensive test expansion covering deferred fallback, urgency tiers, hard-stop recovery, and unknown-completion promotion.
assets/aft.schema.json	Adds four new bash config properties to JSON schema with correct types, minimums, and defaults.

_{Reviews (2): Last reviewed commit: "feat(opencode): wake for background bash..." | Re-trigger Greptile}

[cubic-dev-ai]

2 issues found across 9 files

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>