Weft Status

Weft Status is a macOS menu bar companion for Weft. It displays current job, rental, and autopilot activity from Weft's local daemon subscription API. Weft remains the source of truth for job and instance state.

Screenshots

Requirements

• macOS 14 or later.
• A running Weft daemon. The app connects to ~/.cache/weft/daemon.sock, and says how to start the daemon when that socket is missing.
• A daemon activity event may be up to 64 MiB. Larger events produce an explicit error instead of allowing the app's receive buffer to grow without bound.
• The weft executable. Row commands and the provider credit balance run it directly, looking on PATH and then in the usual install locations, since an app launched from Finder inherits a minimal PATH.
• Spend against target needs a Weft whose daemon reports budget_usd_per_hour. Earlier daemons always send zero, and the app then shows the run rate with no target beside it.
• Structured autopilot give-up detection needs a Weft whose daemon reports runaway_breakers. Older daemons that omit that field do not expose reliable give-up state to the app.

Using It

The app lives in the menu bar and has no Dock icon. Clicking the menu bar label opens the popover, which carries the signal that most needs attention, the jobs and rentals behind it, and menu items for opening the HUD, Settings, About, and Quit.

Control-Option-H opens and closes the floating HUD, and the popover's Open HUD item does the same thing. The hotkey is configurable, and can be turned off; the menu item shows whichever shortcut is currently set. Settings and Quit take the usual Command-comma and Command-Q.

Features

• The menu bar label shows nonzero running, queued, placement, blocked, results, and run-rate metrics. Its leading icon follows the highest-priority current signal.
• Alerts identify stopped work, warnings identify impeded work, and attention identifies unprocessed results. Routine job failures stay informational by default and can be promoted to alerts in Settings.
• Placement is informational until its configurable blocked threshold, which defaults to one hour.
• The popover leads with the highest-priority signal, then shows the job and rental detail behind it. Project names and status badges open the matching Project or Status section in the HUD.
• The HUD is ordered as alerts when present, system status with active rentals, projects, jobs, then activity. Activity combines app commands and changes observed through Weft's daemon subscription in one chronological stream, labeled with their provenance when it is available.
• Job rows carry the daemon's own diagnosis. A job that cannot be placed says why, and a failed job shows its exit code and suggested next step.
• Queued and unplaced job rows have a Diagnose control. It runs weft diagnose job on demand and shows the exact live offer search plus GPU-class-scoped counterfactuals in a dismissible HUD card.
• Rental rows show provider, GPU, cost, uptime, job counts, and lifecycle state. An instance winding down through its grace period reads as such, with its deadline.
• Row controls copy job and instance IDs, move queued work to new instances, kill running jobs, and terminate rentals. Kill and terminate take effect immediately and cannot be undone from the app. Confirmation is available in Settings and is off by default.
• The HUD keeps the 50 most recent commands the app has run, including each target, duration, outcome, the control that started it, and the full weft output when a command fails. Read-only diagnosis commands are recorded too. All 50 are visible, and the bounded record survives a restart.
• Completed and failed jobs stay visible while their results need attention.

On-prem hosts can run jobs without appearing in the rental section. The rental section describes cloud/rental launch records only.

Architecture

flowchart LR
    daemon["Weft daemon<br/>activity subscription"] --> models["Normalized app models<br/>Shared/"]
    models --> surfaces["Menu bar, popover, HUD"]
    surfaces -- "commands, diagnosis, credit balance" --> cli["weft executable"]

Loading

The app reads over one channel and writes over another. Everything it displays comes from a subscription to Weft's activity resource on ~/.cache/weft/daemon.sock, and code in Shared/ normalizes that payload into app models before any SwiftUI surface renders it. There is no bridge process — see docs/decisions/0001.

Row commands run the weft executable instead, because the daemon socket exposes no kill, terminate, move, or live counterfactual-diagnosis operation. The provider credit balance behind the runway alerts comes from weft budget, polled every five minutes. That poll is a live provider API call.

The app never opens ~/.config/weft/jobs.db. SQLite is an internal Weft implementation detail. Data the daemon does not supply appears as a loading, stale, disconnected, or error state rather than as live-looking counts.

Repository Layout

The app is a SwiftPM project:

• Shared/: app-facing models, payload normalization, freshness rules, priority signal selection, the action record, and fixture data. Imports nothing beyond Foundation and CoreGraphics so the check executables can link it.
• DaemonTransport/: the Unix-socket transport and bounded frame reader.
• DaemonClient/: the Weft daemon activity subscription client.
• CommandSupport/: the weft command client with bounded output and deadlines.
• AppModel/: the view model connecting the subscription, commands, and the retained action history.
• WeftStatusApp/: SwiftUI surfaces, settings, notifications, and the documentation screenshot renderer.
• App/: macOS app bundle metadata and icon source.
• Checks/: executable model checks that run without XCTest.
• specs/: the Allium lifecycle specification validated by just check-specs.
• docs/decisions/: decision records for choices a future contributor should not undo by mistake.

Development

Build the app:

swift build

Run from SwiftPM:

swift run WeftStatus

Open the HUD with example activity:

swift run WeftStatus --fixtures --hud

Open Settings with example activity:

swift run WeftStatus --fixtures --settings

Regenerate the README screenshots:

swift run WeftStatus --capture-screenshots docs/images

Add --dark for Dark Mode or --fixture-state connected|stale|disconnected|error|loading to render a specific connection presentation.

Render the complete light/dark connection-state matrix:

swift run WeftStatus --capture-accessibility-matrix /tmp/weft-status-ui-matrix

Build the macOS app bundle:

just app

Install the bundle in ~/Applications and launch it:

just install

The installer stops a running copy before replacing it. Local installs are unsigned by default. Use just install-signed to add and verify an ad hoc signature. just launch is the same as just install.

Run the model checks and build:

just check

This development check requires allium and jq on PATH, in addition to the Swift toolchain.

Use swift run WeftStatusSharedChecks to run only the model checks, or swift run WeftStatusCommandChecks to run the bounded subprocess output and deadline checks. Use just check-live-daemon to run the bounded integration checks against the currently running local Weft daemon as well as the scripted socket scenarios.

Settings

Settings open in a separate window from the menu bar popover:

• Menu bar identity: icon, name, or both.
• Menu bar status: abbreviated labels, words, or icons. The leading icon follows severity automatically.
• HUD hotkey and default HUD job grouping.
• Whether kill and terminate ask for confirmation naming the target. This is off by default. Move commands never ask.
• Whether job failures raise the alert tier. This is off by default and does not disable infrastructure alerts.
• Infrastructure warning thresholds for low credit runway and overnight runway.