From 088e09973728ceb02e8b9a04447860145c5c3bb5 Mon Sep 17 00:00:00 2001 From: gustavonline <8681157+gustavonline@users.noreply.github.com> Date: Wed, 21 Oct 2026 12:11:35 +0200 Subject: [PATCH] Clarify host setup and maintenance ownership Describe the existing coordinator, Foundation and project AgentOps responsibilities, startup stages, scoped maintenance holds and consistent same-host recovery. Preserve separate source, synthetic and live-host evidence. Refs #83. Co-authored-by: Claude Opus 5.5 --- VERSION | 2 +- docs/architecture.md | 14 +- docs/qualification.md | 3 +- foundation/factory-foundation/SKILL.md | 11 +- .../factory-foundation/references/adoption.md | 17 ++- .../factory-foundation/references/setup.md | 131 +++++++++++++++++- 6 files changed, 169 insertions(+), 9 deletions(-) diff --git a/VERSION b/VERSION index f8bc4c6..d8a023e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.18 +0.1.19 diff --git a/docs/architecture.md b/docs/architecture.md index 585951c..9adf02d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ # Responsibility and access -Revision: 0.1.6 · Updated: 2026-10-09 +Revision: 0.1.19 · Updated: 2026-10-21 Factory has three responsibilities around existing tools. It has no server, provider adapter, task database or application runtime of its own. @@ -8,6 +8,7 @@ provider adapter, task database or application runtime of its own. | Responsibility | Owns | Does not establish | | --- | --- | --- | | Foundation | Project context, native setup, access choices and readiness checks; repair when these change | Product scope, continuous execution or readiness merely because files were installed | +| Host coordinator (optional) | Host continuity, maintenance shared by several projects, and repair requests to Foundation, within an explicit owner mandate | Product priorities, worker assignments or acceptance in a project; administrator rights or personal connectors | | AgentOps | Research, priorities, assignments, worker model choices, reviewed skill/context improvements and acceptance within delegated authority | Administrator access, permission to bypass review or self-installed skills | | ADLC | The concrete specification, implementation, independent review and authorized delivery | Authority to accept unrelated work or widen its own access | | T3 and native harness | Conversations, models, worktree binding, native tools, permissions and recovery | Application deployment, monitoring or per-role OS isolation by naming a thread | @@ -19,6 +20,16 @@ or context gap affects the task; it is not a stage repeated before every edit. The owner decides admission and delivery by default, or delegates either for a specific scope. A completed run is not acceptance; published is not installed. +A host coordinator, sometimes called a Planning Agent, is an installation choice. +It can be an existing lead thread given a host mandate; it is not a daemon, a +central queue or another privileged tier. It keeps the shared host ready after +restart and coordinates maintenance that affects several projects. When a host +condition needs repair, it asks Foundation, which owns the reusable method and +scoped readiness checks. Each project's AgentOps keeps its product priorities, +workers and acceptance; ADLC performs the tasks. A blocked host operation holds +only that operation and the work depending on it, not every project. See +[keeping the host ready](../foundation/factory-foundation/references/setup.md#keep-the-host-ready-after-restart). + ## Three-level access architecture The three access levels are **human owner → AgentOps → ADLC workers**. The arrows @@ -54,6 +65,7 @@ calling three role names three isolated environments. | Method and project instructions | Reviewed source plus selected native skill scope | Loaded sources match the adopted revision | | Work status and delivery | GitHub issues/Projects, PRs, CI and releases | Actual fields, credentials and protections read back | | Deployment/data/telemetry | Application's chosen infrastructure | Task-specific operation and recovery evidence | +| Host startup and maintenance schedule | Host's native service, autostart and scheduler; private installation record | Readback after boot and login; actual trigger evidence, not the configured schedule | A client can be on the execution machine itself and still connect to a different OS account's service. Closing a client is safe only after service independence diff --git a/docs/qualification.md b/docs/qualification.md index baa91db..9c985c8 100644 --- a/docs/qualification.md +++ b/docs/qualification.md @@ -1,6 +1,6 @@ # Qualification -Revision: 0.1.18 · Updated: 2026-10-17 +Revision: 0.1.19 · Updated: 2026-10-21 This record distinguishes source review, disposable exercises and observed native operation. A package release does not qualify another host, every future update @@ -10,6 +10,7 @@ remain with the installation; public issues track the remaining acceptance work. | Boundary | Observed evidence | Limit / next check | | --- | --- | --- | | Package | Eight portable skills, metadata/link checks and staging tests | Mechanical checks do not establish agent decisions | +| Host continuity and maintenance (0.1.19 candidate) | 2026-10-21: [Factory #83](https://github.com/arcitai/factory/issues/83) source change, after an installation could look ready while operator apps did not start after login and no maintenance schedule was active (owner report, not reproduced here). Setup, adoption and architecture now describe the optional host coordinator, separate startup stages, one owned nightly maintenance opportunity, scoped holds and a same-host recovery copy. The existing owner coordinator reported one actual scheduled wake on 2026-10-21. On the frozen candidate: `scripts/check.py` passed with 8 skills and 0 errors, 11 unit tests passed, and staging Foundation produced its 9 portable files plus a manifest, which were not installed. In a fresh Sol 6.1 Max context, one application each of four synthetic cases matched the retained rubric (lead assessment, evidence kept privately): independent source work continued without a hold; a startup or wake was kept apart from recovery; unknown local account-tool exposure stayed unknown; and a real maintenance hold kept its timeouts and restored prior states. An earlier rehearsal was not run, because its brief prohibited the available reader; it is neither a pass nor a failure | These are bounded synthetic decisions, not live proof of boot, update, reconnect or isolation, and not a reliability result. That single wake is not proof of reboot, of operation with the Mac disconnected, or of full recovery. Controlled reboot, login and reconnect, safe update and continuation, and the host gates remain open live acceptance; this change marks none of them complete. Independent review of the exact final source is pending in the delivery PR | | Production artifact evidence (0.1.18 candidate) | Reconciled 17 October 2026 from product-lead handbacks ([Factory #76](https://github.com/arcitai/factory/issues/76); not reproduced here). OPD: the source expected eight embedded editor assets, but the installed executable held six and served editor-not-built. Its six tests substituted a `#[cfg(test)]` `tests::BUNDLE_FILES` list, while production uses `OUT_DIR/bundle.rs`, so those tests did not exercise production inclusion. The OPD lead's original handoff left a production smoke optional; the corrected R10 proof gate made it required. A same-source replacement was atomically adopted at 06:17:35Z (transferred receipt). AIOS: the contrast build installed at 06:18:55Z (298 files). Bridge: the owner passed queue history. The lead checked retained artifacts offline against the eight source-derived names: the old six-asset output was rejected for missing `editor.js` and `panel.js`, the fresh eight passed, and the R10 manifest and receipt agree. Six of the eight assets are runtime bytes; two are build provenance | Offline reuse of historical evidence; no binary was run, and this does not show that the method caused the recovery. Still open: the OPD native workflow and app-origin binding, and the AIOS native colours and opening. The missing Bridge toast is not a proven defect; no custom Undo is authorized. In one fresh-context rehearsal of five incident packets, every decision kept these limits: the incomplete package, the installed but unaccepted workflow and visual checks, the toast without an established contract, and the dropped accepted centre amendment. This tested decisions only, with no live product action and no claim of general reliability. Independent review of the exact candidate and its checks is recorded in the delivery PR | | Blocked-request follow-through (0.1.17 candidate) | 2026-10-15, after the held OPD request recorded below ([Factory #32](https://github.com/arcitai/factory/issues/32); coordinator native UI actions plus Factory native readback). Declining the held compound shell call failed it without running it, but the run stayed active and proposed a second shell change before the prepared text-only correction arrived. The coordinator then cancelled that held call: neither call ran, the run was interrupted and ended with nothing pending, and its pre-recovery checkpoint was kept. The OPD lead sent its accepted native-file-only instruction to the same worker at that checkpoint; the next run completed native file changes with no shell or approval items and nothing pending while still active | Operator-assisted progress after an interrupted blocked attempt, not an automatic wake, autonomous responder, uninterrupted run, completed diagnostic checks, review or product delivery, or OS isolation. The two settled requests are not to be re-disposed. The source guidance followed this event and did not cause it. Source checks and independent review are recorded in the delivery PR | | Lead-prepared inputs (0.1.16 candidate) | 2026-10-15: separately, an OPD worker's archive preparation waited 15 m 12 s for approval and was resolved once in the native UI (operator report, not reproduced here). In this [Factory #32](https://github.com/arcitai/factory/issues/32) trial the lead prepared harmless inputs in the worker's task worktree; the same Claude worker used native Read and Edit for one result-file change and the AgentOps text change. The lead independently verified the inputs unchanged and the expected result hash; the run ended terminal with nothing pending, and its native timeline showed no approval request or worker shell command | One same-worker prepared-input text task, not a fresh-context comparison, measured wait reduction, general prompt-free operation, worker build/test permission, permission wake or decision authority, or isolation. A separate compound Python edit and Node/shell check request in that same OPD run remains held at this observation; its lead has a recovery handoff, not a passing recovery. Source checks and independent review are recorded in the delivery PR | diff --git a/foundation/factory-foundation/SKILL.md b/foundation/factory-foundation/SKILL.md index 5241a96..8957430 100644 --- a/foundation/factory-foundation/SKILL.md +++ b/foundation/factory-foundation/SKILL.md @@ -3,8 +3,8 @@ name: factory-foundation description: Prepare or assess a software project's engineering foundation and its execution host, including reproducible setup, real checks, documentation, CI/delivery, native harness access and GitHub work tracking. license: MIT metadata: - version: "0.1.14" - updated: "2026-10-15" + version: "0.1.19" + updated: "2026-10-21" --- # Factory Foundation @@ -83,7 +83,12 @@ Prepare only the chosen capabilities: approved data destinations and material risk/escalation conditions. - Qualify service startup, client disconnect, restart and recovery on disposable work before relying on unattended operation. Reconcile active/unknown writers - before stopping a service or changing its version. + before stopping a service or changing its version. For host continuity, + establish each startup stage and the one owned nightly maintenance opportunity as + in [the setup guide](references/setup.md#keep-the-host-ready-after-restart). An + optional host coordinator holds host continuity under an explicit mandate and + asks Foundation to repair host conditions. Project AgentOps keeps product work, + and the coordinator gains no administrator rights. - Establish the selected native update channel, updater ownership and maintenance boundary. Update checks are not automatic installs; interrupted turns, OS prompts and encrypted-disk unlock need an explicit recovery route. Preserve skill-local diff --git a/foundation/factory-foundation/references/adoption.md b/foundation/factory-foundation/references/adoption.md index 2dc2be5..23a490c 100644 --- a/foundation/factory-foundation/references/adoption.md +++ b/foundation/factory-foundation/references/adoption.md @@ -1,6 +1,6 @@ # Adoption record -Revision: 0.1.14 · Updated: 2026-10-15 +Revision: 0.1.19 · Updated: 2026-10-21 Foundation identifies the appropriate existing project/adoption record and establishes the relevant choices. AgentOps maintains them and scoped exceptions @@ -91,6 +91,18 @@ Reuse the following existing choice families only where they matter: execution host, OS/account and workspace, distinguished from the client device. - Selected update channels and native installer/updater ownership; checks versus automatic installs, idle/interruption rules, recovery and last observed result. +- Host continuity, where chosen: the host coordinator's thread and mandate, and + the projects whose leads it coordinates with. For each startup stage (disk + unlock, headless service boot, network routes, desktop autostart after login, + power policy), record its owner and last dated readback; see the + [setup guide](setup.md#keep-the-host-ready-after-restart). +- The one owned nightly maintenance opportunity: its native scheduler and target, + each component transaction and its owner, the last actual trigger and what it + observed (no-op; deferred with reason, next action and holder; or the stages + installed, restarted and continued that it reached), the authority it used, and + the retired duplicate after a migration. +- Recovery: the private recovery copy's location, holder and scope, the last + verified same-host restore, and the operator able to act while the service is down. - AgentOps scope (Factory and the adopted repository) and the narrower ADLC task workspaces. Record each extra grant separately from that baseline: who or which role, target, environment, purpose, date, authorizer, expiry/removal condition @@ -123,6 +135,9 @@ date and evidence. Relevant proof includes: 5. The actual phone/remote decision route if selected. 6. A representative isolation check for each trust boundary being claimed. 7. Readback of actual GitHub status/protections and delivered application behavior. +8. Where host continuity is claimed: boot, login, disconnect and reconnect, and one + actual scheduled wake, each recorded separately. A wake alone is not reboot or + recovery proof. Keep source inspection, disposable rehearsals and live installation evidence distinct. One successful run qualifies that path, not every model or future update. diff --git a/foundation/factory-foundation/references/setup.md b/foundation/factory-foundation/references/setup.md index 46e5629..adc0cd7 100644 --- a/foundation/factory-foundation/references/setup.md +++ b/foundation/factory-foundation/references/setup.md @@ -1,6 +1,6 @@ # Set up the host and operator client -Revision: 0.1.14 · Updated: 2026-10-15 +Revision: 0.1.19 · Updated: 2026-10-21 This reference setup uses T3 Code on a Linux execution host, with a Mac and optionally a phone as clients. The host can be a laptop, workstation or VPS. @@ -40,7 +40,20 @@ Activate the lead role in that thread; preserve the project's shared instruction Workers receive the target project's context and skills. Separate provider profiles, T3 environments/OS identities or VMs are appropriate when the lead, workers or projects require different filesystem/network trust. -Do not copy a personal AIOS installation or personal provider home into this setup. + +Keep the owner's personal account and the Factory execution account separate, +each with its own instructions. Do not copy a personal AIOS installation, personal +provider home, Notion workspace, browser profile or credentials into this setup. A +separate OS account or provider home does not prove that connectors synced to the +provider account are excluded. Check which tools a fresh native session actually +exposes, and use the provider's supported local controls to exclude unwanted ones +for this installation. Preserve unrelated settings and the owner's global +connections; do not revoke, connect or grant anything account-wide to pass the +check. A session that was already running may keep its previous tool registry; +do not claim the change reached it without reading it back, and move it over through +the supported lifecycle at a natural safe checkpoint. This needs no new chat or +restart for unrelated native tools or an already-qualified context. The +repository's GitHub access and native T3 orchestration must keep working. Preserve any old Factory runtime and private history while qualifying this setup. Avoid pointing two active agent writers at the same checkout. Do not run native @@ -349,6 +362,50 @@ and prove the actual phone question/response route before relying on it. [Connections](https://github.com/pingdotgg/t3code/blob/ec80933ac8cd02fec5c97b342462ccc9567cdb1e/docs/user/remote-access.md), [mobile notifications](https://github.com/pingdotgg/t3code/blob/ec80933ac8cd02fec5c97b342462ccc9567cdb1e/docs/user/mobile-notifications.md). +## Keep the host ready after restart + +An installation can look ready while the operator's apps do not start after login +and no maintenance schedule is active. The installer or host owner establishes and +verifies the chosen startup, service, power, network and schedule settings. + +An installation may also choose an owner-side **host coordinator**, sometimes +called a Planning Agent: a thread with an explicit mandate to keep the host +continuous, coordinate maintenance that affects several projects, and ask +Foundation to repair a host condition. It is optional. An existing lead thread can +take that mandate, so no extra top-level chat, daemon or central queue is needed. +It does not replace each project's AgentOps, which keeps that product's priorities, +workers and acceptance, and ADLC still performs the tasks. The role grants no +administrator rights or personal connectors; host administration stays with the +person or narrow native route that holds it. Resolve the actual host and accounts, +client and server routes, effective permissions, and the person who can operate +recovery when the service is down. After a restart or migration, reuse the +existing coordinator and leads instead of starting replacements. + +Each startup stage is a separate observation: + +| Stage | Establish and verify | Limit | +| --- | --- | --- | +| Disk unlock | Who unlocks an encrypted disk after boot, and how they learn it is waiting | Nothing below starts until then | +| Headless service boot | The execution service is enabled, starts at boot without a login and survives logout, as in [section 3](#3-make-the-service-independent-of-the-client) | Read it back after boot; the install command alone is not proof | +| Network routes | The network, a private route such as Tailscale, T3 Connect and the chosen SSH route come up without a desktop login | A client may reconnect through a fallback route rather than the selected one | +| Desktop session | Operator apps the owner expects start through the desktop's supported autostart after login | Runs only after someone logs in; it is not service boot | +| Power and reachability | On external power the host stays awake and reachable with the screen locked; battery protection and suspend follow the owner's choice | Locked operation on power is not battery or suspend recovery | + +Prove readiness at each boundary separately: boot, login, client disconnect and +reconnect, and an actual scheduled wake. After a controlled reboot, read back from +a fresh native turn that the service, routes, projects, threads and held decisions +are present, and that the expected apps started after login. One scheduled wake is +not reboot, disconnected-client or full recovery proof. Notify someone when a stage +fails or holds, a gap appears or maintenance changed something; do not send daily +unchanged pings. + +Hand each relevant capability over in the existing adoption record, without a new +template: the selected capability; its actual native owner and control, applied +scope and readback; where its private evidence lives and who holds it; and the +exact remaining gap and next action. A missing access, recovery or launcher fact +stays a named capability gap. Keep host identities, paths, raw history and recovery +copies private. + ## 5. Adopt selected skills Clone a reviewed Factory tag on the host into a source directory, separate from @@ -456,6 +513,49 @@ or promise scheduling from a skill. An agent must not stop its own host mid-task and assume it can inspect the result. Hand off disruptive maintenance to the host's existing operator/maintenance facility and reconcile on return. +### One nightly maintenance opportunity + +Give the host one owned nightly maintenance opportunity through a supported native +scheduler, such as the OS timer facility or a native T3 scheduled task. It is a +check that runs once per night for each target. It reads active work and current +versions, then records what actually happened: + +- **No-op:** the component is already current and there is nothing to install. Do + not reinstall it. +- **Deferred:** a change is due but unsafe now, for example because of active + work. Record the concrete reason, the next action or revisit trigger, and who + holds it. A deferral is never a completed update or continuation. +- **Installed, restarted, continued:** observed stages that one transaction can + pass through in turn. Installing applies an update through the component's + native route; restarting activates it and interrupts active turns; continuation + means interrupted work actually resumed, read back afterwards. A restart alone + is not continuation. + +The schedule grants no authority by itself. Installing or restarting still needs +the existing delegated authority for that component and scope. + +OS and packages, the desktop client, the execution service and provider CLIs are +separate transactions, each with its own channel and owner. One succeeding neither +updates nor proves another. The opportunity is not an installer and does not +guarantee unattended updates. Prove it from actual trigger evidence, not from the +configured schedule. After a migration, keep exactly one schedule per night and +target; retire the old one rather than letting two run. Do not add polling or an +approval pump. + +A blocked update, reboot or client acceptance holds only that operation and the +work depending on it. Other already-authorized product and method work continues +in its existing lead and writer, with the specific hold kept visible. An agreed +short maintenance hold is different: healthy work drains or reaches a checkpoint, +every actual producer is accounted for and paused (schedules, clients, PR watches +and other wakes), and each one's prior enabled state is restored afterwards. Do +not interrupt a healthy job to start maintenance. + +Keep the current official runtime and native harnesses; do not run a maintained +fork or activate a parked custom patch on the execution host. A quoted +configuration, installed file, native preference, open listener or successful +reconnect does not by itself prove the allowed tools, isolation, recovery or +resumed work. + For Omarchy, use the installed version's supported updater; inspect its prompts and restart behavior before unattended use. Encrypted boot may still require a person to unlock the disk. A system snapshot need not cover the separate home @@ -493,3 +593,30 @@ threads, including archived chats, from T3; the folder and Git repository remain on disk. Archiving a thread does not remove its project. Reconcile active work first and obtain the owner's explicit deletion decision. Use the native action, not manual database edits. Backup retention/deletion is a separate scoped choice. + +### Same-host recovery copy + +Before a disruptive change, take a consistent private recovery copy on the same +host: + +1. Before stopping anything, establish an operator route independent of the + service, so it survives the service disconnecting. Account for the relevant + holders of the state, including connected clients and any client SSH + auto-launch that could start another server. +2. Let healthy work drain or reach a checkpoint, then quiesce through supported + native controls. If a relevant holder is unknown or cannot be seen, or work + does not drain cleanly, defer before stopping. Do not stop or kill every + process to force quiescence. +3. Check that the source is stable before the copy, take the copy, check the + source again afterwards, and confirm the copy matches it. +4. Copy the complete required state: databases with their SQLite companion files, + shared attachments, service configuration and the prior version. + +Keep the copy private on the same host and verify a restore there. Afterwards, +check actual reconnection and provider continuation, and that held queues and +pending decisions survived. Restore exactly the prior connections and enabled +producers. A root filesystem snapshot alone does not prove a consistent home or +application recovery; its coverage and consistency depend on the actual subvolume +and data scope. Watch disk space, clock correctness and log retention. Preserve +actual failures and history, and read back the current state before any retry. +Keep commands, process identities, paths and other host facts in the private record.