@hivecast/smithers (1.1.32)
Installation
@hivecast:registry=npm install @hivecast/smithers@1.1.32"@hivecast/smithers": "1.1.32"About this package
Smithers
Smithers supplies the existing durable task/attempt and admitted Fleet route backend. Its historical browser view is not the new Fleet control surface; Explorer consumes owner facts. The separately installed fleet coordinator reconciles tasks and starts sessions on installed Codex peers discovered through Registry and host-control.
The coordinator subscribes before replaying the durable Task journal and
reconciling active tasks. Events are fast wakeups; reconnect replays missed
events. A producer may also die after committing but before publishing while
the consumer remains connected. One retained 30-second recovery timer probes
task.journal.head even when there are no active tasks. The metadata is cached
by the Task owner and invalidated on writes: an unchanged idle probe performs
no journal scan, Task-list reconciliation, durable write or worker dispatch.
A metadata probe does not wait for an absent responder, and its deadline is at
most one configured recovery interval (30 seconds in production). A read sent
just before producer death therefore cannot occupy the serialized driver beyond
that budget. A changed head replays authoritative journal order. Live notifications also
replay journal order before advancing the cursor, so a later event cannot hide
a missed predecessor. Active work retains the same reconciliation interval.
(demo "S26") is the executable read-only manual: discover installed
coordinators, inspect their actual Task owner, durable journal head, consumer
cursor and recovery health. It never creates a Task or launches a coding worker.
A home without an installed coordinator explicitly reports that recovery was
not demonstrated there. Its estate catalogue status reflects native fixture
proof rather than a live shared-estate crash claim.
pnpm --dir applications/smithers test:recovery runs the same canonical Omega
program against independent real NATS/SQLite-backed processes. The fixture
kills only the producer after commit/before publication, keeps the consumer
connected, restarts each independently, drops/duplicates wakeups, drains a
backlog and checks durable attempts and worker effects. The inert test worker
performs no inference. Native fault injection is never exposed as a product
operation or run against shared staging. Diagnostics report actual recovery
latency and CPU/RSS/message costs with a 100 ms test interval; production uses
30 seconds. Those short fixture observations are not whole-platform idle or
staging measurements.
The isolated 100 ms-cadence fixture measured producer restart plus recovery at 1,278 ms, one durable attempt/effect, and a 550 ms idle window with five head probes, 10.917 ms of Node CPU and 376,635,392 bytes RSS (including the test TSX loader). Endpoint NATS counters increased by eight published messages; initial query/list counts stayed at 1/3 and no worker effect occurred. These are fixture observations, not a production idle budget. At rest the new recovery check trades zero journal probes for one per 30 seconds. During active work, authoritative replay reads the existing journal before advancing a cursor, so its cost depends on retained history; a wake hint alone is insufficient evidence to skip unseen events.
Related UX opportunities
Task continuity and the application opportunity map suggest composing the relevant task, agent and source views around durable work. Smithers and the fleet coordinator retain task/dispatch ownership; these ideas do not add another scheduler or change the dispatch and acceptance rules below.
Named agent workstreams
The Sessions panel projects self-reported coordination observations from the existing
system.blackboard owner alongside the machine/session tree. task.attempt.start and
smithers.agent.task accept a workstream object with explicit v1 metadata. Its agent
must match the selected named worker. For example, the object is:
{"schema":"fleet.agent-workstream/v1","agent":"named agent","functionalArea":"Shell","workstream":"Session continuity","presence":"available","status":"testing","blocker":"waiting for browser proof","handoff":"coordinator","suggestion":"keep the warm session"}
agent, functionalArea, workstream, presence, and status are nonempty strings;
blocker, handoff, and suggestion are optional strings. The selected Codex session
publishes one stable default.fleet.agent-workstream.<entry-id> row and retains its ID
with the session. task.steer / smithers.agent.steer forward an optional workstream
update; the session can also call session.workstream.upsert {sessionId, workstream}.
The named agent, area and workstream stay fixed; status, presence and optional details
can change. A registration without valid explicit metadata returns
FLEET_WORKSTREAM_METADATA_REQUIRED. An ordinary session without registration creates no row.
A completed, failed or stopped turn marks the row inactive; continuing the same session
reactivates it. Ending the retained task sends session.workstream.end to make the same
row inactive even if its turn is still running. Neither observation publication nor its
failure controls dispatch, completion, execution or approval. The worker reconciles its
retained observations on the existing heartbeat. Writes use Blackboard revision fences
and session sequence numbers so stale publications cannot overwrite newer observations.
Both packages declare fleet.agent-workstreams transport access to the existing store.
Smithers reads state.list with prefix default.fleet.agent-workstream., validates the
shared contracts schema and groups by functional area then workstream. Invalid entries
are omitted and counted in rejectedCount; values never come from prompts, process
names or checkout paths. Empty observations and unavailable reads have distinct states.
Queue dispatch
Queue source workers retain the tested commit under
refs/tags/fleet-candidates/<queue-item>/<task-id>/<attempt-id>. These lightweight
tags are create-only under ordinary Git push: repair attempts get new refs while
rejected bytes stay fetchable. Workers leave the queue claimed and incomplete,
never integrate or push main, and submit a source-candidate artifact with the
exact SHA, files, suite counts and affected check commands through their own
admitted identity. A refused receipt is reported; Task owner credentials are never
borrowed. An optional review request carries the exact tag and SHA. Routine
candidates do not wait for a reviewer or require a review Task or verdict.
The single automated qualification is pnpm queue qualify --authorize-candidate-qualification --tasks '<ordered JSON task IDs>' --tester automated-clean-worktree --home <operator Matrix home> --matrix-cli <absolute repository sdk/command-line/bin/matrix.mjs path>.
It verifies that the worker recorded and merged its current origin/main basis,
then checks the exact immutable attempt in a disposable clean worktree after a
frozen install. It records an attempt-specific qualification ref, never moves
main, and needs no reviewer agent. A refusal is attached to the originating Task
and attempt, starts a rework attempt on the same retained native session, and
steers the exact failed command and defect back to that context. It does not
allocate a replacement worker. The source worker must repair, merge current main
again and rerun its full environment before publishing a new attempt tag.
An independent operator runs pnpm queue integrate --authorize-source-integration --tasks '<ordered JSON task IDs>' --agent <integrator> --home <own Matrix home> --matrix-cli <absolute repository sdk/command-line/bin/matrix.mjs path>.
The CLI entry must exist as a file and is executed with the current Node binary;
ambient matrix on PATH is never selected. --home is only a reference to the
operator’s own admitted home; person-session credentials are never supplied.
The command requires a completed current source attempt, matching automated
qualification, unexpired unchanged queue claim and matching attempt tag, then uses the existing
Git integration backend to prove that the exact candidate still contains current
main and fast-forward it using the retained qualification evidence. It does not
rebuild or retest the candidate. If main advanced, the defect returns to the same
source session; the integration owner does not merge or debug it. A durable
Git fence serializes operators. Uncertain publication or completion stays fenced
for explicit reconciliation; rerunning never silently resubmits it. Candidate and
landed SHAs are recorded separately. This source-only command performs no deploy.
matrix invoke smithers queue.dispatch '<json>' accepts:
id: the queue item id.document: the complete markdown item (flat frontmatter plus body).lane: explicitagent(peer name),machine,cwd,reference,branch,model,reasoningEffort,claimAgent,commitName,commitEmail,checkLogandreportPath, all nonempty strings.
From a checkout, pnpm queue dispatch <id> --lane '<json>' reads the item and
calls that operation once. Optional --home and --provider pass to matrix.
The shortcut needs matrix on PATH and a current checkout of the queue item.
It neither allocates a peer nor launches a local coding subprocess.
Smithers preserves the item id as a queue-item reference, its title, its entire
body as the spec, the Done when section as acceptance, and a bulleted Owned paths section as owned-path references. Completed/blocked items, mismatched
ids, missing acceptance and unexpired foreign claims are refused. The supplied
item is a snapshot; the worker still claims/renews against the git-backed queue.
src/actors/FleetWorkOrder.ts is the single source for lane instructions. It
renders checkout, queue lease, affected verification, commit identity, cleanup,
push, reporting and task receipt instructions from the assignment. The selected
installed peer must match both the assignment's agent and machine. Dispatch
asks the durable Task owner to prepare the exact retained lane as that owner's
enrolled unit; the coordinator never receives worker-inbox authority or substitutes
a caller token. The Task owner rejects a different agent, mount, machine, checkout,
queue item, model or reasoning effort before contacting a peer. Ticket dispatches
likewise retain the selected custodian and machine on the Task and refuse target
substitution. A dirty-workspace refusal
creates no attempt. A successful preparation carries the queue item, cwd, model
and effort through task.attempt.start → session.start. Repeating the same
item and assignment reuses the task/attempt; changing admitted content under the
same item id is refused by task operation identity. The normal task.receipt
operation remains an owner operation. A source worker publishes its immutable
attempt tag and returns one bounded CANDIDATE: line in its terminal result;
the Task owner validates the exact item/task/attempt tag and retains the
source-candidate receipt after the attempt ends. Before pushing any code or the
candidate tag, the source worker fetches and merges the latest origin/main, resolves
it locally, and tests the exact merged commit. Review tasks are started only by
an explicit review.request or an admitted risk escalation; they are optional and
never part of routine integration admission. Before publishing its candidate, the
source worker tests the exact committed SHA in its prepared full environment,
building the affected package graph and reusing immutable dependency caches rather
than rebuilding unrelated workspace packages. The automated qualifier provides the
one independent clean-state pass and retains machine evidence for the exact attempt.
Integration consumes that result and checks only immutable identity, current-main
ancestry and publication fencing; it never becomes another test or debugging loop.
Installing the coordinator and dispatching one item
queue.dispatch, fleet.assign, review.request and fleet.work.list are ready only
when exactly one Registry entry supports smithers.fleet-coordinator/v1 in the home.
Install @hivecast/fleet-coordinator on the HiveDock that runs the home's Smithers, the
same way Smithers was installed there; no profile carries either package. Its mount
smithers.fleet-coordinator derives the Task owner smithers.tasks, and its cursor is
that dock's durable record store. From the dock's deployment folder:
hivedock up <checkout>/applications/fleet-coordinator # roll back: hivedock remove @hivecast/fleet-coordinator
A dock whose engine predates the checkout's manifests refuses hivedock up with
Unknown runtime credential capability import; restart that dock's unit so its engine
and runtimes load the current checkout, then read $health on smithers.
Allocation reads smithers.fleet. It joins each durable agents.codex.<name> claim to a
running Host Control runtime: an actor-class row naming that mount, or the runtime the
claim's placement.desiredRuntime names (hivedock:<deployment>/runtime:<runtimeKey>;
a native installation publishes its subtree under installations.<install>.topology).
It asks each peer as Smithers' enrolled unit. A peer that is missing, or listed with
online: false, cannot be dispatched to; its error says why.
On staging the fleet home is demo-hivecast-ai. Smithers and the coordinator run on the
staging-fleet-workers HiveDock (user unit hivedock-staging-fleet-workers-489f57d2 on
hivecast-dev, deployment folder ~/.local/state/hivecast-staging-fleet/deployment,
packages from /home/ubuntu/hivecast-envs/staging); its Codex peer is
agents.codex.hivecast-dev. A staging delivery rebuilds that checkout but restarts
neither this dock's engine nor its runtimes, so restart the unit after a delivery that
changes Smithers, the coordinator or a manifest.
One dispatch from hivecast-dev, as the staging proof home (credentials stay there).
pnpm queue dispatch needs a matrix on PATH that runs the command line, for example
a one-line script that runs node /home/ubuntu/hivecast-envs/staging/sdk/command-line/dist/index.js "$@":
H=~/.hivecast-agent/staging-proof-home
matrix invoke smithers '$health' '{}' --home $H # queue.dispatch READY
matrix invoke smithers smithers.fleet '{}' --home $H # hivecast-dev online
ITEM=<queue item id>; W=~/.local/state/hivecast-staging-fleet/work; Q=$W/queue
LANE=$(node -e 'const [q,i,reference]=process.argv.slice(1);console.log(JSON.stringify({agent:"hivecast-dev",machine:"hivecast-dev",
cwd:`${q}/${i}`,reference,branch:`queue/${i}`,model:"gpt-6.1-sol",reasoningEffort:"medium",
claimAgent:"codex-hivecast-dev-queue",commitName:"HiveCast Fleet Worker (hivecast-dev)",
commitEmail:"fleet-worker@hivecast-dev.local",checkLog:`${q}/${i}.check.log`,reportPath:`${q}/${i}.report.txt`}))' $Q $ITEM $W/source)
pnpm queue dispatch $ITEM --lane "$LANE" --home $H --timeout-ms 180000
If the Task owner retains a typed pre-session workspace-prepare-refused, repair
that exact checkout and explicitly continue the same Task rather than submitting
the queue item again:
matrix invoke smithers queue.continue \
'{"taskId":"<retained-task-id>","refusedOperationId":"fleet-coordinator.dispatch.<retained-task-id>"}' \
--home "$H" --timeout-ms 180000
The original refusal remains immutable. The continuation is admitted only when
the Task still has zero attempts, its payload matches the refused request, and
the linked operation identity is exactly <refusedOperationId>.continue.
Repeating the continuation observes the one retained attempt. A refusal after
session.start may have taken effect and is never retried through this path.
If workspace preparation itself refuses again before an attempt exists, repair
the exact checkout and pass the returned continuation operationId as the next
refusedOperationId. The Task owner retains the original intent fence and the
next operation advances by one .continue suffix; it never replaces the Task.
Command failures also retain a bounded, credential-redacted
workspace-command-failure/v1 diagnostic in the refusal. Inspect its stage, exit or
system code, signal, timeout fact, duration, and output tail before repairing and
continuing; do not infer contention or resubmit the queue item from a generic error.
The reply carries taskId, attemptId and sessionId; worker.status and
session.status on agents.codex.hivecast-dev (with --with-proof) follow the session.
On 2026-10-23 the first staging dispatch stopped before any attempt because the
coordinator tried to publish workspace.prepare directly to the peer while its narrowed
credential imports only smithers.tasks and smithers.fleet. The source contract now
keeps that credential narrow: the coordinator requests task.attempt.start, and the
Task owner validates retained lane or ticket-selection references before using its
existing enrolled-unit worker-control authority for both workspace.prepare and
session.start. The refused staging task c7820614 remains truthful evidence; staging
continues to refuse at the old boundary until this source revision is independently
landed and served.
Selected Fleet route: independent integration
Normal package installations read configuration from their exact installed
Preferences occurrence at activation, including when the composition factory
receives an empty configuration envelope. Configure fleet there, then restart
that occurrence to apply it; the route is restart-only and creates no settings
subscription. Missing fleet leaves execution unconfigured. An unavailable or
mismatched settings owner refuses startup instead of recovering stale launcher
values. Standalone callers without an installed binding still use their explicit
configuration. src/__tests__/installed-configuration.spec.mjs covers this boundary;
the canonical S30 route tests boot through the same installed-settings binding.
Before a new source-writing attempt, the route asks the configured agent mount
for $source and worker.status. Both must identify the configured package;
worker.actorMount must be that exact mount, worker.status must be online,
and worker.capabilities.hasFilesystem, hasShell and hasGit must each be
true. Missing, refused or mismatched evidence stops before task.attempt.start;
the route never selects a substitute worker. A source-only worker is enough:
MCP projection, Docker and a full platform stack are not required. Inspect the
refusal through S30, restore the selected worker's capabilities, and continue the
same ticket. Retained attempts are read using their recorded agent and session
without repeating new-work admission, including while $source or worker status
is unavailable.
The installed fleet.integration configuration names ownerMount (one exact Matrix
actor) and target; timeoutMs bounds an individual request, not the whole delivery.
It replaces the pilot's statusCommand/statusCwd observation-only adapter. Configure
the independent integration actor before enabling this route. The existing home
Capabilities owner must admit its caller; configuration itself grants no authority.
After candidate checks, the Task owner's attempt retains a fleet-integration
artifact reference. Its id is the operation ID; integration.ownerMount and
integration.request retain the selected owner, ticket generation, candidate and
target. Reopening uses those values, even if installation defaults have changed.
The route reads first, submits only when that owner says the operation is absent,
and follows the same operation after a lost reply. fleet.route.run is the
explicit effect boundary: it may continue an exact safely restored delivery, or
recheck a retained INTEGRATION_SOURCE_CHECK_FAILED that occurred before
publication by echoing its exact sourceCheckReceiptRef. The owner revalidates
the ticket candidate and independent grant. Status, S27, reopen projections,
unknown publication/delivery outcomes, other refusals and stale fences remain
observation-only; none starts a replacement execution or an automatic retry.
fleet.route.status reads central Tickets and the exact Task-retained integration
binding on every inspection, including a cold activation. Its ticketStatus and
integration fields are owner facts; execution/session visibility stays with the
person-filtered central Tickets read, never this unit's private view.
running, last and at describe only the
current Smithers activation. In particular, running: false does not say an
independent integration stopped. not-submitted means no binding was retained;
unavailable preserves the read refusal without inferring absence. A missing
receipt never causes submission from status. S30 prints this same read-only
projection; its canonical semantic regression and the port tests cover restored,
refused, unknown and completed operations without extra execution effects.
The independent owner integrates, verifies delivery and closes central Tickets. Smithers only observes the exact matching closure and marks its Task landed. Even an accidentally integration-granted Smithers runtime never self-closes the ticket.
For executable help, open Demos → S27: Follow one Fleet integration in Explorer.
Use the exact owner and operation ID from the attempt's retained artifact; do not
paste credentials. Its canonical program is
applications/demos/src/catalogue/fleet-integration.ts, exercised by the integration
owner's integration-lesson.spec.ts. It reads the receipt and explains the next
action without starting delivery. The installed-route regression is
src/fleet/__tests__/fleet-route.spec.mjs; lost-reply/reopen coverage is
src/fleet/__tests__/fleet-integration-port.spec.mjs. Full ticket-to-completion and
two-improvement acceptance remain C05 requirements, not claims made by S27.
The ticket intake and continuation lesson is S30's canonical source,
applications/demos/src/catalogue/fleet-workflow.ts. Set the exact route owner,
ticket owner and existing ticket ID. To file a new improvement instead, leave the ID
empty, fill its title, statement, admitted program and package, and explicitly
set file-ticket? true. The program identity is scheme-qualified, for example
program:fleet-bootstrap-staging; a plain fleet-bootstrap-staging is refused
by Tickets and S30 shows its safe error/code/field diagnostic. The ordinary central owner returns the new or matched
ticket; retain its ID for reopening. Ordinary intake becomes a missing-capability
case in the caller's own home; inspect the route's eligibility before continuing.
Filing alone never launches an agent. If the
filing reply is lost, inspect Tickets before filing again. It inspects by default; setting
continue-work? to true explicitly asks the admitted route to continue that
same ticket. That same-operation continuation can consume one exact retained
pre-publication source-check failure fence; it cannot retry an uncertain source
publication or delivery. It shows actual recipe, progress and central completion evidence,
never treats an acknowledgement as completion, and creates no polling loop.
fleet-route.spec.mjs executes this same program through the real Task and
integration actors with native worker/Tickets/delivery fixtures. S30 is included
in the built Demos catalogue and marked planned until its installed walkthrough
passes; this is not a claim that live Fleet acceptance is complete. The lesson
uses Omega's ordinary hash-map constructor for nested request data; the facade
regression covers that constructor, not an alternative ticket API.
The three fleet.route operations report readiness from central Tickets, which
they call directly. The optional coordinator-backed dispatch lane is not a
prerequisite for S30. Its own operations retain their provider requirements;
an absent coordinator does not make those operations ready. Inspect per-operation
health rather than treating aggregate package health as every operation's state.
fleet-readiness.spec.mjs checks both missing-provider cases through the actual
Matrix actor readiness implementation.
Retained Fleet attempt recovery
An owner-completed Fleet attempt is not reconstructed from a session status.
After a Task-owner restart, task.attempt.sync asks the exact retained agent
mount for the exact retained session history. A terminal agent.result,
agent.turn-failed or agent.error frame is reconciled through the ordinary
observation path, preserving the original task, attempt, session and worktree.
If the status looks terminal but no matching frame can be read, the result is
attempt-result-unknown; the attempt stays running and no replacement worker,
session or integration operation is launched.
pnpm --dir applications/smithers test:recovery executes the shipped S30
fleetWorkflowProgram across a real SIGKILL/restart boundary using private
NATS and SQLite owners. The retained agent completes while Smithers is absent;
an explicit S30 continuation recovers its history once, retains one candidate,
and advances the same attempt. Inspection and reopen runs remain read-only, and
an unresolved integration effect remains INTEGRATION_OUTCOME_UNKNOWN. This is
isolated native proof for C06; shared-target/browser acceptance still depends on
the accepted C05 route and must not be inferred from the fixture.
Historical Fleet view
The default Fleet tab reuses the workbench's RunnerPanel and history reader.
Each installed peer shows its machine, whether session.list answers, and model
and reasoning defaults from config.get. Only those configuration fields are
forwarded; configuration failures stay visible separately from liveness.
Sessions show status, first prompt line, turns and start time. Selecting one
reads the latest 50 session.history events, displayed newest first; polling
keeps the selection's history current and
ignores replies belonging to an older selection. There is no refresh button.
The Fleet chrome inherits the shell's ui-kit color tokens. Workbench and Tasks
remain available through the same view navigation.
Local verification
From a clean frozen install, retained candidate checks run in this order:
pnpm --filter '@hivecast/smithers^...' build; pnpm -s test:queue;
pnpm --dir applications/smithers test;
pnpm --dir applications/smithers type-check;
pnpm --dir applications/smithers build; git diff --check.
The dependency build supplies package exports before the tests and type-check.
pnpm --dir applications/smithers test runs in-process actor and browser
component specs. pnpm --dir applications/smithers type-check and
pnpm --dir applications/smithers build verify types and runtime/browser bundles.
node --test tools/delivery/work-queue-dispatch.spec.mjs pins the thin shortcut.
No live broker, Docker or environment adoption is needed for these local checks.
New Fleet browser acceptance uses the established Explorer and owner-backed
surfaces; the historical Smithers Fleet tab is not the delivery target.
Workstream metadata may include dependencies, an explicit array of nonempty workstream links.
The Fleet projection retains these coordination references without dispatching or gating peers.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @open-matrix/agents | 1.1.32 |
| @open-matrix/codex-agent | 1.1.32 |
| @open-matrix/contracts | 1.1.32 |
| @open-matrix/conversation | 1.1.32 |
| @open-matrix/omega-core | 1.1.32 |
| @open-matrix/package-runtime | 1.1.32 |
Development Dependencies
| ID | Version |
|---|---|
| @hivecast/demos | 1.1.32 |
| @hivecast/fleet-integration-owner | 1.1.32 |
| @matrix/test-utils | 1.1.32 |
| @open-matrix/core | 1.1.32 |
| @open-matrix/sqlite-store | 1.1.32 |
| esbuild | ^0.25.0 |
| nats | ^2.29.3 |
| tsx | ^4.22.4 |
| typescript | ^5.7.0 |
Peer Dependencies
| ID | Version |
|---|---|
| @open-matrix/core | 1.1.32 |