[Feature]: Add an atomic guarded wake primitive for idle threads

[Fr4nzz]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/server

Problem or use case

I have a working standalone monitor for long-running external work: arbitrary
processes, file/sentinel conditions, and structured polling commands, with LSF
as an optional external adapter. The monitor stays outside T3 so it does not
hold a tool call open and the chat remains responsive.

When an event occurs, the monitor needs to wake one exact existing T3 thread
only after that thread becomes idle. It persists the event before attempting a
wake, uses a short-lived loopback-only T3 session, retries with deterministic
command/message IDs, and revokes the session after each attempt.

The remaining reliability gap is a time-of-check/time-of-use race between
reading the thread/session state and submitting thread.turn.start. A user turn
can become active or queued between those two operations. The current workaround
also relies on internal T3 orchestration behavior rather than a small supported
boundary intended for external local integrations.

Proposed solution

Add a small authenticated server operation—name illustrative, for example
thread.wake-if-idle—that atomically:

• validates the exact existing, non-archived thread;
• rejects or defer-signals if a turn is requested/running, the backing session
  is starting/running, or a user turn is already queued;
• accepts a caller-provided command ID so a retry can use T3's existing
  orchestration receipt/idempotency behavior;
• submits one normal user turn and returns its accepted sequence; and
• exposes no scheduler, polling, monitor-registry, or credential concepts.

This could be exposed through the existing authenticated local HTTP boundary,
the CLI, or both. The important part is that the idle precondition and dispatch
are one server-side operation.

Why this matters

External work often outlives an agent turn: builds, training, downloads,
cluster allocations, CI, exports, and remote batch jobs. A guarded wake lets a
small local monitor notify the correct thread when work changes state without
keeping Codex busy, blocking user messages, polling inside T3, or embedding
site-specific credentials in T3.

The standalone implementation has been live-tested for sentinel completion,
LSF state changes, transient session-issuance failure with successful retry,
Teleport authentication expiry, restart recovery, duplicate suppression, and
exactly one accepted dispatch.

Smallest useful scope

One server-side conditional dispatch operation plus focused tests for:

• busy-thread and queued-user-turn races;
• duplicate retries with the same command ID;
• exact-thread mismatch or archived thread;
• accepted-response loss followed by retry; and
• the accepted sequence returned on success.

No UI, background scheduler, polling loop, adapter registry, webhook receiver,
or external-job integration is needed.

Alternatives considered

• Keep the current external read-then-dispatch sequence. This works in practice
  but cannot close the busy-thread race and depends on internal APIs.
• Put scheduler adapters and polling inside T3. This would expand product scope
  and bring credential, lifecycle, and resource-management concerns into the
  server.
• Extend the broader automations proposal in [Feature]: Add Automations & Triggers (for loops) #3164. That issue targets product
  triggers and reusable automations; this request is only a low-level guarded
  dispatch primitive that external tools could use.
• Build on PR Add PR monitoring: server-driven babysit mode for agent threads #4428. Its claim/revalidate/dispatch/ack approach informed this
  request, but the PR is closed and its monitor-specific scope was much larger
  than the boundary proposed here.

Risks or tradeoffs

• The exact definition of "idle" must match T3's thread, session, and queued-turn
  state machine.
• Idempotency semantics need to be explicit when dispatch succeeds but the
  caller loses the response.
• This should remain authenticated and local-first; it should not create an
  unauthenticated remote wake surface.
• The API becomes a compatibility commitment, so the request/response contract
  should stay minimal.

Examples or references

• Related broad automations request: [Feature]: Add Automations & Triggers (for loops) #3164
• Prior monitor implementation: Add PR monitoring: server-driven babysit mode for agent threads #4428

I can share the standalone package, state-machine tests, sanitized live-test
evidence, and a focused implementation/test proposal if maintainers want to
pursue this boundary.

Contribution

• I would be open to helping implement this.

[Fr4nzz]

Published the standalone implementation as a public alpha:

• Repository: https://github.com/Fr4nzz/t3-external-monitor
• v0.3.0 alpha release: https://github.com/Fr4nzz/t3-external-monitor/releases/tag/v0.3.0

The core remains intentionally external to T3: detached one-shot monitoring for processes, sentinels/files, and structured JSON polling commands; durable pending-event/retry state; deterministic dispatch IDs; exact-thread checks; loopback-only origin; short-lived revoked sessions; cancellation/rearm/restart recovery; and no persisted credentials. LSF is only an optional generic adapter/example, with site-specific Sanger/Teleport behavior kept outside the package.

The release includes 33 automated tests, a threat model, migration/provenance notes, integration recipes, and a concise Codex skill intended to minimize agent/status tokens. The packaged path has also been live-tested for sentinel wake, transient T3 session-issuance recovery, busy-thread deferral, duplicate suppression, and authentication-expiry notification.

This makes the remaining upstream request concrete: the package still has to use version-sensitive local T3 CLI/HTTP behavior, and its two read-before-send checks cannot make the idle precondition plus dispatch atomic. A small authenticated guarded-wake operation would close that final race without moving polling, scheduler adapters, credentials, or a monitor registry into T3.

Happy to adapt the boundary or provide a focused consumer-side test matrix if maintainers are interested.