RFE: Pi background bash lifecycle events for host-side presence tracking #934

Description

Please expose generic background-bash lifecycle events on the Pi extension's pi.events bus, so other extensions can account for AFT-owned work without parsing rendered reminders or reaching into AFT's transport.

Proposed minimal surface:

pi.events.on("aft:bash-background-started", (event) => {
  // event: { sessionId: string, taskId: string }
});
pi.events.on("aft:bash-background-completed", (event) => {
  // event: { sessionId: string, taskId: string }
});

• sessionId is Pi's native session UUID.
• started means AFT handed a live background task back to the agent: explicit background execution, PTY, or an automatically promoted foreground call.
• completed means AFT observed a terminal task status, including failure, timeout, or termination. A pattern match or an accepted kill signal is not completion.
• Events contain identities only, not commands, output, credentials, or final-output handles.
• Completion is independent of notification delivery and agent continuation. AFT would not acquire Herdr-specific logic, insert grace periods, suppress settlement, or change existing completion wakes.

Use case: premature "agent finished" notifications in Herdr

With AFT's background bash in a Pi session hosted by Herdr:

1. The agent starts a long command with background: true, or a foreground call is promoted to a background task.
2. The bash tool returns a task ID; the agent ends its current run while waiting for the automatic completion reminder.
3. Pi settles the current agent activity. Herdr reports the agent as idle/done and announces that it has finished, although the command is still running and the agent will resume when it ends.
4. AFT later receives the actual completion and wakes the agent normally.

An independent personal Pi extension could track a set of AFT tasks and combine it with agent activity when reporting presence. It could also choose its own grace period before releasing busy state, allowing the completion wake to start. A fixed grace period would be an adapter policy, not a guarantee that the agent has resumed.

Today the task handoff can be observed through tool-result details, but the out-of-band completion reaches other extensions only as the text of an injected user message. Parsing [BACKGROUND BASH COMPLETED] is not a supported lifecycle contract and does not cover every inline/watch delivery path cleanly. Pi's tool_execution_end means the tool call returned, not that its background process exited.

This proposal only provides the generic observations. It does not claim that the stock Herdr integration will consume them automatically; the consumer-side presence adapter remains separate.

Relation to #640

I saw that #640 was closed with a decision not to add plugin-visible completion events for shell cleanup wrappers. This request asks whether that decision can be reconsidered for a different use case: host-side session presence and completion notifications.

The suggested shell-level cleanup or trap is appropriate for command cleanup, but it cannot update Pi's in-process extension event bus or represent Pi session activity to its host. No plugin-only execution flag, no-detach override, sudo handling, or final-output interception is requested here.

Proposed implementation

A working proposal is available in my fork:

• Branch: https://github.com/chpock/aft/tree/feat/pi-background-bash-events
• Commit: chpock@bf0f83a27
• Diff: chpock/aft@main...feat/pi-background-bash-events

The change is limited to packages/pi-plugin:

• Publish start at the live background handoff.
• Observe completion through existing push, piggyback, durable-drain, task-exit-pattern, and terminal status/watch/kill paths; suppress repeated completion events.
• Preserve start-before-completion ordering when completion beats the spawn reply.
• Document the payload, terminal-status semantics, and runtime-local scope. Events are not a durable inventory; consumers clear state on session shutdown/reload, and inherited tasks are not re-announced.
• Add unit regression coverage and gated real-engine tests for successful and failing commands, checking event counts and the existing completion wake. The native cases include async-watch exits while another Pi session is active.

Validation: the Pi plugin unit suite passes (1084 passed, 2 platform/fixture skips); all 4 new real-engine cases pass with AFT 0.62.0. Package typecheck/build, changed-file lint, and repository formatting pass. Independent review found a cross-session task_exit routing omission, which was fixed and re-reviewed without further findings.

No Rust engine or transport protocol change is proposed. I have not opened a PR; I am requesting design discussion/approval first, as required by the contribution policy. The branch is a concrete proposal, not an assumption that this API is already approved.