Tier 2 fuzzing: a nightly cargo-fuzz crate at crates/heph-core/fuzz/ with
three targets (crdt_merge, crdt_write, extract), reaching crate-private CRDT
internals through heph-core's new 'fuzzing' feature. Driven ad-hoc via
'mise run fuzz'; not in CI (needs nightly + wall clock).
crdt_merge immediately surfaced robustness gaps in yrs 0.27 on malformed sync
deltas (a 4-byte input OOMs; other inputs abort/UB) — uncatchable, limited
blast radius (authenticated /sync/push), documented as a known limitation.
extract and crdt_write ran clean over ~1M cases.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Tier 1 fuzzing: proptest properties across extract, wikilink, crdt,
frontmatter, recurrence, hlc, datespec, and quickadd — they run with the
normal cargo test suite. Fuzzing surfaced and this fixes:
- parse_offset overflowing chrono date arithmetic on huge offsets (panic)
- parse_month_day slicing a multibyte token on a non-char boundary (panic)
Also hardens crdt::merge_body against malformed sync deltas with catch_unwind
(partial: yrs 0.27 can still SIGABRT/UB on some inputs — tracked separately).
Fixes the extract nested-checkbox alignment so context_item_lines stays 1:1.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A hand-made `wiki` link row looked like it worked, then silently
vanished on the next body write — the links table's wiki rows are an
index derived from `[[…]]` in the body, and `sync_wiki_links` diffs
them against it. Store::add_link now rejects `wiki` (with a pointer at
the body as the durable path) plus the `canonical-context` / `log-of`
task internals. Body materialization uses the internal path and is
unaffected; `link.add` ops arriving over sync still apply.
Drops the wiki-links explanation card — it existed to document the
footgun, and the footgun is gone.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A fresh hub started with an existing device's owner id rebuilds itself
entirely from that spoke's first full op-log push: no snapshot copy and
no origin reset (the new store mints its own). adopt_owner is idempotent
once adopted, so the flag is safe baked into a service unit.
[[set-up-sync-hub]] documents the recipe and drops the manual-seeding gap.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Docs-first commit for the feature/task-sweep branch, which addresses the
bulk of the outstanding Hephaestus-project tasks in one sweep. The
fragments describe the intended end state; code follows.
Also delivers the "understand heph link wiki semantics" task outright:
the new [[wiki-links]] explanation card documents body-vs-links-table
layering, the manual-wiki-link reconciliation footgun, resolution tiers,
and per-client surfaces.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The CLI's attention flag (on task/list/attention/edit/promote) now takes the
a1–a4 labels, a bare digit 1–4, or a colour word, normalizing to the storage
colour before the RPC. Adds Attention::parse_input() in heph-core (lenient
human input) alongside the strict storage parse(), with a clear error listing
the accepted forms. `heph attention` now echoes the band as `a1 (red)`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Retire the `A` attention cycle and the duplicate `b` push-to-blue gesture
in heph-tui. Attention is now picked directly: press `a` then `1`–`4`
(a1=red, a2=orange, a3=white, a4=blue, ordered by intensity). Cycling past
blue used to make a task vanish from the current view with no way back —
direct selection never does. Quick-add moves from `a` to `n`.
Surface the a1–a4 nomenclature everywhere instead of colour words or the
old p1–p4 priorities: heph-tui status/legend, the heph-quickadd chip + hint,
and the PWA chip/hint plus a new band-picker (replacing its cycle button).
The shared quick-add parser now accepts `a1`–`a4` (a1=red … a4=blue) and no
longer recognizes `p1`–`p4`. Colour mappings are unchanged; only the words.
Add Attention::ui_label() in heph-core so both Rust surfaces share the
mapping; bump the PWA service-worker cache; update the PWA how-to.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The global ⌘' quick-add overlay is a borderless, transparent, always-on-top
accessory window that winit hides with `Visible(false)`. That orders the window
out visually but leaves heph-quickadd the *active* application — so after a
capture (or Esc / toggle) keyboard focus never returns to the app the user was
in, and the lingering overlay can keep intercepting clicks where it used to sit.
Hide at the application level instead via `NSApplication.hide:`, which fully
orders our windows out and activates the next app in line (the previously
focused one). On re-show, `unhide:` clears that hidden flag before the existing
viewport `Focus` command makes the field key again. Both are macOS-only no-ops
elsewhere, wired through new `app_yield_focus`/`app_take_focus` helpers backed by
objc2 / objc2-app-kit (unified to the 0.6/0.3 line global-hotkey already pulls).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`Client` connected to the unix socket once and never reconnected, so after an
opt-in self-update or `heph daemon restart` dropped the socket, every later
`call()` failed — `heph-tui` would sit on errors until relaunched (and the work
we just shipped makes restarts more frequent).
`Client` now stores the socket path and reconnects on a dropped connection,
classifying the failure to stay safe:
- write-side failure (request never reached the daemon) → reconnect + retry once;
- reply lost after sending (daemon closed mid-request) → reconnect for next time
but surface this one, so a mutation is never silently double-applied;
- genuine RPC errors are passed through untouched.
heph-tui and the CLI use `Client` unchanged, so the TUI self-heals on its next
refresh tick. Adds an integration test driving a mock daemon that drops the
connection after each request.
Closes the "heph-tui: reconnect on a dropped daemon socket" backlog task.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The spoke OAuth path funneled every failure into one `AuthError::Provider`
whose Display was hardcoded "identity provider unreachable". So a reachable IdP
returning `400 invalid_grant` on a refresh was reported as "unreachable",
misdirecting incident response toward the network when the fix is re-auth. The
real refresh cause was also swallowed — `bearer()` logged it and returned None,
so sync health only ever showed the downstream 401 on /sync/pull.
Wording fix (auth.rs / oauth.rs):
- Split AuthError into Unreachable (transport), Rejected (IdP returned an HTTP
error — carries the RFC 6749 §5.2 error/error_description), and Other
(keyring / malformed response, previously mislabeled too).
- refresh()/discover()/start()/poll() classify transport vs status; refresh
reads the OAuth error body on a non-2xx.
- Hub-side token verify maps IdP-infra failures → 503, token failures → 401.
Recovery UX (server.rs / heph / heph-tui):
- bearer() returns Result; the sync paths record the real acquisition failure
(with a re-login hint when it's a rejection) instead of a masked 401.
- sync health's last_error carries the exact `heph auth login --hub-url …
--issuer … --client-id …` command (keyed to the configured hub); sync.status
also returns issuer/client_id + the command.
- New `heph auth status` prints auth health and the re-login command.
- heph-tui's auth chip points at it: `⚠ auth · heph auth status`.
Closes the duplicate "misleading identity provider unreachable" tasks and the
"actionable re-auth guidance" task. Also corrects a now-stale set-up-sync-hub
gap note (daemon config baking landed in the prior PR).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`restart` bootstrapped immediately after `bootout`, but `launchctl bootout` is
asynchronous: launchd may still be killing/reaping the job and removing its
label when the command returns. Bootstrapping into that transitional domain
fails with a generic `5: Input/output error`, intermittently — the odds depend
on how fast hephd (sync client + SQLite + a heph-quickadd child) shuts down.
- Wait for the label to actually clear (poll `launchctl print`, bounded) before
re-bootstrapping, and retry the bootstrap to cover the residual settle window.
- When the plist is unchanged (the common binary-upgrade restart), use
`launchctl kickstart -k` to restart the loaded job atomically — no
bootout/bootstrap, no race. The full reload path is reserved for genuine
config changes, where launchd must re-read the plist.
Start's bootstrap shares the same retry helper.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`heph daemon start`/`restart` previously hardcoded `hephd --mode local` and
only wired the bare `--self-update` bool — the poll interval and all spoke/hub
sync config (`--hub-url`, `--http-addr`, `--oidc-*`) could not be set on the
managed service without hand-editing the plist/unit (which a later
start/restart would clobber).
Generate the hephd arg vector from a DaemonConfig and add the corresponding
`heph daemon start/restart` flags: --mode, --hub-url, --http-addr,
--oidc-issuer, --oidc-audience, --oidc-client-id, and
--self-update-interval-secs. Regenerating now reads the existing service file
and preserves any flags not passed (start as well as restart), so a bare
invocation never silently drops baked config.
Closes the "pass through --self-update-interval-secs" and "bake hub/spoke
config into the generated service" backlog tasks.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The background sync loop runs every 30s, so the last-sync age never crossed
the 60s 'just now' threshold — the chip always read 'just now', which also
masked the first missed sync (age 30-60s looked identical to a fresh one).
Show seconds under a minute ('⟳ 26s') so the chip is a visible heartbeat and a
stalled sync surfaces ~30s sooner.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A spoke could be silently failing to sync (expired token → 401, or hub
unreachable) with the only signal buried in the daemon log. Now:
- hephd tracks SyncHealth (last attempt/success time, last error, auth-failure
flag) from the background sync loop and sync.now, classifying a 401 as an auth
failure. sync.status returns it plus the pending merge-conflict count.
- heph-tui shows a live status-line indicator (spoke only): '⟳ <age>' since the
last good sync, red '⚠ auth' when re-login is needed, '⚠ offline' when the hub
is unreachable, and '⚠ N conflicts' when conflicts are pending. The event loop
polls on a 2s tick so the age advances and failures appear while idle.
- docs: recommended Authentik access/refresh token validity to stop frequent
re-logins (with the iOS PWA localStorage-eviction caveat).
Closes the 'Add hub connection status to heph-tui' and 'Spoke sync health:
surface unhealthy state instead of silent 401 spam' backlog items.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bundles the cosmetic/UI-polish backlog for the agenda surfaces. All read-side;
no schema or sync change (see hub-spoke-data-evolution).
- humanize_rrule (hephd::datespec): inverse of parse_recurrence — renders an
RRULE as 'every other week', 'weekdays', 'yearly on Apr 15', etc.; falls back
to the raw rule for unmodeled parts (COUNT/UNTIL/ordinal BYDAY). Mirrored in
the PWA's datespec.js. Shown in the TUI recurs detail line and PWA task/qa
previews instead of the raw FREQ= string.
- project.overview RPC + Store::project_overview: each project's parent (via the
existing 'parent' links) and direct outstanding-task count, a read-only query.
- TUI sidebar: subprojects indented by depth, per-project counts, wider pane,
and ListState + scrollbar so it scrolls instead of clipping on overflow.
Tests: humanize parity (Rust + JS), round-trip through parse_recurrence,
raw-passthrough; project_overview count/parent; sidebar tree ordering + cycle
safety.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document why heph's op-based sync lets most new features (new link types,
read-side queries, optional payload fields) ship without a coordinated
migration across the hub and spokes, and the narrow case — a new required
SQLite column the apply path writes — that does need a hub-first rollout.
Groundwork for the indented/counted project sidebar, which is pure read-side
(existing parent links + a GROUP BY) and needs no migration.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document the PKCE 'Login with Authentik' flow, the hub /config zero-config
discovery, and the redirect-URI prerequisite on the Authentik heph provider.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add host-heph-pwa.md: a deployment how-to for serving the PWA from the canonical
hub in the hub/spoke OIDC setup (post-release) — fetch the shell at the hub's
tag, add --web-root, terminate TLS (tailscale serve / reverse proxy), and the
token-paste caveat with the device-code-login follow-up. Cross-linked from
heph-pwa and the how-to index.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document serving the app from the hub (--web-root), connecting (hub URL +
optional token), quick-add syntax, voice, triage, and the deliberate
design choices (PWA over native iOS; online-only; token paste vs device flow)
with their known limitations to revisit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
hephd's reqwest client is built default-features=false with no TLS
feature, so the self-update release poll's HTTPS GET always failed
('release check failed: requesting forge releases/latest') — the bug
never surfaced before because nothing in production used reqwest over
HTTPS (hub sync is plain http://). Switch the poll to ureq, which is
already a dependency and ships a rustls/ring TLS stack needing no system
libs (notably no cmake/aws-lc-sys, which would break the rust:bookworm CI
image). Verified end-to-end: a 0.0.0 build now detects v1.1.0, installs,
and restarts.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Collapse the eight Mikado scaffolding cards (+ goal card) into one
user-facing how-to, docs/how-to/self-update.md: what self-update is and
how to enable it. The per-card breakdown was build-time scaffolding, not
documentation. Keeps the changelog fragment; updates the how-to index.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Public repo => anonymous HTTPS clone, no credentials (the SSH/canonical
premise was wrong: that was the access-restricted cargo registry, not git
clone). Install URL points at the canonical public host (verified end to
end); the service template bakes cargo onto PATH. Card rewritten to
reflect what actually happened.
The repo is public, so self-update needs no credentials: cargo install
--git is a plain anonymous clone (NOT the access-restricted Forgejo cargo
registry, which is what required forge.ops.eblu.me). Point INSTALL_GIT_URL
and the releases poll at the canonical public host over HTTPS — verified
end-to-end (cargo install --git https://forge.eblu.me/... --tag v1.0.3
builds a working hephd with zero auth).
Make the headless service able to run the apply path: 'heph daemon
start --self-update' (default off) generates a launchd/systemd service
that passes --self-update and bakes a PATH (incl ~/.cargo/bin) + HOME so
the minimal service env can find cargo. restart preserves the setting.
Default (no flag) services are byte-identical to before. Template + URL
behavior covered by unit tests.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Restarter + ProcessRestarter wired: install then exit(0) so the service
manager respawns the new binary; restart only on a successful install.
Unit-tested via injection.
Installer trait + CargoInstaller + apply_update landed and unit-tested
via injection. Real cargo execution is gated on the deployment env
(service-env-forge-access).
Self-restart works by exiting cleanly and letting the service manager
respawn the new binary. launchd already does this (KeepAlive=true), but
the systemd user unit was Restart=on-failure, which ignores a clean
exit (code 0). Switch to Restart=always + RestartSec=1, update the unit
test, and note in run-the-daemon that existing Linux installs must
`heph daemon restart` once to regenerate the unit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kick off the C2 Mikado chain for an opt-in (default-off) hephd
self-update mode (forge-poll -> cargo install from tag -> self-restart).
Goal card plus eight prerequisite cards, indexed from how-to.md:
release-poll-version-check, self-update-opt-in-flag (leaves)
-> self-update-poll-loop (notify-only core)
service-env-forge-access (leaf, the cargo/forge blocker)
+ self-update-poll-loop -> cargo-install-from-tag
service-respawn-on-clean-exit (leaf, systemd Restart=always)
+ cargo-install-from-tag -> self-restart-after-update
verify-hub-dropout-resilience (leaf, lock in the base-case guarantee)
Grounded in research of hephd's sync loop, daemon lifecycle, the
launchd/systemd service templates, and the forge releases API.
Captured from Hephaestus task 01KTA2NSNRYT902HC3VRW00S1J.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The cargo-fmt failure on this PR slipped to CI because the pre-commit
prek hooks were never installed in the working clone. The existing
cargo-fmt hook reformats in place but only when it runs. Add a
pre-push cargo-fmt-check hook (`cargo fmt --all --check`) that mirrors
CI's Dagger `check` step exactly, so an unformatted commit is blocked
locally before it can reach the runner — even if the pre-commit hook was
skipped or not installed. Filtered to .rs pushes so Rust-free pushes pay
nothing.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
RPC clients (the hephaestus.nvim plugin, for its `:Heph version`
command) had no way to learn which hephd they are talking to — `health`
returns counts, not a version. Add a tiny `version` method returning
`{ version: heph_core::VERSION }`, the same `X.Y.Z (sha)` string the
binaries print for --version. No store access needed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Editing a task's canonical-context doc body previously meant looking up
its `canonical_context_id` (e.g. via `heph list --json`) and then
`heph node update <doc-id> --body`. Add a `heph context <task-id>`
command that resolves the canonical-context doc from the task's outgoing
links and:
* prints the body with no flag,
* `--body <text>` replaces it (`-` reads stdin, matching `node update`),
* `--append <text>` adds a blank-line-separated paragraph.
Errors clearly when the id has no canonical-context doc (e.g. a plain
doc node rather than a task). Purely a client-side CLI convenience — no
new RPC.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The `--project <name>` argument matched titles case-sensitively and
exactly, so `--project hephaestus` or `--project heph` failed against a
`Hephaestus` project. Make project-name resolution forgiving but
deterministic, via a tiered match in `resolve_project_id`:
1. exact (case-sensitive) — the historical behavior; always wins
2. case-insensitive exact — only when unambiguous
3. case-insensitive prefix — only when unambiguous
Ambiguous fuzzy matches resolve to None (callers report "no project
named X") rather than silently picking one. This single resolver already
backed `heph list --project` (via project_scope); route the CLI's
task/edit/promote/parent path through it too with a new `project.resolve`
RPC + `Store::resolve_project`, so every `--project` surface behaves the
same.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
heph-tui was the one daily-driver binary that did not answer --version.
Add the same clap `version = heph_core::VERSION` attribute that heph and
hephd already carry, so all three report `X.Y.Z (sha)` consistently.
Addresses the heph-tui half of the cross-binary --version task.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
