coord

func (ChatMessage) Body ¶

func (m ChatMessage) Body() string

Body returns the message payload as a string.

func (ChatMessage) From ¶

func (m ChatMessage) From() string

From returns the agent identifier of the message sender.

func (ChatMessage) MessageID ¶

func (m ChatMessage) MessageID() string

MessageID returns the substrate-assigned identifier for this message. Opaque to callers — consumers pass it back to coord.React as the target identifier without interpreting the contents. Source-compatible extension to ChatMessage.

func (ChatMessage) ReplyTo ¶

func (m ChatMessage) ReplyTo() string

ReplyTo returns the parent message ID when the message is a reply, or the empty string for a top-level post.

func (ChatMessage) Thread ¶

func (m ChatMessage) Thread() string

Thread returns the 8-character short thread identifier the message was posted under. This matches coord.Post's caller-visible thread identity, which collapses to notify's ThreadShort form; later phases may add a separate accessor for the full UUID-shaped ID if a consumer needs it.

func (ChatMessage) Timestamp ¶

func (m ChatMessage) Timestamp() time.Time

Timestamp returns the UTC wall-clock time the message was created.

func (*Claim) Release ¶

func (c *Claim) Release() error

Release un-claims the task and releases held files. Safe to call more than once.

func (*Claim) TaskID ¶

func (c *Claim) TaskID() TaskID

TaskID returns the claimed task's identifier.

func (Config) Validate ¶

func (c Config) Validate() error

Validate checks every Config field against its documented bounds and returns the first violation as an error. Validate is pure; it does not panic on bad operator input per invariant 9.

Callers must apply defaultTuning before Validate; Open does this automatically. Direct Validate callers (tests) should call defaultTuning themselves if they rely on zero-value Tuning fields.

func (*Coord) Answer ¶

func (c *Coord) Answer(
	ctx context.Context,
	handler func(ctx context.Context, question string) (string, error),
) (func() error, error)

Answer registers handler as the responder for peer questions addressed to this agent. The subject subscribed on is <proj>.ask.<c.cfg.AgentID>: peers call Ask with this agent's ID as the recipient and their request lands in handler. The handler returns either (reply, nil) to send a reply or ("", err) to drop the request — ADR 0008 does not model error payloads, so a handler error is indistinguishable from "no handler registered" from the Ask caller's side (both surface as ErrAskTimeout).

The handler receives context.Background, not the Ask caller's ctx: the notify/NATS substrate has no per-message ctx to thread through, and fabricating one with a timeout would introduce a second deadline unrelated to the caller's. Handlers that need bounded work should construct their own ctx inside.

The returned closure is an idempotent unsubscribe: the first call tears down the subscription; subsequent calls are no-ops and return nil. sync.Once-guarded so concurrent defer sites cannot double-close. Safe to call after Coord.Close: the underlying chat Manager will have been torn down by then and the closure silently no-ops on the already-closed subscription.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 8 (Coord not closed). handler non-nil likewise panics.

Operator errors returned:

Any substrate error from chat.Respond — e.g. a NATS subscribe
    failure — surfaces wrapped with the coord.Answer prefix.

func (*Coord) Ask ¶

func (c *Coord) Ask(
	ctx context.Context, recipient string, question string,
) (string, error)

Ask sends a synchronous question to a peer agent and waits for a reply on the <proj>.ask.<recipient> subject. The reply, when it arrives, is returned as a string. Recipient is opaque: coord does not verify that anyone is listening before sending — if no peer has Answer registered for the subject, the ctx deadline elapses and Ask returns ErrAskTimeout. Per ADR 0008 this is deliberate: the substrate cannot cheaply distinguish "no one listening" from "listener is slow", and surfacing them identically keeps the caller's retry strategy honest (both cases want another attempt or a give-up).

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 8 (Coord not closed). Recipient and question non-empty preconditions likewise panic.

Operator errors returned:

ErrAskTimeout — ctx deadline elapsed, or no responder answered
    within the deadline. Distinct from context.Canceled.
context.Canceled — ctx was canceled (not deadlined) before or
    during the request. Surfaces wrapped with the coord.Ask
    prefix. Distinct from ErrAskTimeout.
Any other substrate error — e.g. a NATS publish failure — is
    wrapped with the coord.Ask prefix and returned verbatim.

func (*Coord) AskAdmin ¶

func (c *Coord) AskAdmin(
	ctx context.Context, recipient string, question string,
) (string, error)

AskAdmin sends a synchronous question to a peer agent after first pre-flighting the recipient against the project's presence bucket. If the pre-flight finds no live presence entry for recipient, AskAdmin returns ErrAgentOffline without touching the chat substrate. When the pre-flight succeeds, AskAdmin delegates to the same chat.Request path as Ask — same subject shape (<proj>.ask.<recipient>), same reply-wait semantics, same error translation table.

The "Admin" naming is a holdover from ADR 0008's scope-out language around admin-override semantics. Any agent may call AskAdmin; there is no role-based restriction in Phase 4. Role-based auth is deferred to Phase 6+.

ErrAgentOffline vs. ErrAskTimeout: the pre-flight sentinel narrows the "no one was listening at call time" branch to a directory-based answer, so callers that want to distinguish "recipient does not exist" from "recipient is slow" have a machine-checkable boundary. A successful pre-flight that then times out returns ErrAskTimeout as usual — presence entries can age out between pre-flight and publish, and the timeout path remains the source of truth for substrate-observed non-delivery. Callers that do not want the pre-flight cost continue to use Ask.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 8 (Coord not closed). Recipient and question non-empty preconditions likewise panic.

Operator errors returned:

ErrAgentOffline — presence pre-flight found no live entry for
    recipient in this project. Distinct from ErrAskTimeout.
ErrAskTimeout — pre-flight succeeded but the reply-wait
    deadline elapsed before a response arrived. Same semantics
    as Ask's ErrAskTimeout.
context.Canceled — ctx was canceled (not deadlined) before or
    during the call. Surfaces wrapped with the coord.AskAdmin
    prefix. Distinct from ErrAskTimeout.
Any other substrate error — e.g. a presence Get failure or a
    NATS publish failure — is wrapped with the coord.AskAdmin
    prefix and returned verbatim.

func (*Coord) Blocked ¶

func (c *Coord) Blocked(ctx context.Context) ([]Task, error)

Blocked returns open, unclaimed tasks that are currently blocked by at least one non-closed task via an incoming `blocks` edge. Results are sorted oldest-first and capped by Config.MaxReadyReturn.

func (*Coord) Claim ¶

func (c *Coord) Claim(
	ctx context.Context,
	taskID TaskID,
	ttl time.Duration,
) (func() error, error)

Claim atomically acquires a task for this agent. Reads the task record from NATS KV; CAS-updates it to status=claimed, claimed_by=cfg.AgentID; then acquires file-scoped holds on every file declared in the record. If the CAS loses (task already claimed by another agent, or closed), returns ErrTaskAlreadyClaimed and does not attempt holds. If any hold fails, the task CAS is undone before the error return.

The returned release closure is idempotent (invariant 7) and symmetric with Claim: it CAS-un-claims the task record (status back to open, claimed_by cleared) AND releases every hold. A task that was concurrently closed by the claimer via CloseTask will NOT be un-claimed by release — the closed state is terminal. Callers should defer release; it is safe to defer even if CloseTask has already run.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 2 (TaskID non-empty), 5 (ttl > 0 and <= HoldTTLMax), 8 (Coord not closed). Invariant 16 governs the release closure.

Operator errors returned:

ErrTaskNotFound, ErrTaskAlreadyClaimed, ErrHeldByAnother.

func (*Coord) Close ¶

func (c *Coord) Close() error

Close shuts down the Coord. Safe to call more than once; subsequent calls are no-ops and return nil. Close itself never panics once the receiver is non-nil (invariant 8 governs method calls after Close, not Close itself).

Release closures returned by Claim remain callable after Close; they silently no-op (see releaseClosure). This keeps defer-style shutdown from racing the Coord lifecycle.

func (*Coord) CloseTask ¶

func (c *Coord) CloseTask(
	ctx context.Context, taskID TaskID, reason string,
) error

CloseTask marks a task closed with an explanatory reason. The caller must be the current claimed_by on the task record (invariant 12); a mismatch returns ErrAgentMismatch. Transition rules follow invariant 13 (open→closed and claimed→closed allowed; closed→closed returns ErrTaskAlreadyClosed; no other transitions are legal).

Because invariant 11 couples claimed_by to status, an open task has ClaimedBy == "" and the identity check ("" != AgentID) fires as ErrAgentMismatch. This is intentional: Phase 2 has no admin override, so only the agent holding the claim may close. Operators that need to close an un-claimed task must first claim it.

Invariants asserted (panic on violation — programmer errors):

1 (ctx non-nil), 2 (TaskID non-empty), 8 (Coord not closed).

Operator errors returned:

ErrTaskNotFound, ErrAgentMismatch, ErrTaskAlreadyClosed.

Other errors from the CAS write path are returned wrapped.

func (*Coord) HandoffClaim ¶

func (c *Coord) HandoffClaim(
	ctx context.Context,
	taskID TaskID,
	fromAgent string,
	ttl time.Duration,
) (func() error, error)

HandoffClaim transfers an already-claimed task from fromAgent to the caller. Unlike Reclaim, the current claimer may still be live; this is an intentional cooperative handoff used by the dispatch harness so a worker process can own Commit/CloseTask itself.

Preconditions:

• task must exist and be in claimed status
• current claimed_by must match fromAgent
• caller must not already be the claimer

On success the task record stays claimed, claimed_by becomes the caller's AgentID, claim_epoch is bumped, old holds are released, and new holds are acquired under the caller. The returned release closure is identical in behavior to Claim/Reclaim's release closure.

func (*Coord) Link ¶

func (c *Coord) Link(ctx context.Context, from, to TaskID, edgeType EdgeType) error

Link records an outgoing typed edge from one task to another per ADR 0014. Any agent may Link; no claimed_by check (Phase 6 posture).

Preconditions:

• edgeType must be one of EdgeBlocks, EdgeDiscoveredFrom, EdgeSupersedes, EdgeDuplicates. Other values return ErrInvalidEdgeType (invariant 26).
• from and to must both exist. The to task may be in any status, including closed (supersedes/duplicates are valid against closed targets).

Link is idempotent on (from, to, edgeType): a second call with the same triple is a no-op (invariant 25). CAS-retry is inherited from tasks.Manager.Update — concurrent Link calls converge without caller involvement.

func (*Coord) OpenTask ¶

func (c *Coord) OpenTask(
	ctx context.Context, title string, files []string,
) (TaskID, error)

OpenTask creates a new task record with status=open and returns its generated TaskID. Files must be non-empty, bounded by cfg.MaxTaskFiles, every path absolute, and are sorted+deduplicated here before Create (callers need not pre-sort).

Title is the human-readable summary; it must be non-empty. No upper bound is enforced beyond internal/tasks's MaxValueSize check on the encoded record.

Invariants asserted (panics on violation — programmer errors):

1 (ctx non-nil), 4 (files shape), 11 (status=open iff claimed_by
empty), 15 (generated TaskID matches ADR 0005 shape).

Other underlying errors are returned wrapped; a CAS-Create collision on a generated ID is a broken-generator condition that panics via assert.Postcondition rather than silently retrying.

func (*Coord) Post ¶

func (c *Coord) Post(
	ctx context.Context, thread string, msg []byte,
) error

Post publishes a message body to a chat thread via the internal chat.Manager, which routes through EdgeSync notify per ADR 0008. Persistence is delegated to notify's Fossil backing — coord itself owns no chat-message state.

ctx is pre-checked inside chat.Send before any repo or NATS work, so a canceled ctx short-circuits cleanly. Once notify.Service.Send is entered, it runs to completion: the upstream API takes no ctx and cannot be interrupted mid-write. ADR 0008 documents the limitation; observed write latency is sub-millisecond in normal operation.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 8 (Coord not closed). The thread-non-empty precondition is likewise a programmer error and panics.

Operator errors returned:

context.Canceled / context.DeadlineExceeded — ctx finalized
    before chat.Send entered notify; surfaces wrapped with the
    coord.Post prefix.
chat.ErrClosed — the chat manager was closed underneath (usually
    via Coord.Close racing with an in-flight Post).
Any substrate error from notify — e.g. a NATS publish or Fossil
    write failure — surfaces wrapped with the coord.Post prefix.

func (*Coord) PresentAgentIDs ¶ added in v0.2.0

func (c *Coord) PresentAgentIDs(ctx context.Context) ([]string, error)

PresentAgentIDs returns just the AgentID values from Who as a flat string slice. Convenience for callers (e.g. dispatch's WaitWorkerAbsent) that only need the IDs and would otherwise flatten the slice themselves; the method reference satisfies dispatch.PresenceProbe directly.

func (*Coord) Prime ¶

func (c *Coord) Prime(ctx context.Context) (PrimeResult, error)

Prime returns a full snapshot of the workspace: open tasks, tasks ready for this agent, tasks claimed by this agent, recent chat threads this agent participates in, and live peers.

Prime is safe to call concurrently. It is the recommended entry point for session-start context recovery (ADR 0015).

func (*Coord) React ¶

func (c *Coord) React(
	ctx context.Context, thread, messageID, reaction string,
) error

React posts a reaction to the message identified by messageID in the given thread. The reaction payload is opaque to coord — emoji, text, or arbitrary bytes all pass through untouched — and is surfaced to peers subscribed to the same thread as a Reaction event on the coord.Subscribe channel.

Reactions piggyback on the chat substrate: they are encoded in-band as a notify.Message body with the REACT prefix and routed through the same chat.Send path as Post. No new KV bucket, no new NATS subject. The encoding is a substrate detail and never appears on the public surface — callers emit reactions through React and receive them through Subscribe as Reaction events.

messageID is whatever ChatMessage.MessageID returned for the target message. Coord does not verify that messageID corresponds to a real message on the thread: a reaction to a non-existent message will still publish, and consumers receive it as a Reaction event with a target that matches no visible chat. This is deliberate — the alternative would couple reactions to a per-message lookup on the write path, which the chat substrate was designed to avoid.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 8 (Coord not closed). Thread, messageID, and reaction non-empty preconditions likewise panic.

Operator errors returned: any substrate error from chat.Send, wrapped with the coord.React prefix.

func (*Coord) Ready ¶

func (c *Coord) Ready(ctx context.Context) ([]Task, error)

Ready returns open, unclaimed tasks eligible to be worked on, sorted oldest-first and capped by Config.MaxReadyReturn. A task is eligible iff ALL of the following hold:

• status == open
• claimed_by == "" (not held by another agent)
• no incoming blocks edge from a non-closed task (ADR 0014)
• no incoming supersedes edge from a non-closed task
• no incoming duplicates edge from a non-closed task
• no non-closed task names it as Parent (parent waits on children)

Cost is O(N+E) where N is the task count and E is the total edge count across non-closed tasks; the reverse index is rebuilt on every call. If this becomes a bottleneck, a cached reverse index is a future optimization (see ADR 0014 §Consequences).

discovered-from edges are stored but intentionally ignored by the filter — they are audit metadata, not a ready-blocker.

func (*Coord) Reclaim ¶

func (c *Coord) Reclaim(
	ctx context.Context,
	taskID TaskID,
	ttl time.Duration,
) (func() error, error)

Reclaim transfers an abandoned claim from a crashed or unreachable agent to the caller. Preconditions per ADR 0007:

1. Task must exist and be in 'claimed' status — Reclaim on an 'open' task returns ErrTaskNotClaimed (the caller wants Claim).
2. The current claimed_by agent must be absent from coord.Who — otherwise ErrClaimerLive. Presence entries expire after 3 × HeartbeatInterval per Invariant 19.
3. Caller must not be the current claimed_by — self-reclaim is nonsensical; returns ErrAlreadyClaimer.

On success: the task record is CAS-re-claimed with the caller's AgentID, claim_epoch bumped (Invariant 24), holds re-acquired under the caller's ID, and a single-line reclaim notice posted to the task's chat thread best-effort.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 2 (TaskID non-empty), 5 (ttl > 0 and <= HoldTTLMax), 8 (Coord not closed).

Operator errors returned:

ErrTaskNotFound, ErrTaskNotClaimed, ErrClaimerLive,
ErrAlreadyClaimer, ErrHeldByAnother. Other substrate errors are
wrapped with the coord.Reclaim prefix.

func (*Coord) Subscribe ¶

func (c *Coord) Subscribe(
	ctx context.Context, pattern string,
) (<-chan Event, func() error, error)

Subscribe returns a channel of coord.Event values for messages that match pattern, plus a close closure the caller must invoke to tear the subscription down. Phase 3 ships ChatMessage as the only concrete event type; consumers read with a type switch per ADR 0008.

pattern is the coord-facing thread filter. An empty pattern selects every thread in this agent's project (the documented project-wide path, used by the 2w5 smoke test); the non-empty pattern is a caller-supplied thread name, mapped deterministically to a notify ThreadShort via SHA-256 — two Coords watching the same name subscribe to the same stream (see ADR 0008's 2026-04-19 update). Glob patterns are a Phase 4 follow-up.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 8 (Coord not closed). pattern is NOT asserted non-empty — empty is valid and selects the project-wide stream.

Runtime enforcement:

ErrTooManySubscribers — returned if the live-subscription count on
    this Coord already equals Config.MaxSubscribers at entry. The
    caller may retry after an existing subscription's close closure
    has run (invariant 17 ensures decrement happens exactly once).

The returned close closure cancels an internal ctx derived from the caller's ctx, waits for the relay goroutine to drain, and decrements the live-subscription counter. The Event channel itself is closed by the relay goroutine as it exits, so both the explicit-close and the caller-ctx-canceled paths funnel through the same close site — no second close(chan) call is needed here, and the channel is never double-closed. sync.Once-guarded so subsequent calls return nil and take no action (invariant 17).

func (*Coord) SubscribePattern ¶

func (c *Coord) SubscribePattern(
	ctx context.Context, pattern string,
) (<-chan Event, func() error, error)

SubscribePattern returns a channel of coord.Event values for every thread whose ThreadShort matches the given NATS subject-segment pattern, plus a close closure the caller must invoke to tear the subscription down. Patterns use NATS subject-wildcard syntax: "*" matches every ThreadShort (equivalent to Subscribe(ctx, "") on the project-wide path), ">" matches every ThreadShort plus any hypothetical subsegments, and a literal pattern matches a single ThreadShort — usefully, the string returned by ChatMessage.Thread() on an earlier event, so a consumer can bootstrap a pattern subscription from observed traffic without round-tripping through the thread-name hash.

Unlike Subscribe, SubscribePattern does NOT hash its pattern — callers supply a raw substrate-level pattern. This is a deliberate substrate leak: it delivers glob-Subscribe without a new KV registry bucket or per-Post write cost. Callers that need name-level pattern matching (e.g. "deploy.*" matching thread names) must layer a registry themselves.

pattern is asserted non-empty to keep the "project-wide" path on Subscribe(ctx, "") and the "pattern" path on SubscribePattern. Callers wanting everything should prefer Subscribe's empty-pattern shorthand over SubscribePattern("*") — the two subscriptions are behaviorally identical but Subscribe is the documented entry point for the wildcard-all case.

Invariants asserted: 1 (ctx non-nil), 8 (Coord not closed). Pattern non-empty panics before any substrate work.

Runtime enforcement:

ErrTooManySubscribers — returned if the live-subscription count on
    this Coord already equals Config.MaxSubscribers at entry.
    Shared with Subscribe; the slot is freed by the close closure
    (invariant 17).

The returned close closure shares the cancel/drain/decrement shape of Subscribe's closer — sync.Once-guarded and safe to call from multiple goroutines.

func (*Coord) WatchPresence ¶

func (c *Coord) WatchPresence(
	ctx context.Context,
) (<-chan Event, func() error, error)

WatchPresence returns a channel of coord.Event values that fire whenever an agent comes online or goes offline in this Coord's project. Concrete type is PresenceChange. Consumers discriminate via the standard Event type switch (ADR 0008); mixing chat and presence events on the same switch is permitted because the sealed interface carries both types.

The initial snapshot is NOT replayed: Watch starts from the moment of subscription. Use Who for a snapshot; use WatchPresence for deltas. Consumers that want both sequence them explicitly.

The returned close closure is idempotent per invariant 17 — the first call cancels the internal ctx, waits for the relay goroutine to drain, and closes the event channel; subsequent calls return nil and take no action.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 8 (Coord not closed).

Operator errors returned: any substrate error from the KV watch path, wrapped with the coord.WatchPresence prefix.

func (*Coord) Who ¶

func (c *Coord) Who(ctx context.Context) ([]Presence, error)

Who returns the live-presence snapshot for this Coord's project. Each Presence describes one agent whose heartbeat KV entry is still current (not yet TTL-expired). The list includes this Coord itself — Open writes our initial entry before returning, so the caller's own Coord is always visible in Who by the time Who can be called.

Project scoping matches the Post/Ask scheme: agents in other projects are not surfaced. This is a fresh read; presence state is read-through the KV with no client-side caching.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), 8 (Coord not closed).

Operator errors returned: any substrate error from the KV list/scan path, wrapped with the coord.Who prefix.

func (*Hub) HTTPAddr ¶

func (h *Hub) HTTPAddr() string

HTTPAddr returns the hub's HTTP listen address, suitable as the hubHTTPAddr argument to OpenLeaf.

func (*Hub) LeafUpstream ¶

func (h *Hub) LeafUpstream() string

LeafUpstream returns the URL remote agents pass as NATSUpstream to peer their meshes into the hub's mesh as leaf nodes. The hub mesh accepts these solicits on its leaf-node port (separate from the client port returned by NATSURL).

func (*Hub) NATSURL ¶

func (h *Hub) NATSURL() string

NATSURL returns the hub's NATS client URL — the agent's mesh accepts regular client connections here. Use this for non-agent NATS clients (e.g. coord's claim/task KV traffic from the same process). For remote agents joining the hub's mesh upstream, see LeafUpstream.

func (*Hub) Stop ¶

func (h *Hub) Stop() error

Stop shuts down the agent (which also shuts down its embedded NATS mesh). Safe to call more than once; subsequent calls are no-ops.

func (HubAddrs) IsEmpty ¶

func (a HubAddrs) IsEmpty() bool

IsEmpty reports whether all three URL fields are empty. OpenLeaf uses this to choose between Hub and HubAddrs when LeafConfig has both set or both empty.

func (*Leaf) AnnounceHolds ¶

func (l *Leaf) AnnounceHolds(
	ctx context.Context, paths []string,
) (release func(), err error)

AnnounceHolds acquires file-scoped holds under the leaf's slot identity for every path in paths. Idempotent for files already held by this slot (holds.Announce treats same-agent re-announce as a lease renewal); returns an error if any path is currently held by a DIFFERENT identity (ErrHeldByAnother, wrapped). On success returns a release closure that releases every successfully-held file.

Designed for swarm-style flows where the slot's worktree is its territory but the task record's Files list may not have been pre-populated at task-create time. Callers (e.g. `bones swarm commit`) call AnnounceHolds before Commit so the hold-gate (see checkHolds / Invariant 20) sees the per-path holds the slot needs to commit.

Paths must be absolute (holds.Announce asserts on this). The release closure swallows individual release errors — best-effort cleanup, mirroring the semantics of the Claim release closure.

func (*Leaf) Claim ¶

func (l *Leaf) Claim(ctx context.Context, taskID TaskID) (*Claim, error)

Claim atomically acquires taskID for this leaf. The returned *Claim carries an idempotent release closure. Delegates to the underlying Coord; Phase 1 keeps the existing claim semantics intact.

func (*Leaf) Close ¶

func (l *Leaf) Close(ctx context.Context, claim *Claim) error

Close marks the claimed task closed. Delegates to the underlying Coord.CloseTask; the *Claim's release closure is also called so any remaining file holds drop. After Close returns, the *Claim should not be reused.

func (*Leaf) Commit ¶

func (l *Leaf) Commit(
	ctx context.Context, claim *Claim, files []File, opts ...CommitOption,
) (string, error)

Commit writes files into the leaf's libfossil repo as a new checkin authored by the slot, then triggers a sync round (SyncNow).

When LeafConfig.Autosync was true at OpenLeaf time, Commit performs a hub HTTP round-trip (pull /xfer) BEFORE resolving the trunk tip so the new commit's parent is the latest hub-known commit. This is the implementation of trunk-based development across slots: every slot.Commit advances a shared trunk rather than producing a parallel leaf that fan-in must collapse later. Cost is one network round-trip per Commit; callers that prefer offline tolerance over linearity should set Autosync=false at OpenLeaf time and accept branch-per-slot semantics.

The hold-gate (Invariant 20) and epoch-gate (Invariant 24) are enforced via the leaf's Coord: every File.Path must be held by this leaf at call time, and the *Claim's TaskID must still be active with the same claim_epoch the leaf last observed.

All writes route through l.agent.Repo() — there is no second *libfossil.Repo handle to leaf.fossil in this process. Per architectural invariant: one *libfossil.Repo per fossil file, owned by leaf.Agent.

On success, returns the manifest UUID of the new checkin.

Variadic CommitOptions tune commit-time fields. WithMessage replaces the default "leaf commit for task <id>" comment with a caller-supplied string; WithUser overrides the slot-derived author.

func (*Leaf) Compact ¶

func (l *Leaf) Compact(ctx context.Context, opts CompactOptions) (CompactResult, error)

Compact summarizes eligible closed tasks and writes one artifact per task into the leaf's libfossil repo as a new checkin authored by the slot. Eligibility: status=closed, CompactLevel=0, ClosedAt older than opts.MinAge. The summary body is produced by opts.Summarizer and the artifact path is `compaction/tasks/<TaskID>/level-<N>.md`.

All writes route through l.agent.Repo() — the only *libfossil.Repo handle to leaf.fossil in this process. After each commit, SyncNow triggers a sync round so the artifact propagates to the hub.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), receiver non-nil, opts.Limit > 0, opts.Summarizer non-nil. Operator errors from substrate reads (tasks.List) and the per-task summarize/commit/update/archive paths surface wrapped.

func (*Leaf) Metadata ¶

func (l *Leaf) Metadata(key string) string

Metadata returns the value associated with key in the harness-supplied metadata map (from LeafConfig.Metadata). Returns "" if the key is absent or if no metadata was provided.

func (*Leaf) OpenTask ¶

func (l *Leaf) OpenTask(ctx context.Context, title string, files []string) (TaskID, error)

OpenTask is a thin shim onto the leaf's substrate Coord so harnesses and Phase 1 callers can open tasks without reaching into private fields. Phase 2 may relocate task lifecycle entirely onto Leaf.

func (*Leaf) OpenWorktree ¶ added in v0.7.0

func (l *Leaf) OpenWorktree(ctx context.Context, dir string) error

OpenWorktree creates a fossil checkout at dir using the leaf's repo handle and extracts trunk's files into it. dir must already exist. The Checkout handle is closed before return: bones doesn't drive commits through it (Leaf.Commit writes through the repo handle directly per the "one *libfossil.Repo per fossil file" invariant); what downstream readers need is the on-disk `.fslckout` plus the materialized files.

On a fresh repo with no checkins this is a no-op: libfossil refuses to create a checkout without a checkin, and there are no files to write anyway. The next Acquire after the first slot commits will populate the worktree.

func (*Leaf) PostMedia ¶

func (l *Leaf) PostMedia(
	ctx context.Context,
	thread, mimeType string,
	data []byte,
) error

PostMedia stores opaque bytes in the leaf's libfossil repo and publishes an in-band media reference on the chat thread. Subscribers receive a MediaMessage event.

All writes route through l.agent.Repo() — the only *libfossil.Repo handle to leaf.fossil in this process. After the commit, SyncNow triggers a sync round so the artifact propagates to the hub before the chat reference is published; subscribers can then resolve the reference against any peer that has caught up.

Invariants asserted (panics on violation — programmer errors): 1 (ctx non-nil), receiver non-nil, thread/mimeType non-empty, data non-empty.

Operator errors returned: any error from the libfossil commit, the JSON envelope encode, or the chat substrate Send — surfaced wrapped with the coord.Leaf.PostMedia prefix.

func (*Leaf) Stop ¶

func (l *Leaf) Stop() error

Stop shuts down the underlying leaf.Agent. Idempotent.

func (*Leaf) Tip ¶

func (l *Leaf) Tip(ctx context.Context) (string, error)

Tip returns the manifest UUID at the head of the leaf's current branch, or "" on a fresh repo with no checkins.

func (*Leaf) WT ¶

func (l *Leaf) WT() string

WT returns the worktree path under which the slot's working copy lives.

func (MediaMessage) From ¶

func (m MediaMessage) From() string

func (MediaMessage) MIMEType ¶

func (m MediaMessage) MIMEType() string

func (MediaMessage) Path ¶

func (m MediaMessage) Path() string

func (MediaMessage) Rev ¶

func (m MediaMessage) Rev() RevID

func (MediaMessage) Size ¶

func (m MediaMessage) Size() int

func (MediaMessage) Thread ¶

func (m MediaMessage) Thread() string

func (MediaMessage) Timestamp ¶

func (m MediaMessage) Timestamp() time.Time

func (Presence) AgentID ¶

func (p Presence) AgentID() string

AgentID returns the agent's unique identifier.

func (Presence) LastSeen ¶

func (p Presence) LastSeen() time.Time

LastSeen returns the UTC wall-clock time of the agent's most recent heartbeat observed in the presence substrate.

func (Presence) Project ¶

func (p Presence) Project() string

Project returns the project segment the agent belongs to.

func (Presence) StartedAt ¶

func (p Presence) StartedAt() time.Time

StartedAt returns the UTC wall-clock time the agent's coord instance called Open. Stable across the Manager's lifetime — a consumer comparing two reads of the same AgentID can distinguish "same process, still up" from "restarted" by watching this field.

func (PresenceChange) AgentID ¶

func (p PresenceChange) AgentID() string

AgentID returns the identifier of the agent whose presence changed.

func (PresenceChange) Project ¶

func (p PresenceChange) Project() string

Project returns the project segment of the agent.

func (PresenceChange) Timestamp ¶

func (p PresenceChange) Timestamp() time.Time

Timestamp returns the wall-clock time the watcher observed the change, NOT the original event time at the substrate. Observed-time semantics match notify's delivery model.

func (PresenceChange) Up ¶

func (p PresenceChange) Up() bool

Up reports the direction of the change: true for became-online, false for went-offline. A Down event with no prior Up on the same consumer's watch is possible — the watch started after the initial Up — and a consumer that cares about the full picture should seed state from coord.Who before WatchPresence.

func (Reaction) Body ¶

func (r Reaction) Body() string

Body returns the reaction payload as a string. Coord does not validate or normalize the content — emoji, text, or arbitrary bytes all pass through untouched.

func (Reaction) From ¶

func (r Reaction) From() string

From returns the agent identifier of the reactor.

func (Reaction) Target ¶

func (r Reaction) Target() string

Target returns the MessageID of the chat message this reaction applies to. Opaque — the caller passed it into coord.React and received it back unchanged, consistent with ADR 0003's substrate- hiding rule for identifiers.

func (Reaction) Thread ¶

func (r Reaction) Thread() string

Thread returns the 8-character short thread identifier the reaction was posted under. Matches ChatMessage.Thread so consumers that track per-thread state can route on a single field.

func (Reaction) Timestamp ¶

func (r Reaction) Timestamp() time.Time

Timestamp returns the UTC wall-clock time the reaction was created.

func (Task) ClaimedBy ¶

func (t Task) ClaimedBy() string

ClaimedBy returns the AgentID currently holding the claim, or the empty string when the task is unclaimed.

func (Task) CreatedAt ¶

func (t Task) CreatedAt() time.Time

CreatedAt returns the UTC wall-clock time the task was opened.

func (Task) Files ¶

func (t Task) Files() []string

Files returns the absolute-path file list. The returned slice is a fresh copy; mutating it does not affect the coord record.

func (Task) ID ¶

func (t Task) ID() TaskID

ID returns the task's unique identifier.

func (Task) Title ¶

func (t Task) Title() string

Title returns the human-readable task title.

func (Task) UpdatedAt ¶

func (t Task) UpdatedAt() time.Time

UpdatedAt returns the UTC wall-clock time of the most recent write.