Skip to content

ops: Unity project persistence + save cadence (LFS + autosave cron + on-boundary save) #1617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
100yenadmin wants to merge 2 commits into
base: main
Choose a base branch
from
+47 −3
Open

ops: Unity project persistence + save cadence (LFS + autosave cron + on-boundary save) #1617

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2b2475d
ops: Unity project persistence + save cadence (box git-LFS setup, aut…
Jul 16, 2026
2a05864
ops: correct LFS caveat — initial 6.3GB push SUCCEEDED (account has b…
100yenadmin Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 45 additions & 3 deletions docs/OPERATIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,46 @@ Spend the cheapest instrument that answers the question (tier table + honest sig
building the eval IS the next task. Escalate to the owner ONLY genuine taste/priority/business
calls — and bring a recommendation.

## Unity project persistence — the box is the renderer's source of truth (owner-ratified 2026-07-16)

The GEX44 Unity project (`/home/unity/worldos-unity` on `root@46.4.26.123`) is the ONLY copy of the

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Remove the tracked GEX44 SSH endpoint

This tracked operations doc now embeds the GEX44 root SSH endpoint even though the repo’s own box guidance keeps connection refs operator-only (AGENTS.md says GEX44 connection refs belong in ~/.openclaw/secrets/gex44.env, and WorldOS-GUI-RUNBOOK.md:367 says to never put the endpoint in tracked docs). For public or broadly shared repo copies, this exposes the host address and login user that the existing policy intentionally keeps out of source control; use the existing secret/env reference instead.

Useful? React with 👍 / 👎.

renderer's scenes, prefabs, shaders, camera rig, animator wiring, and the 10 purchased asset packs.
It is NOT the WorldOS git repo — it is its own repo (`100yenadmin/worldos-unity-2026-06-30_07-21-47`,
private). A 2026-07-16 audit found it **242 files dirty, last commit 15 days stale, remote empty** —
i.e. every scene/anim/shader change since #1433 lived only on the box's working disk. That is fixed;
do not let it regress.
Comment on lines +136 to +141

@coderabbitai coderabbitai Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Clarify “ONLY copy” to mean the only live/editable source.

The same section documents an off-box tarball copy later, so “ONLY copy” is literally contradictory and may confuse recovery decisions. Use wording such as “only live/editable working copy” or “primary active source.”

Confidence: 99%.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/OPERATIONS.md` around lines 136 - 141, Update the GEX44 Unity project
description to identify it as the only live/editable working copy or primary
active source, rather than the “ONLY copy.” Preserve the existing details about
its contents, repository separation, audit findings, and protection against
regression.


**Git LFS is ON** (set up 2026-07-16). `.gitattributes` routes binary asset classes
(`*.fbx/.glb/.png/.tga/.psd/.exr/.wav/.dll/.unitypackage/…` + the extensionless
`Assets/StreamingAssets/worldos_actors` bundle) through LFS; `.gitignore` excludes build artifacts
(`Library*/`, `AssetBundles/`, `Logs/`, `Temp/`, `obj/`, `*.bak/`). The box has the owner's push
credential stored (`~unity/.git-credentials`, mode 600). **Never commit `Library/` or re-add the
`*.bak` dirs** — they were the bulk of the historical bloat.
Comment on lines +143 to +148

@coderabbitai coderabbitai Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -eu
pwd
fd -H -t f '^\.gitattributes$|^\.gitignore$|worldos-unity-save\.sh$' .
rg -n -C3 'filter=lfs|StreamingAssets/worldos_actors|Library|AssetBundles|Logs|Temp|obj|\.bak' \
  -g '.gitattributes' -g '.gitignore' .

Repository: electricsheephq/WorldOS

Length of output: 4823

🏁 Script executed:

#!/bin/bash
set -eu

printf 'PWD=%s\n' "$(pwd)"

echo '--- .gitattributes (relevant lines) ---'
sed -n '1,120p' .gitattributes

echo '--- .gitignore (relevant lines) ---'
sed -n '1,160p' .gitignore

echo '--- worldos_actors / Library / AssetBundles / Temp / obj / bak references ---'
rg -n 'worldos_actors|Library\*|AssetBundles|Logs|Temp|obj|\.bak|git-credentials|~unity' .

echo '--- path match probe ---'
python3 - <<'PY'
from pathlib import PurePosixPath

patterns = [
    "extensions/renderers/unity/**/*.fbx",
    "extensions/renderers/unity/**/*.glb",
    "extensions/renderers/unity/**/*.png",
    "extensions/renderers/unity/**/*.tga",
    "extensions/renderers/unity/**/*.psd",
    "extensions/renderers/unity/**/*.exr",
    "extensions/renderers/unity/**/*.wav",
    "extensions/renderers/unity/**/*.dll",
    "extensions/renderers/unity/**/*.unitypackage",
]
candidate = "Assets/StreamingAssets/worldos_actors"
print("candidate:", candidate)
for pat in patterns:
    # very rough glob sanity: prefix/suffix only
    print(pat, "=>", candidate.startswith("extensions/renderers/unity/"))
PY

Repository: electricsheephq/WorldOS

Length of output: 50381

🏁 Script executed:

#!/bin/bash
set -eu

printf 'PWD=%s\n' "$(pwd)"

echo '--- .gitattributes (relevant lines) ---'
sed -n '1,120p' .gitattributes

echo '--- .gitignore (relevant lines) ---'
sed -n '1,160p' .gitignore

echo '--- worldos_actors / Library / AssetBundles / Temp / obj / bak references ---'
rg -n 'worldos_actors|Library\*|AssetBundles|Logs|Temp|obj|\.bak|git-credentials|~unity' .

echo '--- path match probe ---'
python3 - <<'PY'
from pathlib import PurePosixPath

patterns = [
    "extensions/renderers/unity/**/*.fbx",
    "extensions/renderers/unity/**/*.glb",
    "extensions/renderers/unity/**/*.png",
    "extensions/renderers/unity/**/*.tga",
    "extensions/renderers/unity/**/*.psd",
    "extensions/renderers/unity/**/*.exr",
    "extensions/renderers/unity/**/*.wav",
    "extensions/renderers/unity/**/*.dll",
    "extensions/renderers/unity/**/*.unitypackage",
]
candidate = "Assets/StreamingAssets/worldos_actors"
print("candidate:", candidate)
for pat in patterns:
    print(pat, "=>", candidate.startswith("extensions/renderers/unity/"))
PY

Repository: electricsheephq/WorldOS

Length of output: 50381

🏁 Script executed:

#!/bin/bash
set -eu

echo '--- .gitignore ---'
cat -n .gitignore | sed -n '1,220p'

echo '--- repo paths ---'
rg -n 'worldos_actors|git-credentials|Library\*|AssetBundles|Logs|Temp|obj|\.bak' .gitattributes .gitignore docs/OPERATIONS.md

Repository: electricsheephq/WorldOS

Length of output: 7196

Fix the OPERATIONS.md LFS/ignore claim
docs/OPERATIONS.md:143-148 describes safeguards that are not present in the repo config: .gitignore does not exclude Library*/, AssetBundles/, Logs/, Temp/, obj/, or *.bak/, and .gitattributes only applies LFS rules under extensions/renderers/unity/**, not Assets/StreamingAssets/worldos_actors. That gap misleads operators into trusting protections that do not exist; either update the doc to match the actual rules or add the missing patterns. Confidence 91%.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/OPERATIONS.md` around lines 143 - 148, Update the OPERATIONS.md section
describing Git LFS and ignore safeguards to accurately reflect the repository’s
actual .gitignore and .gitattributes rules, removing unsupported claims about
root-level Unity paths and the extensionless worldos_actors bundle. Do not claim
protections outside the configured extensions/renderers/unity/** scope unless
the corresponding repository rules are added.


**Save cadence (how often — automated + on-boundary):**
- **Autosave cron (installed on the box, runs as `unity`):** commit-if-dirty every 4h
(`17 */4 * * *`), commit + best-effort LFS push daily (`12 3 * * *`), via
`/home/unity/worldos-unity-save.sh` → `~unity/worldos-autosave.log`. It skips a tree whose source
changed in the last 90s (never captures a mid-write Unity state). The LOCAL commit is the primary
save and always succeeds; the push is best-effort (starts working the moment LFS quota + creds are
green). This is the safety net — it is NOT a substitute for boundary saves.
Comment on lines +151 to +156

@coderabbitai coderabbitai Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Define the release gate when the best-effort LFS push fails.

The policy says the push may fail because of quota while the claim checklist says to run --push and then release. Explicitly require verification that the local commit succeeded, then state whether a failed LFS push is logged/escalated but still permits release—or blocks release. Also avoid promising that local commits “always succeed”; disk-full, permission, hook, or process failures remain possible.

Confidence: 96%.

Also applies to: 168-172, 264-268

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/OPERATIONS.md` around lines 151 - 156, Update the Autosave cron
documentation and the corresponding claim-checklist sections to remove the
guarantee that local commits “always succeed.” Require verifying that the local
commit completed successfully before release, and explicitly define whether a
failed best-effort LFS push is logged/escalated while still permitting release
or instead blocks release; keep this policy consistent across all referenced
sections.

- **On-boundary save (every agent, every box session):** after any scene edit / prefab change /
animator or camera-rig change / shader edit / asset import / player build, run
`sudo -u unity /home/unity/worldos-unity-save.sh --push` before you release the box. A render or
build session that changed the project MUST end with a save — treat "did I save the box?" as part
of box claim-queue etiquette (§ Box claim-queue).
- **Off-box backup (weekly, or before any risky box op — Mac/agent-initiated):** the box can't reach
LEXAR, so pull a working-tree tarball to the primary drive from the Mac:
`ssh …@box 'tar --exclude=worldos-unity/Library* --exclude=worldos-unity/.git --exclude=worldos-unity/AssetBundles -czf /home/unity/worldos-unity-backups/worktree-<date>.tgz worldos-unity'`

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Fix the backup tar command to run from /home/unity

When agents follow the documented root@... box connection, this SSH command runs tar from the login user's home, but the Unity project is documented as /home/unity/worldos-unity. Because the archive operand is relative (worldos-unity) and the command neither cds nor uses tar -C /home/unity (confirmed via tar --help: -C, --directory=DIR changes directory), the weekly/risky-op backup will fail with a missing path or archive the wrong tree, leaving the advertised off-box disaster backup absent while LFS pushes are over quota.

Useful? React with 👍 / 👎.

then `scp` it to `/Volumes/LEXAR/Codex/worldos-unity-backups/`. This backup does NOT depend on
GitHub quota — it is the disaster floor if the box disk dies.

**LFS quota reality:** the tracked binary payload is ~7.4 GB — over GitHub's 1 GiB free LFS tier, so
the daily push needs a paid LFS data pack on the `100yenadmin` account (~$5/mo per 50 GB, covers
storage + bandwidth) OR the payload trimmed. Until that's resolved the local commits + off-box
Comment on lines +168 to +170

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Correct the LFS billing/quota guidance

This guidance says the 7.4 GB payload is over a 1 GiB free tier and needs a paid 50 GB data pack, but current GitHub billing docs list Free/Pro/org accounts as including 10 GiB of LFS storage/bandwidth and state that prepaid data packs have been removed in favor of metered billing (https://docs.github.com/en/billing/concepts/product-billing/git-lfs). In the common Free/Pro/org account case this can make operators believe pushes are blocked and ask the owner to buy a product that no longer exists, instead of checking the actual account plan/budget.

Useful? React with 👍 / 👎.

tarball are the live save story; the push retries harmlessly and logs its failure. This is an owner
billing decision — see the box's `worldos-autosave.log` for push state.

## Definition of "you are done for now"

There is no "done" — there is the next gate. A session ends cleanly when: the claimed issues are
Expand Down Expand Up @@ -221,9 +261,11 @@ tracker issue before any box op; release (comment) when done.** Concretely:
near-mechanical when it starts (see `qa/evidence/dungen-spike/BOX-DRIVE-RECIPE.md` for the
pattern: "repo-side is DONE + green; this is the ready-to-run box phase"). Don't idle-poll for
the box to free up — do the next repo-side unit of work instead, and check back when you need it.
- **Claim, do the bounded op, restore, release.** On the box: `chown -R unity:unity` any files you
touched, `ctrl+r` (refresh Unity), restore the scene you found, THEN comment release on the
claiming issue. Restoring state is part of the op, not optional cleanup.
- **Claim, do the bounded op, restore, SAVE, release.** On the box: `chown -R unity:unity` any files
you touched, `ctrl+r` (refresh Unity), restore the scene you found, **then if the op changed the
project (scene/prefab/anim/shader/import/build) run `sudo -u unity /home/unity/worldos-unity-save.sh
--push`** (§ Unity project persistence), THEN comment release on the claiming issue. Saving the box
is part of the op — the 4h autosave cron is only a safety net, not a substitute.
- **The Built-in-RP note:** the box's Unity project is **Built-in Render Pipeline, not URP.**
Shader/material work that assumes URP (Shader Graph particle materials, certain post-effects)
needs a repoint step for this box (e.g. `RepointHovlMaterials`, PR #1515/#1525) — check the
Expand Down
Loading