Sync an agent workspace

Folderbase Cloud is being designed for folders that humans, editors, and agents change directly. Local files remain ordinary files. After one explicit connection, stable changes synchronize automatically without requiring a commit, push, or per-file approval.

Development status: this page describes the accepted owner-sync product target and its two pilot fixtures. It is not a claim that Folderbase Core 0.7.2 or the current native App provides end-to-end Cloud sync. Exact local capture and restore, verified Cloud storage foundations, native restore, and a restart-safe local owner-sync journal now exist. Disposable native GCS provider conformance and a narrower private Cloud SQL behavioral checkpoint have also passed in a dedicated private GCP project. The native GCS/PostgreSQL authority composition and the reviewed Cloud SQL authority install plan/apply/execution-recovery path now pass locally as well. A generalized Content & Stories V0 folder has also passed a one-device PostgreSQL/MinIO local-cell pilot through a descriptor-bound disposable copy: exact managed bytes, Remote Head, Device Cursor, restart replay, and final Up to date state were verified without modifying the source. A follow-on local hosted-bootstrap tracer now publishes encrypted chunks from a logical MacBook through a bounded authority process and restores the exact current Core Version into an absent destination for a distinct logical Mac mini Device. It uses real PostgreSQL 16, request-validating numeric-loopback native-GCS semantics, direct ciphertext transfer, and exact expiring Google V4 upload/download capability shapes. This is a logical two-Device proof—not live GCP, a physical MacBook-to-Mac-mini run, or bidirectional sync. All cost-bearing Cloud SQL test resources were removed. No live authority Job ran for the later local checkpoint. These proofs do not deploy the owner-sync data plane. The native App can now project exact local-service status and Pause/Resume, but it truthfully shows Not connected when no verified service session exists. App connection, remote-to-local application, conflict handling, the physical two-device loop, and the full V1 folder remain in development.

What works today

The implementation has crossed a sequence of local and real-provider checkpoints without changing the ordinary-folder experience:

1. exact Core captures stable ordinary files as immutable Folderbase Versions;
2. a deterministic owner-sync coordinator verifies required bytes before it advances one Remote Head;
3. a bounded private journal coalesces rapid changes, preserves Pause and retry across restart, and replays interrupted work without publishing twice; and
4. a privacy-safe local-cell pilot exercised a real generalized V0 folder containing 47 mixed ordinary files through initialization, exact managed-byte transfer, stable-edit publication, Remote Head revision 1 to 2, Device Cursor revision 2, restart reconciliation, and final settled Up to date state without modifying the source;
5. a local hosted-bootstrap tracer publishes a mixed Markdown-and-opaque Folderbase from one logical MacBook, survives a committed upload whose response was lost, and cleanly restores the exact current Core Version for a distinct logical Mac mini before committing its Device Cursor;
6. its trusted clients encrypt and decrypt chunks locally, transfer only ciphertext directly to a pinned numeric-loopback provider, and strictly validate create-only upload and exact-generation download capabilities with an absolute lifetime of at most five minutes;
7. one disposable native GCS bucket passed exact-generation create, replay, conflict, range read, replacement, recovery, marker, and three-inventory behavior before returning to zero resources;
8. one disposable private Cloud SQL cell behaviorally passed loopback-only private-IP proxy transport, passwordless IAM authentication, schema migration, portable collation, receipt-bound backup/clean restore, and replay;
9. the native GCS/PostgreSQL composition locally binds immutable provider generations to PostgreSQL staging, managed promotion, reconstruction, terminal collection, and backup/restore evidence;
10. the owner-private operator locally reviews and applies the exact authority infrastructure transition, then proves one etag-fenced install execution, lost-response adoption without relaunch, and revision-bound cleanup against fixtures. No live authority Job ran; and
11. the native App maps the exact restart-safe owner-sync status and Pause/Resume seam while refusing to imply connection, transfer progress, or conflict when those facts are unavailable.

The journal stores no changed paths, stays outside the Folderbase, and binds to the selected physical root. Opening the service schedules an authoritative scan before it can report Up to date. The deterministic tests still use an in-memory adapter where appropriate; the generalized V0 pilot instead used the sealed PostgreSQL/MinIO local cell. Neither is deployed Folderbase Cloud.

Current evidence is recorded in Platform PR #190 and PR #192. The generalized existing-folder preflight is recorded in PR #196. It uses the deterministic in-memory Cloud adapter and is not the physical two-device pilot. The durable PostgreSQL/MinIO owner-sync composition is recorded in PR #218, the truthful native App status projection in PR #219, and the generalized one-device V0 local-cell pilot in PR #220. The encrypted logical two-Device hosted-bootstrap tracer, direct ciphertext transfer, and expiring Google V4 capability contracts are recorded in PR #221. The earlier native provider/database composition is recorded in PR #204, and the latest local authority execution checkpoint is recorded in PR #215 under issue #211. Real provider evidence is recorded in Platform issue #205 and issue #207.

The hosted path is fixed before deployment

The first owner-only Cloud cell now has a reviewed architecture rather than an open-ended provider choice. The narrow target is one dedicated GCP project in asia-southeast1: a stateless Cloud Run coordinator, private Cloud SQL PostgreSQL, native GCS immutable generations, a KMS-backed narrow Key Broker, and locked OpenTofu operations.

The contract preserves the product behavior above:

• exact verified bytes remain durable before Remote Head metadata advances;
• Cloud SQL is private and reached through an authenticated TLS/IAM proxy;
• each stored chunk uses the accepted authenticated managed-envelope profile;
• direct short-lived chunk transfer does not expose reusable bucket authority;
• provider retries and collection bind exact GCS generations; and
• public evidence omits private resource identities while remaining verifiable against an owner-private deployment receipt.

The local hosted-bootstrap tracer now exercises that shape without pretending to be the deployed service. A logical MacBook publishes through the existing restart-safe background service to an independent bounded HTTP authority process backed by real PostgreSQL and request-validating numeric-loopback GCS semantics. The trusted client encrypts each chunk, sends only ciphertext to the provider, and adopts a create that committed even when its response was lost. A distinct logical Mac mini then downloads the exact immutable ciphertext generation, decrypts it locally, reconstructs the same exact Core Version into an absent destination, and commits its Cursor only after Core verification.

The production-shaped capability contracts are also locally verified: upload is exact-object, create-only, length-and-metadata-bound, and expires within five minutes; download binds one exact GCS generation and the same maximum lifetime. Reissue never extends the original operation. These requests were validated by loopback fixtures—not live IAM or GCS—and no Device bearer credential reached the provider. Production Identity, KMS/Key Broker, authenticated TLS/Cloud Run, live GCP completion, physical devices, remote apply, and bidirectional conflict handling remain open.

The bootstrap remains live in the dedicated private pilot project. Its reviewed boundary contains the Storage API binding and one empty regional Standard state bucket with uniform access, public-access prevention, Object Versioning, and seven-day soft deletion. Provider-read-only status and exact-revision conformance re-attest the reviewed plan, private state, live bucket policy, and empty live/noncurrent/soft-deleted object inventories.

Two disposable provider proofs have now passed beyond that bootstrap:

• native GCS exact-generation behavior passed against one temporary data bucket, which was proven empty and removed; and
• private Cloud SQL transport, migration, collation, backup, clean restore, and replay behavior passed through one bounded Cloud Run Job. The database, Job and executions, temporary identity, and private images were removed.

That Cloud SQL run is a behavioral sub-gate, not the full release gate. A fresh run must still bind the image build to exact committed source, re-attest live provider state before the Job, compare every authoritative restored row and native-GCS receipt tuple, prove the distinct runtime/migrator install-to-steady authority, and finish exact provider-absence cleanup.

The local continuation now reviews the deterministic runtime/migrator identities and install-configured Job, applies that exact authority infrastructure state with lost-response recovery, and validates an exact Ready Job and immutable Execution through the existing sql-test seam. It binds the complete terminal proof and refuses a partial authority phase, ambiguous execution history, changed provider inputs, or cleanup substitution. This is fixture-backed orchestration evidence only: no live authority Job ran, no SQL authority phase changed in GCP, and the later migrate, prepare, bootstrap removal, protected fence, and steady-state proofs remain open.

Twelve free network/API control-plane objects remain under a revision-bound cleanup receipt while temporary serverless and deleted-producer references expire. The cleanup can only delete that reviewed remainder. The USD 25 monthly budget remains an alerts-only guardrail—not a hard spending cap—and no Cloud SQL, Cloud Run Job, VM, GKE, Artifact Registry image, KMS key, or other cost-bearing test resource remains.

The main cell remains gated on the complete Cloud SQL release gate, zero-state network cleanup, the reviewed install-to-steady runtime/migrator authority split, managed-envelope readiness, and hosted recovery. The reviewed decision, public commitment, bootstrap receipt, and implementation slices are recorded in Platform issue #197 and PR #200.

The experience

1. Open an existing Folderbase in the App.
2. Choose Connect to Cloud once.
3. Keep working from Finder, Terminal, an editor, or an agent harness.
4. Folderbase coalesces rapid writes into stable checkpoints in the background.
5. Verified bytes become durable before Cloud publishes the new Folderbase Version as the one Remote Head.
6. Another owner device receives the change and updates its ordinary local folder automatically when the change does not conflict.

Local writes never wait for the network. Closing the App window does not stop the restart-safe background sync service. The App reports states such as Saving locally, Uploading, Applying changes, Needs attention, and Up to date instead of claiming success from a placeholder or an event hint.

V0: Content & Stories

The first pilot is deliberately focused: a normal folder of small content and planning files used actively by a person and their agents.

Content & Stories/
├── Drafts/
│   ├── agent-workspaces.md
│   └── founder-story.md
├── Published/
│   └── launch-note.md
├── Research/
│   ├── interview-notes.md
│   └── sources.csv
├── Assets/
│   └── cover.svg
└── editorial-calendar.json

The completed one-device local-cell checkpoint proves the engine can capture, publish, restart, edit, republish, and settle the generalized folder without touching its source. The final V0 product proof still uses two owner Macs as equal writers:

• an edit on device A reaches device B without a manual push;
• an edit on device B reaches device A through the same path;
• a network interruption never blocks local work;
• a restart resumes from durable state without duplicate publication;
• different-file edits converge automatically; and
• same-file divergence preserves both versions and appears as one scoped item that needs attention.

The generalized V0 acceptance sequence is:

Device A                 Folderbase Cloud                 Device B
   │  stable local edit          │                            │
   ├─ capture + verify ─────────▶│                            │
   │                    publish Remote Head                  │
   │                            ├─ verified change ─────────▶│
   │                            │                    apply locally
   │◀──────────── verified Device Cursor / Up to date ──────┤

If either process or network connection stops, local editing continues. The durable journal resumes the same work; it does not manufacture a second canonical publication from a lost response.

One-device V0 checkpoint passed

On August 29, 2026, the generalized folder passed twice through a native PostgreSQL 16.10 and exact MinIO local cell running on disposable storage. The pilot verified:

• the descriptor-bound source byte and metadata snapshot was identical before and after the run;
• every managed candidate and referenced immutable byte matched exact Core evidence;
• Remote Head advanced from revision 1 to revision 2 after one stable edit;
• Device Cursor reached revision 2;
• restart returned AlreadyCurrent instead of publishing again;
• the final local journal had equal observed and settled generations and projected Up to date; and
• the per-run PostgreSQL schema, object bucket, keys, marker, services, and disposable pilot scratch were cleaned and attested absent.

This proves the one-device local engine and durable provider composition. It does not yet prove live GCP, Device A to Device B application, bidirectional convergence, conflict handling, or the V1 full-folder scale boundary.

Logical two-Device hosted bootstrap passed locally

The next checkpoint proves the one-way bootstrap sequence with two distinct logical Devices and an independent authority process:

• the logical MacBook publishes mixed Markdown and opaque bytes as one exact Core Version and Remote Head revision 1;
• client-side envelope encryption keeps plaintext and the Device credential away from the provider;
• a committed upload with a lost response is adopted without a second signed PUT or duplicate Remote Head;
• the logical Mac mini starts from an absent destination, downloads and decrypts the exact immutable generations, reconstructs the same Core Version, and records its Cursor only after exact Core verification; and
• restart, late revocation, corrupt ciphertext, wrong roots, and existing destinations fail closed without publishing a false destination or Cursor.

This narrows the gap to a physical V0 run, but it is not that run. Live IAM/GCS, production Identity and KMS, authenticated Cloud Run completion, an edit made on the Mac mini flowing back to the MacBook, automatic conflict handling, and the full V1 folder are still unproven.

V1: Full personal operating system

The second pilot expands the exact same model to a large, mixed folder with active repositories and opaque binary formats.

Personal OS/
├── Content & Stories/       # the complete V0 Folderbase boundary
├── Career/
│   ├── profile.docx
│   └── opportunities.xlsx
├── Projects/
│   ├── product-app/         # active Git working tree
│   └── research-database.sqlite
├── Media/
│   ├── demo.mov             # large opaque bytes; metadata first
│   └── screenshots/
└── Operations/
    └── planning.pdf

All regular file types remain supported as ordinary bytes: Markdown, source code, CSV, spreadsheets, PDFs, SQLite databases, images, audio, and video. Folderbase does not pretend every format can be text-merged. Conflicting opaque files keep both versions for explicit resolution.

Git working trees require Git-aware reconstruction rather than naïvely syncing .git internals. Reconstructable dependency trees and transient files such as node_modules, build output, editor locks, and disposable agent worktrees can be excluded by reviewed policy. A large file can be inventoried by metadata before its bytes transfer, but Keep Local never silently evicts local work.

V1 reuses the V0 engine rather than introducing a separate “large workspace” mode. The scale gates are explicit:

• inventory hundreds of thousands of entries without reading large payloads;
• synchronize valuable mixed files while excluding only proven reconstructable dependency and build state;
• resume large verified objects while small documents continue;
• preserve active Git working state without live-mirroring .git internals;
• treat nested Folderbases as independent sync/security boundaries; and
• remain responsive during rapid agent refactors and disposable worktrees.

Delivery ladder

How this differs from drive sync

Folderbase still uses familiar sync-engine safety baselines: authenticated devices, encrypted transport, immutable object storage, bounded retries, checksums, recoverable deletions, retention policy, audit records, and explicit per-folder sharing. Humans and agents remain first-class participants, but an ordinary local CLI agent is not interrupted by a second Folderbase permission prompt after the operating system has already granted folder access.

What follows the owner-sync MVP

The two-device private owner-sync pilot is the trust gate. After it passes, the same verified foundation can add scoped Live Folder sharing, recipient materialization, a third owner device, Cloud Agent workspaces, optional Archive, and File Provider integration. Those later surfaces must not weaken the local folder or create a second synchronization authority.

For the currently released local workflow, start with the five-minute quickstart and capture local versions.