Add a worktree-proximity reference application

[ScriptedAlchemy]

Summary

Add an examples/ application that proves Agent Bundle can support custom
request hooks, context providers, cross-process topology state, semantic event
routes, RSC guidance, and directed notices without baking collision logic or a
daemon into framework core.

This is intentionally a demanding application example, not a request for
useWorktree, topology inference, dependency-overlap analysis, or collision
policy in framework core.

Scenario

One root task has two child agents in separate Git worktrees. Each begins
working on files whose dependency or path sets overlap. Application code—not
the framework—detects proximity and warns both actors through the delivery
routes their hosts support.

Example structure

examples/worktree-proximity/
  agent-bundle.config.ts
  src/
    providers/
      git-worktree.ts
      agent-topology.ts
    state.ts
    events/
      session/start.tsx
      agent/start.tsx
      tool/before.tsx
      tool/after.tsx
      stop.tsx
    domain/
      proximity.ts
    mcp/
      coordinator/tools/status.tsx
  tests/

The example authors custom APIs from framework primitives:

export const worktree = async (): Promise<WorktreeContext> =>
  (await agent()).providers.gitWorktree;

export const useWorktree = (): WorktreeContext =>
  useAgent().providers.gitWorktree;

The proximity evaluator remains ordinary application code:

export default async function BeforeTool() {
  const { actor, event, providers, notices } = await agent();
  const conflicts = await findProximity(
    providers.agentTopology.snapshot,
    providers.gitWorktree,
    event,
  );

  await Promise.all(conflicts.map((conflict) =>
    notices.publish({
      recipient: { actorId: conflict.actorId },
      content: <Agent.Warning>{conflict.summary}</Agent.Warning>,
    }),
  ));

  return conflicts.length === 0
    ? null
    : <Agent.Warning>{conflicts[0].summary}</Agent.Warning>;
}

Evidence boundary

The deterministic suite uses generated host adapters, two real child hook
processes, separate Git worktrees, and one durable local state driver. It is an
artifact/contract integration test, not proof that an external commercial host
actually dispatched the events.

Optional native smoke runs remain separately authorized and evidence-labelled.

Required journeys

1. Observe a root actor and two child actors with explicit parent provenance.
2. Associate each actor with a distinct worktree and current activity.
3. Record non-overlapping work and emit no warning.
4. Record overlapping path/dependency intent and warn the current actor.
5. Publish a notice for the other actor.
6. Deliver that pending notice on the other actor's next event when no native
   directed-message API exists.
7. Deduplicate repeated native events.
8. Mark parent identity unavailable for a fixture whose host does not expose it
   and refuse to fabricate a topology edge.
9. Restart all hook processes and retain topology/notices through durable
   storage.

Acceptance criteria

• The example contains no framework-private imports or handwritten host JSON.
• Custom worktree() and useWorktree() APIs are implemented solely through
  the public context-provider contract.
• Two independent processes share exact state revisions without a daemon.
• Collision logic is isolated in the example domain module.
• Current and remote-recipient warnings use the real Agent Document and notice
  projectors.
• Unsupported identity/delivery states are visible and tested.
• The scaffold documents the external-driver boundary. It claims external
  integration only if a real adapter is connected and passes the state-driver
  conformance suite; a disconnected example is not presented as integrated.

Design references

• Git worktree model
• Current Agent Bundle RSC reference application's four-plane architecture
• Current Agent Bundle request-context seam
• Current cross-process example state kernel
• TraceDecay canonical core events
• TraceDecay host dispatch boundary

Stack position

• Depends on: #93 routes, #95 context/providers, #96 RSC renderer, #97 events, #98 state, #99 notices, and #103 Rstest.
• Serves as the integration proof that these independent features compose into
  a TraceDecay-class coordination application.
• Does not unlock framework primitives; it validates their composition and
  documents how application authors roll their own domain hooks.

Full meta-framework stack

• Foundations: #93 routes - #94 identity - #95 context - #96 renderer
• Runtime: #97 events - #98 state - #99 notices
• Host: #100 components - #101 lifecycle
• Surfaces and proof: #102 CLI/scripts - #103 Rstest - #104 proximity example - #105 Workbench