Share and resume to S3, an S3-compatible endpoint, or a folder

[akesling]

Adds S3 (and any S3-compatible endpoint, and plain folders) as a share
destination alongside Pathbase, configured once instead of per call.

path auth s3 login                      # credentials, if you're using a bucket
path target ~/Dropbox/toolpath-traces   # a folder — no credentials needed
path target s3://my-bucket/traces       # or a bucket; checked before it's stored
path share                              # → wherever you pointed it
path target                             # what's in effect, and why

path share --to /tmp/scratch            # override for one call
path share --to pathbase

path resume ~/Dropbox/toolpath-traces   # lists what you've shared, pick one
path resume s3://my-bucket/traces/2026-08-07-fix-the-parser-claude-abc.json

Where shares go

One setting in one place: default_target in ~/.toolpath/config.json.
Not inside either credential file — if each backend's own config could
claim to be the default, "where does my next share go?" becomes a
precedence puzzle the day a third backend appears.

path target is a top-level verb rather than a subcommand of auth,
because it's a persistent setting and it isn't authentication.
path auth s3 keeps the credentials, which genuinely are.

Resolution: --to → $TOOLPATH_SHARE_TARGET → the stored target →
Pathbase. Nothing is inferred from which credentials happen to exist: a
share that silently changes destination is a data-egress bug, not a
convenience. The one guard sits at the bottom — with S3 credentials
stored, no Pathbase session, and no target set, share refuses rather
than falling through to the anonymous public Pathbase endpoint.

The Pathbase-only flags (--anon, --repo, --public, --url,
--name) select Pathbase on their own, overriding an object target;
pairing one with an explicit object --to is an error rather than a
silent resolution.

Targets are verified when set

Setting a target does what a share does — writes a small
.toolpath-access-check object, then removes it — and refuses to store
one that fails. A target is set once and used many times, so a wrong one
that survives costs a session pick and a derivation later, at the moment
you wanted a result rather than a setup step. A listing would only prove
s3:ListBucket, which isn't the permission a share needs.

--no-verify stores unchecked, for a bucket you haven't created yet or
a laptop that's offline; it prints (not verified) so the state is
visible. Folders take the same path, which also creates them.

Destinations you can read back out of

Documents land at <date>-<topic>-<cache-id>.json — e.g.
2026-08-07-add-s3-support-to-share-claude-6f2a1c9e.json. Every
component is a pure function of the document, so re-sharing a session
that grew overwrites its own object instead of leaving near-duplicates;
the date is the session's first step, so it doesn't move as the
conversation continues.

path resume <bucket|prefix|folder> lists the destination and offers a
picker — the counterpart to share's picker across every harness. Rows
are built from object names alone, so browsing a hundred shared sessions
costs one list request and zero downloads. A destination holding one
document skips the picker.

Two traps closed

• A bare relative target (my-bucket/traces) is rejected rather than
  quietly creating ./my-bucket/traces and reporting success. It's
  overwhelmingly a bucket name typed from memory; ./my-bucket/traces
  opts in explicitly.
• memory:// is rejected: a fresh per-process store, so anything
  "shared" there is gone before the command exits.

Implementation

Transport is the object_store
crate — one code path for AWS S3, any S3-compatible endpoint (R2, MinIO,
Ceph, B2), and file://. It adds 18 crates but no new crypto backend
(aws-lc-rs was already in the lock via rustls).

• store.rs splits where a document goes (Destination, ObjectUri,
  ObjectName — pure URL parsing and naming) from how to reach it
  (S3Settings at ~/.toolpath/s3.json, connection + credentials
  only, so one stored credential serves any number of buckets).
• target.rs sits above and owns the Pathbase-vs-object choice.
• Preflights cap timeouts and retries — object_store's default ten
  retries would otherwise multiply a 5s connect timeout into a ~50s
  stall — and its retry epilogue is stripped from user-facing errors.
• Config files under the config dir now share
  config::write_private_json / read_private_json, which own the
  0600-file / 0700-parent story.

Plumbing counterparts: p export object / p import object, both
aliased s3.

Testing

scripts/quality_gates.sh 8/8. 413 unit + 154 integration tests for
path-cli (was 358 + 121).

The folder backend isn't only a testing affordance, but it's what makes
the tests real: share and resume round-trip end to end through the
actual object_store code path with no network and no mock HTTP server.
Verification failures are tested deterministically offline by pointing
at http://127.0.0.1:1.

wasm32-unknown-emscripten still builds — the new modules are cfg-gated
like cmd_pathbase.

Note

path-cli and the toolpath-cli shim bump to 0.17.0. Nothing here was
released, so --s3 → --to and the s3.json shape changed freely
during review; there's no migration to write.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[github-actions]

🔍 Preview deployed: https://ace50488.toolpath.pages.dev