fix(files): keep the pod's own S3 uploads out of the sync guard (CLEAN-115)

[maksymhryzodub-prog]

Jira: CLEAN-115

Rebased onto main after #110 (CLEAN-112) merged. Root version bumped to 0.3.63.

Problem

While an agent runs, the Files tab shows an amber "Agent copy is newer (HH:MM) — Sync now" pill at all times, and every Sync after the first LLM call opens "Overwrite newer files in S3?" listing data/usage.json, a file nobody touched from Ranch.

The runtime's fs.watch pusher (30 s debounce, always on with S3_BUCKET) uploads every local change: usage.json on each LLM call, memory, sessions. The CLEAN-50 guard only compares LastModified against max(lastSyncAt, lastPullAt − 60 s), so the pod's own upload is indistinguishable from a console edit. Spec 008 R1 described the bridle sync event as the only push path and missed the watcher.

Change

API

• Every S3 write Ranch makes into an agent prefix (console save, agent tool, import, skill sync) carries object metadata origin=ranch (RANCH_ORIGIN_METADATA). Template copies via CopyObject stay untagged on purpose: they land before the boot pull and are never newer than the baseline.
• IFileGateway.wasWrittenByRanch(agentId, path) — one HeadObject, false when absent.
• SyncGuardService.assess keeps only tagged objects among the newer-than-baseline candidates. Files at or below the baseline are not looked up. The agent tool sync_agent_files shares the guard and benefits automatically.
• Tool description, 409 ApiResponse and SyncConflictDto.atRisk text say "edited from Ranch"; swagger + admin/app SDK regenerated (doc comments only).

Admin

• Pill: neutral "Agent running since HH:MM · Sync now" instead of the amber "Agent copy is newer". Tooltip explains that the pod pushes its changes within ~30 s and Sync is the full-push safety net.
• 409 dialog: "edited from Ranch (console, chat tools or import) after the running agent last took its copy".

Docs

• specs/008 research.md R8: the watcher, the fix, and the residual risk only the runtime can close (a Ranch edit to a file the pod rewrites itself is overwritten by the next watcher flush; hardening = runtime tags its uploads and/or heads before overwriting).
• specs/017 quickstart.md step 6 updated.

Twin console check

app/slices/agent has no file sub-slice and no reference to lastPullAt/copyPill, so nothing to mirror there. app only received the regenerated SDK doc comments.

Verification

• jest src/slices/agent/file src/slices/bridle: 31 suites, 422 tests green, including the new file.gateway.origin.spec.ts (metadata on saveRaw, putObjectRaw, syncSkills; wasWrittenByRanch true / false / absent) and three new syncGuard.service.spec.ts cases.
• nest build, generate:swagger, admin/app build:api, nuxt typecheck (admin) — clean.
• Not run manually against a live pod. To check (quickstart step 6): after an LLM call, Sync must not open the overwrite dialog for data/usage.json; a file saved from the console while the agent runs must still trigger it. Note that objects written before this deploy carry no tag, so a pre-deploy console edit is treated as a pod upload until it is saved again.

🤖 Generated with Claude Code