A Routine Result Is Not a Delivery

A scheduled agent can finish its work and still fail the person who asked for it. The model produced text. The shell command exited. The routine history says it ran. But its result never reached a human.

That is why APX treats routine output and routine delivery as separate steps. A result is what the routine produced. Delivery is where that result actually goes—and whether that route accepted it.

APC is the portable context layer: repository-owned rules, agent definitions, and skills that travel with a project. APX is the daily-use runtime and tooling layer. It runs a scheduled job, chooses its local delivery channels, and records the operational outcome. This is runtime behavior, so it belongs in APX, not in APC.

Delivery is opt-in

APX resolves delivery in a deliberate order:

1. The routine's own deliver_to setting.
2. The runtime default at config.routines.deliver_to.
3. No delivery.

That final default is intentional. A newly introduced delivery feature should not change where older routines send output. A routine must opt in before its result becomes a message on a channel.

For example, a routine can calculate a daily status and produce a useful answer. Without a configured delivery target, it has completed computation—not communication. The distinction prevents a misleading green checkmark.

One output, one owner

A second failure mode is double delivery. A routine can send a Telegram message itself, run a post_commands shell hook that sends the same text, and also have configured delivery. One logical report then becomes several notifications.

APX checks for channels already served by the routine handler, its post-command sinks, or an agent tool call. It suppresses the redundant path rather than assuming every configured route should fire.

This changes how to design a routine. Pick one delivery owner for each channel:

{
  "kind": "exec_agent",
  "spec": {
    "agent": "default",
    "no_tools": true,
    "prompt": "Summarize today's status in one short paragraph."
  },
  "deliver_to": ["telegram"]
}

The routine creates the text; configured delivery owns the Telegram send. Alternatively, a hand-written apx telegram send "$APX_LLM_OUTPUT" post-command can own that send. Do not configure both as independent paths for the same message.

A failed route should look failed

APX records a result for each delivery channel: ok, held, or error. An unknown channel is reported as an error rather than silently ignored. If delivery was requested but no channel accepted the message—and no earlier path already served it—the routine ends in an error state with a direct explanation: it produced an answer and no one received it.

held is different from failure. It means an interruption or notification budget deliberately withheld the message. The result remains available in the run log and routine memory instead of being discarded or mislabeled as sent.

That distinction is useful operationally:

• ok: result reached configured channel.
• held: runtime deliberately delayed or withheld a notification.
• error: route did not accept delivery; investigate configuration or service state.

Ordinary reports need less noise

For ordinary Telegram-bound routine reports, APX can record a pending delivery first. The daemon gives the owner a short grace period to open the agent chat and reply. If that happens, the delivery becomes answered and the extra notification is canceled. If it remains pending, a later sweep notifies the owner. Priority or anchor deliveries notify immediately.

This is a small product rule with a practical effect: a user who already saw the report does not receive an unnecessary second ping, while an unseen report does not vanish inside a routine log.

The useful test for a scheduled agent is therefore not only “did it run?” Ask:

1. Did it produce the intended result?
2. Which channel owned delivery?
3. Was that channel ok, held, or error?
4. Could another path have sent the same report twice?

Let APC carry the portable instructions that define the work. Let APX own the local execution and delivery record. A routine becomes useful only when its result reaches the right person exactly once.