OpenWorkspace keeps canonical pointers to where a project's information lives. Every project declares an information map — the home of its tasks/backlog, decisions, knowledge (wiki), plans and coordination channel, plus any extras (credentials vault, data stores, …) — and OpenWorkspace renders it into a generated "Where information lives" section of the project's README.md and AGENTS.md, keeps it current, and has projects doctor check it. A home can be an external system (GitHub Issues, Teamwork, a wiki URL, a Slack channel, a repo path) or one of OpenWorkspace's own native stores — plain Markdown/TOML files under _project/, chosen à la carte per primitive (use the native wiki and task tracker but your own decision log, say). Nothing is scaffolded empty. Underneath is the substrate for a plain-filesystem workspace: projects are directories marked by _project/id — or, for a map-only project with no native store, by the machine-readable information-map block in its README.md/AGENTS.md (decision-3) — and every view is computed from the live tree on demand — no registry, no manifests, no hidden database. It is built for one human plus many AI agents (including agents in git worktrees) writing concurrently over iCloud and git, safe by construction: atomic writes, machine-local ID minting locks, one-immutable-file-per-message coordination. The spec of record is the PRD at ~/Documents/Personal OS/_project/wiki/OPENWORKSPACE_PRD.md — where this README and the PRD disagree, the PRD wins (the information-map reorientation is recorded in this repo's _project/decisions/decision-2 and amends the PRD's §4.3 skeleton and Appendix A; see PRD §15; map-only projects, which keep no _project/ folder at all, are decision-3, amending decision-2).
This repo is itself a tracked OpenWorkspace node. It carries its own
_project/(runprojectsfrom within this directory to see its tasks/decisions), and it is owned (kind = code) by the Personal OS project in~/Documentsvia a project-graph[[owns]]edge. It lives at~/Code/openworkspace— outside the iCloud-synced~/Documents— perdecision-3(git repos must not live in iCloud); it moved there whole (tracker included) from~/Documents/Personal OS/openworkspaceon 2026-09-29, and the workspace discovers it through[projects] external_roots(below). The design/spec docs (OPENWORKSPACE_PRD.md,PROJECT_GRAPH.md,CODE_PROJECTS.md) stay in Personal OS's wiki, not in this repo.
npm install
npm run build # tsc → dist/, then build:client (vite build in src/dashboard/client),
# then copies the client's single-file dist/index.html to dist/src/dashboard/index.html
npm link # puts `projects` on PATH (bin → dist/src/cli.js)
# or run directly: node dist/src/cli.js <command>Node ≥ 20. Runtime dependencies: yaml and smol-toml only. The dashboard client (src/dashboard/client/) is its own npm package with its own node_modules (React, Vite, vite-plugin-singlefile) — npm install at the root does not reach it; npm run build does, via build:client.
Start with projects task list --json in this repo, then read the relevant
design note in _project/wiki/ for the current arc. For automation-runtime
work, read _project/wiki/automation-runtime-v2-design.md, then run
npm test and projects doctor. For Mini rollout/remediation, check
task-3/task-4 first and do not deploy into the separate Mini checkout until
its dirty worktree has been reconciled.
# <project>/_project/project.toml
[map]
wiki = "native" # shorthand: native | none | <url> | <path>
forum = "none"
# render_to = ["README.md", "AGENTS.md"] # the default targets
[map.tasks] # an external pointer: system + url/locator/path
system = "GitHub Issues"
url = "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/acme/widget/issues"
locator = "acme/widget"
[map.decisions]
path = "docs/decisions" # a path in this repo (or ~/…, or absolute)
[map.credentials] # any other key is a free-form extra
system = "1Password"
locator = "vault Acme"projects map set|unset edit it (preserving lifecycle/[[owns]] and every other key) and re-render the marker-delimited <!-- BEGIN openworkspace:information-map … --> block in README.md/AGENTS.md — idempotent, byte-identical on an unchanged map, and the hand-written text around the block is never touched. projects map show prints it with each native store's state; projects show and home scan --json (and the dashboard's project cards) carry it too.
- Native stores are opt-in per primitive (
projects init|new --native tasks,wikior--native all, orprojects map set wiki native). A store is created by its first write. With no native store requested,init/newmake a map-only project (no_project/folder — see below); with one (or--folder/--no-docs),initcreates only_project/id, the orientationREADME.md,.gitignoreandproject.toml. - A primitive homed elsewhere redirects. Reads (
task list,decision list,forum list|who|inbox,plan show) print the pointer (on stderr under--json, so stdout's JSON shape is unchanged) and list any native records still awaiting migration; creates (task create,decision new,forum open|post,plan open) exit 3 with the pointer and write nothing;forum announce|departare quiet no-ops. Mutating an existing native record is never blocked, so a half-migrated store stays drainable. No integrations: OpenWorkspace says where; it does not proxy. - Undeclared primitives still write natively (a stderr note asks you to declare them) — scripts that
projects initand thentask createkeep working. - Legacy projects (no
[map]) behave exactly as before: every primitive native, no new errors or warnings — doctor adds one info-level note (aggregated into a single line byhome doctor).projects map adopt(dry-run;--apply;--prune-emptyremoves stores holding only the old empty skeleton) declares a map from the stores actually in use. projects doctor(map mode) checks: every core primitive has a declared home (an undeclared one, or one only inferred from an existing store, warns); no native store sits empty; a primitive homed elsewhere has no records left in its native store; pointers look resolvable (local paths exist, URLs well-formed — no network); the README/AGENTS sections exist and match the map. A malformed map entry is an error.
A project whose primitives are all external or none needs no _project/ folder: its map is the "Where information lives" block. projects init|new without --native (and without --folder/--no-docs) creates exactly that — no _project/, just README.md/AGENTS.md carrying a block whose BEGIN marker has the map-only flavor and which embeds the declared document as fenced TOML:
<!-- BEGIN openworkspace:information-map map-only (this block is the project's information map and its source of truth: …) -->
## Where information lives
- **Tasks & backlog:** Teamwork — <https://…>
…
```toml
format = "openworkspace-map/1"
uid = "58e91bd3-ab03-4c68-8aea-7ef5c8382113" # the project's identity (what _project/id is for a folder project)
[map]
decisions = "none"
[map.tasks]
system = "Teamwork"
url = "https://…"
```
<!-- END openworkspace:information-map -->- Source of truth. The first of
README.md,AGENTS.mdcarrying a valid block is the source; the other is a rendered copy kept in step by every write.map set|unset,lifecycle, andownsedit the embedded TOML in place; hand edits to the TOML are fine — runprojects map renderto refresh the human lines. ACLAUDE.md → AGENTS.mdsymlink is written through, never replaced. - Discovery is strict (no false positives): only
README.md/AGENTS.mdat the directory itself are read; the BEGIN/END lines must sit at column 0 outside any fenced code block; the BEGIN line must carrymap-only; the block must hold a fenced TOML withformat = "openworkspace-map/1"and a UUIDuid. A doc that merely describes the format (like this one) is not a project._project/idwins when both exist. A TOML typo keeps the project discoverable (uid by line scan) and is a doctor error; writes refuse until it is fixed. _project/appears only when a native store is enabled.projects map set <prim> native, or the first native write (task createon an undeclared primitive,decision new,forum open|post), creates_project/with the same uid and moves the map intoproject.tomlverbatim (the doc block reverts to the generated folder flavor). Presence verbs (forum announce|depart) and reads never conjure the folder.projects map adoptconverts both ways.--map-only [--apply]movesproject.toml(map,lifecycle,[[owns]]) and the uid into the block and removes_project/— only when nothing but the tool's stamps and empty stores remain and no primitive is declarednative(otherwise it lists the blockers and exits 1).--folder [--apply]is the reverse. Plainmap adopton a folder project that is eligible says so.- Everything else handles both forms:
doctor(a map-only project gets the map checks plus its own invariants: no declared-native home, no stray_project/without an id),home list(taggedmap-only),home doctor,home scan --jsonand the dashboard (form: "folder" | "map-only"), lifecycle reconcile (the committed block is the tier-1 evidence). Existing_project/projects are unchanged.
projects home init mark the current directory as a workspace (.openworkspace/)
projects home list [--all] live-scan projects (--all includes the Dormant/Archives shelves)
projects home scan full scan: projects, tasks, attention counts
projects home doctor workspace + all-projects invariant checks
projects home mint-suffix [<sfx>|--clear] this machine's ID suffix (PRD §4.4 — set "mini" on the Mini)
projects home runner-node [<path>|--clear] this machine's granted runner node binary (decision-1, §7.4)
projects home machine-id [<name>] show or set this machine's id — the value automation
manifests' runs_on = [...] (or legacy machines = [...])
declarations are matched
against; setting renames the synced registry file
projects init [<path>] | new "Name" stamp _project/ (id, README, .gitignore, project.toml with the [map])
[--native tasks,wiki|all] and render the map into README.md/AGENTS.md (--no-docs skips);
[--home key=<url|path|none>] no native store is pre-created. init without a path initializes the
[--no-docs] cwd (refuses outside a workspace, at the workspace root, or a shelf root)
projects map show · set <key> [native|none|<url>|<path>] [--system --url --locator --path --note --label]
unset <key> · render [--dry-run] · adopt [--apply] [--prune-empty]
projects show · doctor · rename · move · lifecycle <ref> --to <active|dormant|archived>
projects reconcile [--all] [--apply] [--auto] heal location⟷metadata drift (decision-2: metadata-as-truth)
[--revert <ref>] [--adopt-location <ref>] human tiebreak for ambiguous drift
projects task create "title" [--parent 36] [--quadrant q2] [--hidden-until DATE] [--recur weekly]
projects task list [--subtasks] [--hidden] [--all] · show · edit · note · archive
projects task status <id> <todo|doing|waiting|review|done> [--force]
projects task done <id> on a recurring task: completes the occurrence
projects task hide <id> --until DATE · recur <id> <interval|off>
projects decision new "title" · accept · list · show · supersede <id> --by <id>
projects plan show · open
projects forum announce · depart · who · open · post · show · list · inbox · resolve · archive
projects forum sweep retention: remove own-machine stale presence, propose thread archives
projects automation apply [<name>|--all] · deactivate · list [--all] · status · supervise
supervisor apply|status|deactivate · prune · logs · run-now
projects import legacy [--dry-run|--apply] [<project-ref>|--all] migrate legacy _tasks/reminders/dirchannels
projects skills sync [--dry-run|--apply] [--json] aggregate every project's Skills/ into <ws>/.agents/skills/ and install for the runtimes
projects dashboard dev | open [--port N] [--host H] [--allow-host H]... [--cache-ttl MS] [--config <path>] read-only dashboard (localhost-only by default; Host-header-validated; scan cache off by default)
Every read takes --json; every project-scoped verb takes --project <ref> (path, workspace-relative path, unique name, or UID; default = walk-up from cwd). Exit codes: 0 ok, 1 error, 2 canonical-resolution failure (a forum/coordination verb could not resolve the project's canonical checkout — never silently degraded), 3 the primitive's home is elsewhere per the information map (nothing written; the message says where).
Two write postures (PRD §6.3): records ride the branch (task/decision/plan/wiki writes are worktree-local and merge with your code), while coordination rides the machine (forum and presence verbs always resolve to the project's canonical checkout by UID, so agents in different worktrees see each other immediately).
Lifecycle is metadata-as-truth (decision-2). A project's lifecycle lives in its _project/project.toml lifecycle field (active|dormant|archived; absent ⇒ active — Matteo dropped the ongoing state 2026-06-11: an "ongoing" project is just an active one he never archives, and the active-project cap is C3's concern, not the tool's); the project's location (top-level vs Dormant Projects/ vs Archives/) is a derived, reconciled view of that field, maintained for Finder legibility. projects lifecycle <ref> --to X is metadata-primary: it writes the field (and a machine-local intent record) and then moves the folder to match. This survives iCloud sync, which has no tombstone-honest delete model and can spuriously resurrect a delete or revert a move: such a location change is now cosmetic drift a projects reconcile pass heals, not state corruption. The drag-vs-glitch tiebreaker (a human Finder-drag and an iCloud glitch are the same observable event, opposite responses) is resolved by, in order: committed git (git show HEAD:project.toml where a project is a repo — iCloud can't author a commit), then a machine-local append-only intent-log in ~/Library/Application Support/OpenWorkspace/ (outside iCloud's reach), then — when neither proves intent — propose-only: reconcile surfaces both fix commands and never guesses, so it can undo a glitch but never silently overrule a human. Reconcile also heals the iCloud record-corruption shapes: same-ID duplicates (task-50 - x 2.md, archived reversibly to _project/archive/reconcile/) and resurrected state-named subdirs (tasks/todo/ — rehomed flat, tasks/archive/ whitelisted). --apply executes the plan except ambiguous rows; --auto (the Mini's mode) restricts to the glitch-certain class. git is NOT the sync and NOT the source of truth — iCloud stays the universal file sync; git is optional, per-project version control.
External project roots ([projects] external_roots). A project does not have to live inside the workspace tree. A git repo that is itself an OpenWorkspace project (it commits its own _project/) belongs outside iCloud — e.g. under ~/Code — and moves there whole, tracker included. List such roots in the workspace config:
# <workspace>/.openworkspace/config.toml
[projects]
external_roots = ["~/Code/openworkspace", "~/Code/some-folder-of-repos"]Each entry is a path: ~ / ~/… expands to the home dir, a relative path resolves against the workspace root, and entries are deduped. An entry may be a project itself or a plain folder holding projects; either way it is walked exactly like the tree (nested projects are found, discovery.ignore applies, foreign git checkouts are not descended). Everything that uses discovery then sees those projects — home list/home scan (the cross-project task view), the dashboard (incl. its live fs.watch on each project's tasks/), skills sync (their Skills/ dirs), home doctor, owns-graph checks, automations, and UID-anchored canonical resolution. Workspace-routed commands run from inside an external root (where walking up finds no .openworkspace/) fall back to the machine store's known workspaces and use the one whose external_roots contains the cwd (the workspace must have been registered once by any command run inside it). Guards: a linked git worktree is never discovered from an external root — neither the root itself nor any dir under it — so a worktree (which carries the committed _project/id) can never surface as a duplicate UID or be picked as canonical (resolution additionally vetoes worktrees via git, as before); every project is deduped by real path, so an entry that overlaps the tree, another entry, or a symlinked spelling never yields a project twice (in-tree wins). An external project's relPath is path.relative(ws.root, root) (it starts with ..), and its lifecycle is metadata-only: with no shelf to sit in, the location view mirrors the declared project.toml value, so projects lifecycle just declares and reconcile never moves it. A missing root, a non-directory, a linked worktree, a non-project git checkout, or a root with no projects is a doctor warning (discovery skips it silently — never a crash); a redundant entry (inside the tree or inside another entry) is info. The old CLI/dashboard ignore the key (unknown config keys are ignored on read).
Skills install from a single aggregated hub (projects skills sync). Agent skills (a directory containing SKILL.md) are authored where they belong — next to the project that owns them (<Project>/Skills/<name>/, plus OpenWorkspace's own bundled skills/<name>/, resolved from the installed package's location — never from an assumed workspace layout — and overridable with [skills] bundled_dir in .openworkspace/config.toml, relative to the workspace root, "" to disable). skills sync discovers every skill source across the workspace (active + shelved projects, via a live scan), aggregates them under <workspace>/.agents/skills/<name> as symlinks to the canonical source (the source of truth stays in the project — never moved or copied), and then installs each for the runtimes by symlinking ~/.claude/skills/<name> and ~/.codex/skills/<name> at the aggregate. Runtime links point at the aggregate, not the source, so .agents/ is the single hub — re-pointing one aggregate link updates both runtimes' view. This deliberately replaces the legacy scattered layout (one runtime symlink straight into each project). Every link target is stored relative to the link's own dir (the workspace survives being moved/renamed), and paths are treated as opaque strings — spaces and : (Inbox:Outbox-style names) are first-class. --dry-run (the default) prints the plan and writes nothing; --apply executes; --json emits the structured plan/result. Sync is idempotent and self-healing: a re-run with the same set is a no-op, a moved source repoints, a removed skill is pruned across all three layers — and a non-symlink squatting a link path (a real dir like *-workspace) is refused, never clobbered (exit 1 if any link was refused). It maintains a markered ### Installed agent skills section (name + one-line description) in the workspace top-level README, idempotently (HTML-comment markers, replace-or-append; byte-identical output on an unchanged set).
The dashboard client is React + TypeScript, built by Vite to a single self-contained HTML file (src/dashboard/client/; decision-8 in Personal OS). It is its own npm package — local node_modules, its own tsconfig (excluded from the root server build so browser-targeted .tsx never leaks into the Node tsc compile) — built via vite-plugin-singlefile so the shipped artifact stays exactly what it was before the migration: one dependency-free, CSP-safe HTML file with no external chunks and no CDN, now served from dist/src/dashboard/index.html. It is a faithful port of the previous vanilla-JS shell: header (view tabs, attention chips, refresh), left rail (lifecycle scope, search, status filter, subtasks toggle), the master project/task tree (collapsible cards, dotted-ID subtask disclosure, status dots, rollups, badges), the detail pane (metadata, rendered markdown body, status/done/note Actions wired to the decision-1 write path with optimistic patch+revert, copyable CLI commands), and the Automations view (machine heartbeat strip, per-automation machine rows, drift banner/filter) — same URL-persisted state (?view=&scope=&status=&q=&subtasks=&task=&project=&autofilter=). The old src/dashboard/index.html stays in the tree as a reference fallback but is no longer what's served. The rail/list/detail columns are now resizable (drag either divider; widths clamp to sane min/max and persist in localStorage, collapsing back to a single stacked column below the existing ~980px mobile breakpoint), the master task tree supports keyboard navigation (roving tabindex over the visible li.task rows — ArrowUp/ArrowDown move focus and selection in rendered DOM order, Enter re-confirms), and the whole client follows dark mode via prefers-color-scheme (no explicit toggle — palette is CSS custom properties, swapped in one @media block).
POST /api/project/reveal opens a project's root in Finder, or its Obsidian vault if one exists, from the client (a "Reveal" control on each project card) — the browser can't spawn a process itself, so this is a narrow, loopback-gated endpoint (same write-gate as the task mutation endpoints, since spawning a process is at least as sensitive as a file write) that resolves the client-supplied project uid to an absolute root server-side and shells out to macOS open, never to a client-supplied path. {target: "obsidian"} 422s when the project root has no .obsidian directory (surfaced in the scan as hasObsidianVault so the client only shows the control when it'll work); any platform other than macOS 501s without spawning anything. The process launcher is injectable (DashboardOptions.processOpener) so tests never actually invoke open.
GET /events (SSE) replaces manual-Refresh-only polling with live push. The warm read-model (below) now emits a change event on every write-through mutation and every fs.watch reconciliation (never on the periodic self-heal rebuild, which would otherwise spam every subscriber on every server-restart-adjacent rebuild); /events is read-gated exactly like /api/scan (Host-header check, GET/HEAD-only posture), bounds its connection count, sends periodic keepalive comments, and cleans up listeners on disconnect (plus a close() override so server shutdown doesn't hang on a live stream). The client opens one EventSource, debounces a burst of events into a single refresh(), and reconnects with exponential backoff on error — falling back to the pre-existing manual Refresh button if EventSource is unavailable or stays down.
The task detail pane has a narrow, library-mediated body editor and interactive Acceptance-Criteria checkboxes (decision-9 in Personal OS, deliberately not a general Markdown/WYSIWYG editor — see the decision for why that fence matters). An "Edit" toggle swaps the rendered body for a plain <textarea> (no editor library) seeded with the task's full current body, so ## Final Summary/## Log are visible and a save never silently drops them; Save routes through a new setTaskBody library primitive that preserves frontmatter verbatim and rewrites only the body. Each rendered - [ ]/- [x] line also gets a real native checkbox (event delegation over the rendered HTML, no library) that calls a new toggleChecklistItem primitive to flip just that one line. Both entry points are hash-guarded the same way task mutations already were: the call carries expectedHash (the warm model's per-file sha256), and a hash mismatch throws ConflictError — mapped to an HTTP 409 (POST /api/task/body, POST /api/task/checkbox) — rather than clobbering a concurrent CLI or Obsidian edit; the client reverts its optimistic patch and asks the user to reload.
The Projects view is a lifecycle-scoped (Active default / All / Dormant / Archived, with counts) master-detail task tree — dotted-ID subtask disclosure, status dots, quadrant/recur badges, a right detail pane with the record markdown and copyable CLI commands. The Automations view (URL-persisted ?view=automations) joins three read-only sources over the live tree — declared machines (each project's _project/automations/<name>/automation.toml machines = [...]), the synced per-machine registries at .openworkspace/machines/<id>.toml (which machines actually activate a given automation), and that machine's last-run outcome + heartbeat age — into a machine-registry freshness strip plus per-automation cards showing schedule, project + lifecycle, where it's activated vs declared, per-machine state/last-run/staleness pills, and placement drift (declared-not-activated and activated-undeclared, computed the way doctor does) inline and as a top banner with a URL-persisted "Drift only" filter. It is served by GET /api/automations with the same security posture as /api/scan (Host-header DNS-rebinding defense, GET/HEAD-only) over the generic stale-while-revalidate ScanCache<T> (automations are not yet on the warm model below). With no flags it binds 127.0.0.1 and accepts only localhost/127.0.0.1 in the Host header (the DNS-rebinding defense) — unchanged. To serve it over Tailscale, the operator sets a bind host (--host, or config host, default 127.0.0.1 — e.g. a Tailscale IP like 100.120.153.52 or 0.0.0.0) and an allowed-hosts set (--allow-host repeatable, or config allowed_hosts array) that is added to the secure default — e.g. --allow-host matteos-mac-mini.tailbd8a21.ts.net (a :port suffix is fine). The Host check still rejects anything outside the (default ∪ configured) set; it never opens up wholesale. Both dashboard dev and dashboard open take these flags and the same keys via --config. The dashboard's read path stays GET/HEAD-only (405 otherwise); writes are the decision-1 loopback-gated exception, not a general mutation surface.
GET /api/automation/logs?project=&name=[&machine=&run=] serves the machine-partitioned per-run logs the runner writes under _project/automations/<name>/logs/<machine>/<stamp>.log — the same logsFor() the CLI's automation logs uses. It returns the run list ({machine, stamp}, newest last, across machines) plus the selected (or latest) run's content, tail-capped at 128KB so a large claude --print stdout can't blow up the response, and traversal-safe by construction (a run is only served if it matches a file logsFor() itself enumerated). It's read-gated like /api/scan (no write surface). In the Automations view, each automation card has a "logs" disclosure with a run picker and a scrollable log view — turning "is it healthy?" into "what did this run actually do, and why did it fail?". Secret values never appear (the runner logs secret keys only).
/api/scan and /api/task are served from a warm, incrementally-maintained read model, not a cache with a TTL (decision-7 Phase 1b, Personal OS). A naive full-tree walk on every request costs ~seconds on a real ~/Documents (deep Archives/Library, ~20 nested git repos) — discovery already skips foreign git working trees (a directory carrying .git that is not an OpenWorkspace project holds no projects and is no longer descended; a measured ~3.5x discovery speedup, 2.6s → 0.74s, while still finding every project, including nested ones and 2-levels-under-a-shelf ones like Dormant Projects/Life Admin/Personal Finance), but the dashboard now goes further: the WarmModel builds the scan once at server start and then keeps it current by construction rather than by expiring it — write-through on the dashboard's own mutation path (a status/done/note edit re-reads only the one file it just touched, no invalidation of the rest) and fs.watch on each project's tasks/ directory (reconciling only the touched file(s) by content sha256, debounced, with self-echo suppression so the watcher doesn't re-process its own write-through update, plus a periodic full-rebuild fallback in case a watcher fails to start on some path). Reads are always served straight from memory — no request ever blocks on a tree walk once the server is up. Nothing is persisted to disk (SQLite stays deliberately deferred, per decision-7's "earn the heavy parts"); the model is a rebuildable, disposable derived index, never a state file — the live tree stays the sole source of truth, and a dropped/restarted model reconstructs itself identically from the files and the watcher. /api/automations is untouched by this — it still runs on the original stale-while-revalidate ScanCache<T> described below, which remains configurable via --cache-ttl MS / config cache_ttl_ms.
The write path closes a data-loss race: optimistic concurrency in touchAndWrite (decision-7 Phase 1a, Personal OS). Two writers — the CLI/dashboard and a human editing the same file in Obsidian — could previously race: both read, one writes, the other's write silently clobbers the first with stale content. Every task write now captures a sha256 of the exact bytes it read, then re-reads and re-hashes the file immediately before the atomic write; a mismatch (or the file having vanished underneath it) throws ConflictError instead of clobbering, turning a silent data-loss race into a visible, retryable conflict. writeFileAtomic was already temp-file + fsync + rename, so the closed hole was purely the read-modify-write gap, not the write itself.
Serving /api/automations stays snappy via a short-TTL in-memory scan cache (unchanged from before Phase 1b, and not yet migrated to the warm model above). The first request builds the scan, caches it in process, and serves it for the TTL window; once stale, a request serves the still-recent cached scan immediately and rebuilds in the background (stale-while-revalidate — no request blocks on the slow walk once warm). It is a rebuildable in-process cache, never a state file (nothing on disk; the live tree stays the source of truth), and the scan's generatedAt always reflects when the scan was actually built, never request time, so freshness shown to the user stays honest. TTL 0 is the default for the foreground dashboard dev case (always fresh); a long-lived served instance (the Mini) sets a small positive TTL (~15000ms suggested).
npm test # build + node:test over dist/tests/**/*.test.jsAll tests run against temp dirs under os.tmpdir() — never the live workspace, never the real ~/Library (the machine store is injected via OPENWORKSPACE_STORE_DIR). Frontmatter-codec fidelity is tested byte-for-byte against real legacy records committed under tests/fixtures/ (do not edit those files). tests/acceptance.test.ts holds the PRD acceptance checks: no state files ever written, duplicate-UID detection, state-named-subdir flagging, the exact (store-free) init stamp, and worktree-post-lands-canonical. tests/infomap.test.ts covers the information map: parsing/inference, idempotent rendering, doctor checks, the CLI redirects, map adopt, and legacy-project backward compatibility; tests/maponly.test.ts covers map-only projects (decision-3): folderless init, strict discovery, writes through the block, promotion on the first native write, map adopt --map-only|--folder, doctor, home list/home doctor and the dashboard scan.
Implemented and green (489 tests): the information map (src/lib/infomap.ts, projects map, the map-aware init/doctor/redirects above, decision-2), the foundation libs (lossless frontmatter codec, atomic fs, TOML, workspace discovery, machine store, UID-anchored canonical resolution, locked ID minting with rename-based stale-lock stealing), tasks (incl. reminders-as-tasks, recurrence, and machine-suffixed minting via home mint-suffix), decisions, forum (threads/messages/presence/inbox/who + the forum sweep retention verb), init (workspace + project identity, orientation README, git posture and information map — no empty stores, plus the .openworkspace/machines/<id>.toml registry heartbeat — now also carrying activations + last-run outcomes), doctor (the PRD §10 set minus the one item below — including conflict scan under .git/, state-named subdirs under any primitive, automation-manifest validation findings incl. the bare-secret hard error, [signature] path checks, declared-vs-activated placement drift + orphaned activations read from the synced registries, resolved-thread archive proposals, unanswered-question aging, doc-currency over the stamped READMEs and the shipped skill, git-posture reconciliation, machine-heartbeat staleness, stale-worktree-registration proposals, [projects] external_roots health), skills sync (cross-project skill aggregation into <ws>/.agents/skills/ + idempotent self-healing install for the Claude Code and Codex runtimes + a markered README section — see below), the dashboard (Projects + Automations views, incl. --config, the /api/automations endpoint, an opt-in tailnet-serving mode, resizable panes + keyboard nav + system dark mode, the /api/project/reveal Finder/Obsidian endpoint, /events SSE live-updates, the decision-9 narrow body-edit + Acceptance-Criteria-checkbox endpoints, and the /api/automation/logs per-run log viewer — see below), and the full projects CLI. Every workspace-routed command registers the canonical checkout with the machine store, and worktree roots are never registered nor resolved as canonical (the §6.3 split-brain guard, regression-tested against real git worktree add checkouts).
Automations are built (PRD §7; src/primitives/automations.ts, src/primitives/automation-runs.ts, src/primitives/automation-scheduler.ts, src/primitives/automation-supervisor.ts, src/runner.ts; tests in tests/automations.test.ts, tests/runner.test.ts, and the focused runtime tests): automation.toml parse/validate (declared placement via runs_on — the forward name for the executor set, matched against projects home machine-id; the legacy machines key is still accepted as an alias, both parsing to the same AutomationManifest.machines field, and declaring both is only accepted when they agree — runs-on-machines-conflict otherwise — cron/calendar_interval + miss_policy, provider-neutral [run].kind, overlap controls, command arrays, static non-secret [run] env (env = { KEY = "value" }; plain strings only — non-string values, pointer-shaped values, and keys colliding with [secrets] are validation errors; under direct_exec runner-only semantics are warnings), pointer-only [secrets], [supervise], [signature], on_dormant_project — now read against the project's effective lifecycle, decision-2's metadata-primary value with location as fallback only, closing the one remaining spot where folder location was still the primary lifecycle signal); the cron→StartCalendarInterval compiler with the PRD §7.1-pinned union semantics (DOM and DOW both restricted ⇒ fires when EITHER matches; conformance-tested, so the v0.2 AND bug cannot recur); late-binding plists (runner + project UID + name — never a project path, never a secret); apply [<name>|--all] with declared-machines reconciliation (undeclared ⇒ error, --force overrides; idempotent convergence — unchanged = no-op, cadence change = regenerate + reload); deactivate · list [--all] (every machine's synced registry with explicit staleness) · status (activation records ↔ launchd ↔ tree placement drift only) · supervise (one local recovery tick) · supervisor apply|status|deactivate (one com.openworkspace.supervisor LaunchAgent) · prune · logs · run-now (through the runner path). The runner resolves UID→canonical at fire time, creates a machine-local run ledger attempt before synced-tree reads, records phase/outcome in ~/Library/Application Support/OpenWorkspace/automation-runs/, resolves [secrets] per run through configured scheme resolvers (env-only — tests grep every written artifact for the resolved value), builds the child env as base env < [run] env (static) < resolved secrets, writes machine-partitioned logs (logs/<machine>/<stamp>.log, LOG_RETENTION newest kept), and mirrors last-run outcomes to its own synced machine registry file (P15). launchctl + the LaunchAgents dir sit behind an injectable LaunchdAdapter; the OPENWORKSPACE_LAUNCHD_DIR env override selects a file-backed fake, which tests use exclusively.
The decision-1 TCC posture is wired (PRD §7.4, resolved 2026-06-10; Personal OS decision-1): the node that plists invoke the runner with is a machine-local fact — projects home runner-node <path> stores it in the App Support store (validated: exists, regular file, executable; v1 posture = a dedicated copy of the official nodejs.org pkg build at a fixed path outside the tree, granted once per machine — see Tools/Automations/MINI_BOOTSTRAP.md "OpenWorkspace runner setup"). apply/list/status all resolve the node through one chain (injected → configured runner-node → process.execPath), so a configured-but-not-re-applied install correctly reports stale-install; an unset runner-node falls back to the current node with a WARNING in apply output (ApplySummary.warnings). projects home doctor carries the runner-posture probes (machine-local, best-effort, system binaries behind an injectable ExecFn seam): runner-node-unset (activations here but nothing configured → warn), runner-node-provenance (Homebrew Cellar path, or codesign -dv --verbose=2 failing / ad-hoc / no Developer-ID Authority → warn — the grant breaks on update), and claude-grant-staleness (claude's Documents-folder grant is path-keyed per version; the probe resolves the current version from the ~/.local/bin/claude symlink target and queries the user TCC db via sqlite3 for a matching path-keyed allow row — no match → warn "re-seed needed"; unreadable db → an info-level "unverifiable" finding, never an error).
Importers are built (PRD §11 step 4; src/importers.ts; tests in tests/importers.test.ts, run against the real legacy fixture corpus): projects import legacy is dry-run-first (--apply executes exactly the plan; per-record audit lines in both modes; --all iterates every project with per-project failure isolation — a failing project is refused whole, with an honest refusal line, while the others still apply and print their audits). State fidelity: legacy Backlog.md statuses map to the native vocabulary; parent_task_id normalizes into the dotted ID (disagreement is a plan error); bodies and unknown frontmatter keys are byte-preserved; archived/completed legacy records land in tasks/archive/. Reminders import as tasks (surface_on → hidden_until; surfaced → live todo; dismissed → archived task keeping the closing-reasoning log line; promoted → archived with a cross-ref; new IDs minted above the legacy max under the project's mint lock). Dirchannels flatten into forum threads (<date>--<channel>--<slug>; one immutable maildir file per messages.jsonl line; sqlite/token/pty tool state listed as skips). Idempotency is verified, not assumed: an ID hit must be the same import (same ID-carrying filename or byte-equal content) — a legacy ID colliding with a pre-existing native task is a loud plan error, never a silent "already imported"; intra-plan duplicate targets (e.g. a duplicated JSONL line after an iCloud append glitch) are deduped when byte-identical and errored when content differs, so an error-free plan can never crash mid-apply. Audit completeness: drafts/, archive/-beyond-tasks/, and the legacy v0.2 reviews/ and proposals/ dirs (under the project's control-plane directory) all get honest per-file skip lines.
Lifecycle metadata-as-truth + the reconciler are built (decision-2 draft; src/reconcile.ts, the lifecycle/intent helpers in src/lib/workspace.ts + src/lib/machine.ts; tests in tests/reconcile.test.ts, tests/lifecycle-metadata.test.ts, tests/lifecycle-intent.test.ts). The capability is whole: readDeclaredLifecycle/writeDeclaredLifecycle (lossless, sheds the key on active), effectiveLifecycle (declared-wins, location-fallback), the machine-local intent-log, classifyDrift (git → intent-log → propose), reconcilePlan/applyReconcile (dry-run default; --apply; --auto for the glitch-certain class; same-ID dedup + ghost-dir healing), the metadata-primary projects lifecycle and the projects reconcile CLI (incl. --revert/--adopt-location human tiebreaks), and doctor's read-only drift report. The lifecycle vocabulary is exactly active|dormant|archived (Matteo dropped ongoing 2026-06-11; the legacy ongoing boolean is removed). Ratify-gated (not yet flipped on the live tree): the principle amendment into the architecture docs, the schema 2→3 bump, wiring the Mini's pre-automation reconcile --apply --auto step, and record-retention field-as-truth (Track A's retired: — deferred per Principle 6, the observed corruption was lifecycle, not retention). See Personal OS/_project/decisions/decision-2 - lifecycle-metadata-as-truth.md. No ~/Documents/.git monolith is part of this design — git is per-project and optional.
Not yet implemented (each stubbed loudly, never silently no-oped):
- The §7.4 TCC question is RESOLVED (decision-1, 2026-06-10) and the code deltas are in (runner-node + the doctor posture probes, above) — what remains is per-machine bootstrap, not code: installing the official-pkg node copy at the fixed path and seeding the grants is a supervised one-time act per machine (steps in
Tools/Automations/MINI_BOOTSTRAP.md). The runner'sexecute()seam still spawns (measured sufficient: leaves ride their own position-independent folder grants);direct_exec = trueremains the documented hybrid fallback for claude jobs (ProgramArguments = the command itself, WorkingDirectory baked at apply time;[secrets]rejected in that mode — no runner to resolve them) with decision-1's switch trigger: grant-staleness probe firing more than ~monthly. - Advanced missed-run scheduling —
skip/catch-updecision logic exists in the Runtime v2 scheduler helper and manifests validatemisfire_grace_seconds/max_catch_up; the current per-automation launchd fire path still runs a single managed occurrence at fire time.fail-loudandcoalesceare reserved and doctor warns when they appear.[schedule] timezoneis rejected at validation until a consumer exists (launchd fires machine-local; silently-local scheduling under a declared timezone would be the worst of both). - The §11.4 manual migration items — the two v0.2 review records → tasks and the finance
_proposals/re-home are migrating-agent work, not importer scope; the importer lists those legacy dirs as audited skips so the checklist cannot miss them. - One doctor gap: the aging-untracked-forum-message commit-sweep proposal (the §6.3 commit-=-retention nudge; needs git-tracking introspection of the canonical forum).
- The peer-coordination machinery (heartbeats, staleness warnings, cross-machine placement-drift healing,
mint-suffixIDs) is cataloged, not removed. It was built for a multi-machine, independently-applying model and every laptop automation still depends on parts of it today._project/wiki/compute-plane-vestigial-catalog.mdmaps exactly what becomes safe to cut once a single always-on hub is the sole executor (decision-7 Phase 4, gated on token rotation — Personal OS task-201/203) — a hub is not a peer, so questions phrased as cross-machine reconciliation collapse to "is the hub itself healthy." Nothing in that catalog should be removed opportunistically; removal is a hub-phase decision.
Pre-migration checklist (real-corpus blockers, found by running the importer against all six preserved legacy-imports/ snapshots). Loud whole-project refusal is the designed posture; these two must be hand-fixed before §11 step 4 can apply cleanly:
- Personal OS —
_tasks/tasks/task-181 - Design-agent-purchase-delegation-mechanism.mdhas an unquoted:in itstitle:value (invalid YAML written by the legacy tool); quote the title. - Home Automation —
task-1 - Approve-Samsung-TV…pairing-prompt.mdand its iCloud duplicate… 2.mdboth carryid: TASK-1; delete the duplicate (the contents diverge —duplicate legacy task idrefuses the project until resolved).
Also note for the re-migration pass: the PRD §6.1 example .gitignore stanza shows an unanchored archive/ pattern, which contradicts §4.8/§11.4 (it would git-ignore tasks/archive/ and forum/threads/archive/, the committed retention homes). The stamp ships anchored (/archive/), and doctor proposes anchoring wherever it finds the unanchored legacy pattern; the PRD example should be corrected to match when it is next revised.
The v0.2 implementation under Personal OS/Tools/OpenWorkspace/ is reference-only (21 known defects) and is retired after re-migration.