Release v2.57.0

.changelog/v2.57.0.md

@@ -0,0 +1,37 @@
+# Release v2.57.0
+
+Released: 2026-09-03
+
+## Highlights
+
+**Rigging & 3D**
+- Generated 3D characters can now be auto-skinned to a rig with a measured weight-coverage gate, then have animation clips retargeted onto them with a compatibility contract and a motion proof, so imported motion doesn't visibly break on unfamiliar skeletons.
+- 3D models can be exported as USDZ, so they open directly in AR on an iPhone/iPad.
+- Image-to-3D gained a subject-framing control so limbs and extremities survive conversion, and Blender rigging now resolves through a fail-closed runtime resolver with a readiness probe instead of failing silently mid-job.
+
+**Code review & CoS agents**
+- Added OpenCode, Kimi, and MTPLX as selectable code reviewers, and reviewers now live under Models instead of a separate list.
+- `pr-reviewer` stage 3 can run on any enabled CLI/TUI provider (spawned headless), with a documented Claude sandbox recipe.
+- A fork PR's held CI run now releases only after the coordinator's own approval, never before — closing a gap where an untrusted fork's CI could run ahead of review.
+- A failed installer can now queue a CoS agent to investigate the failure automatically, and the merge-gate contract is verified before a completing agent tears down its worktree.
+- Numerous CoS/pr-reviewer robustness fixes: honoring a Stop signal mid Codex RPC, rescuing hook payloads from `output.txt` for direct CLI runs, keeping the sandbox-write fallback gated on a real `git apply` (not `--check`), retrying local code review without `reasoning_effort` when a model rejects thinking, and screening PRs for hidden/model-directed content instead of keyword co-occurrence.
+
+**Video generation**
+- FastH3 can now render directly from FastVideo's own checkpoint by converting its DiT locally.
+- Fixed FastMetal's picker showing the wrong download size, clamped FastH3 frame options to the pipeline's actual 5–15s window, and made `generate_fastvideo` importable on Python 3.9.
+
+**Onboarding & settings**
+- A fresh install now gets a first-run card that stages one PortOS slice end to end.
+- Added a Settings > Credentials page showing presence and source for configured credentials.
+- Generated assets are now stamped with their source model/LoRA licenses.
+- Scheduled-task cadences collapsed to a simpler On-Demand / Scheduled choice.
+- Local coding runtime is now recommended based on detected hardware.
+
+**Reliability & UX fixes**
+- Fixed a stuck-forever FLUX.2 venv health-check cache, boot schema DDL races across processes, worktree cleanup after a failed agent spawn, and object-URL leaks in ImageGen.
+- Mobile/UI polish: 44px tap targets on MeatSpace log-row icons, wrapping long tokens in `<pre>` blocks, clamping dropdown popovers to the viewport, and keeping long record names readable via a title tooltip.
+- App Management updates are now opt-in and route through the detached launcher with proper preflight guards, instead of running unannounced.
+
+## Full Changelog
+
+**Full Diff**: https://github.com/atomantic/PortOS/compare/v2.56.0...v2.57.0

.claude/skills/portos-socket-ui/SKILL.md

@@ -11,10 +11,10 @@ These are hard-won failure contracts from the Shell and CoS-agent views. Every o
 
 - **Single-subscriber socket resources need notify + recipient-relative advertise + filter + claim.** Some server-side resources (PTY shell sessions, etc.) intentionally store one attached socket and fan output to it. The contract: (1) emit `<resource>:detached` on the previous socket when a new socket takes over so the displaced client can drop its local view; (2) include an `attached: boolean` field on each list-entry payload, computed *relative to the recipient socket* (true only when bound to a different socket) — a globally-truthy `attached` makes a client's own sessions look unavailable to itself; (3) broadcast list updates from both attach AND detach paths; (4) auto-pick paths send `claim: true` and the server refuses to displace a different socket. Manual paths (tab click, deep-link URL) default to `claim: false` so explicit intent still wins. See `server/services/shell.js` for the canonical implementation.
 
-- **Pending socket-request tracking — `{ target, generation }` ref.** When a stateful socket operation is in flight, track it as `{ target, generation }` and increment `generation` on every change. Response handlers gate on strict equality with `target` — null/stale/cancelled all fall through, so a cancelled-mid-flight response can't re-activate after the user moved on. Deferred work (`setTimeout` fallbacks) captures `generation` and aborts if it advanced. Pair every cancellation path with explicit `cancelPendingAttach()`-style helpers rather than overloading a `clearActiveSession()` helper — clearing the displayed entity and cancelling an in-flight request are *separate* concerns, and conflating them cancels user-initiated switches when an unrelated session dies. See `client/src/pages/Shell.jsx` `pendingAttachRef` for the pattern.
+- **Pending socket-request tracking — `{ target, generation }` ref.** When a stateful socket operation is in flight, track it as `{ target, generation }` and increment `generation` on every change. Response handlers gate on strict equality with `target` — null/stale/cancelled all fall through, so a cancelled-mid-flight response can't re-activate after the user moved on. Deferred work (`setTimeout` fallbacks) captures `generation` and aborts if it advanced. Pair every cancellation path with explicit `cancelPendingAttach()`-style helpers rather than overloading a `clearActiveSession()` helper — clearing the displayed entity and cancelling an in-flight request are *separate* concerns, and conflating them cancels user-initiated switches when an unrelated session dies. See `client/src/hooks/useShellSession.js` `pendingAttachRef` for the pattern.
 
 - **Server-correlate every async response, then filter display.** When the server emits `<resource>:error` in response to a client request, include the original `sessionId` / request id in the payload so the client can match against its pending state. Drop stale errors silently and gate the red-error display on correlation — rendering before classification flashes noise in the UI for requests the user has already moved past (rapid tab clicks, expected `claim:true` race rejections). Passive errors against the currently-displayed resource (e.g. `shell:input` to a now-dead session) should still display, but must not mutate pending state.
 
 - **Distinguish intentional idle from passive idle.** A "no entity displayed" state can come from a user action (Stop / dismiss) or from passive circumstance (initial load found everything in-use elsewhere). Recovery branches that auto-adopt the next free entity must gate on a `userIdle*Ref` flag set by explicit user-clear paths and cleared by every user-initiated start/attach. The gate needs to cover every reconnect-triggered re-init path, not just the initial-load branch — a transient disconnect resets initialization flags, and an empty-list auto-start or survivor adoption can otherwise undo an explicit Stop on reconnect.
 
-- **Deferred work must respect both staleness and unmount.** Any `setTimeout`-scheduled side effect that emits to the network or mutates shared state needs two guards: (1) a generation counter check so user actions during the delay window abort it, and (2) a `mountedRef` so a navigation-away unmount stops it from firing into the void. Pattern: `const mountedRef = useRef(true); useEffect(() => () => { mountedRef.current = false; }, []);` — never reset to `true` (handles dev-mode double-mount cleanly). Without the unmount guard, a deferred socket emit can claim a resource (e.g. shell session) with no listener left to render it.
+- **Deferred work must respect both staleness and unmount.** Any `setTimeout`-scheduled side effect that emits to the network or mutates shared state needs two guards: (1) a generation counter check so user actions during the delay window abort it, and (2) a `mountedRef` so a navigation-away unmount stops it from firing into the void. Use `useMounted()` from `client/src/hooks/useMounted.js`; it re-arms on every mount, which StrictMode's mount-cleanup-remount cycle requires. Do not hand-roll the guard even correctly — `client/src/hooks/mountedRefConventions.test.js` rejects both a `useRef(true)` that is only ever set to `false` and any re-implementation of the hook. Without the unmount guard, a deferred socket emit can claim a resource (e.g. shell session) with no listener left to render it.

.env.example

@@ -25,16 +25,19 @@ PGPASSWORD=portos
 # Loopback HTTP port spawned when HTTPS is active so local curl skips the cert (default: 5553)
 # PORTOS_HTTP_PORT=5553
 
+# Port the Express server listens on (server/index.js; default: 5555 from lib/ports.js)
+# PORT=5555
+
+# VNC port the Remote Desktop broker connects to on this machine
+# (remoteDesktop.js; default: 5900). A non-numeric or out-of-range value falls
+# back to the default rather than failing.
+# PORTOS_VNC_PORT=5900
+
 # pm2 restarts portos-server when its RSS crosses this (memory-leak safety valve).
 # Default 4G fits small installs; raise it on a big-RAM workstation so a long
 # session / heavy SSE load doesn't cause spurious restarts (e.g. 32G on 128 GB).
 # PORTOS_SERVER_MAX_MEMORY=32G
 
-# Same ceiling for the Vite dev server (portos-ui). Default 1G — a dev server that
-# transforms modules on demand should sit well under that; raise it only if a huge
-# client tree makes Vite restart during normal editing.
-# PORTOS_UI_MAX_MEMORY=2G
-
 # Override the base URLs advertised to clients (auto-derived from PORTOS_HOST/PORT if unset)
 # PORTOS_API_URL=https://my-machine.ts.net:5555
 # PORTOS_UI_URL=https://my-machine.ts.net:5555
@@ -69,6 +72,12 @@ PGPASSWORD=portos
 # Chief of Staff runner endpoint (used when CoS runs as a separate process)
 # COS_RUNNER_URL=http://localhost:5558
 
+# Eidoverse world server endpoints (eidoverseWorld.js). The WebSocket URL defaults
+# to ws://127.0.0.1:<eidoverse port>/ws; the HTTP URL is derived from it unless set.
+# Point these at another host only when the world runs off-box.
+# EIDOVERSE_WS_URL=ws://127.0.0.1:8940/ws
+# EIDOVERSE_HTTP_URL=http://127.0.0.1:8940/
+
 # Active local LLM backend: "ollama" or "lmstudio" (chosen at setup time; managed in Settings → Local LLMs)
 # LLM_BACKEND=ollama
 
@@ -96,6 +105,11 @@ PGPASSWORD=portos
 # Maximum Grok image-generation runtime in milliseconds (default: 1200000 / 20 minutes)
 # GROK_TIMEOUT_MS=1200000
 
+# Maximum Grok VIDEO runtime in milliseconds (videoGen/grok.js; default: 1800000 /
+# 30 minutes). Video takes longer than an image, so this cap is separate from
+# GROK_TIMEOUT_MS — keep it above the 20-minute cloud-lane idle watchdog.
+# GROK_VIDEO_TIMEOUT_MS=1800000
+
 # Maximum Antigravity image-generation runtime in milliseconds (default: 1200000 / 20 minutes)
 # AGY_IMAGEGEN_TIMEOUT_MS=1200000
 
@@ -141,6 +155,11 @@ PGPASSWORD=portos
 # because a bare `bash` often resolves to WSL, which can't see drive paths.
 # PORTOS_BASH=/bin/bash
 
+# Python interpreter scripts/setup-image-video.sh uses as the venv base
+# (setupScriptRunner.js). An explicit value always wins; on Windows PortOS
+# otherwise auto-detects one, avoiding a conda base whose venv can't load torch.
+# PYTHON_BIN=/usr/bin/python3
+
 # Shell binary for interactive PTY sessions (the Shell page, agent TUI shells).
 # Auto-detected if unset: on Windows PowerShell 7, else Windows PowerShell, else
 # cmd.exe (last, because it can't reach another drive by anything you'd type —
@@ -171,9 +190,29 @@ PGPASSWORD=portos
 # Ollama context window size passed to new model loads (default: 32768)
 # OLLAMA_NUM_CTX=32768
 
+# Slotstream model cache directory override (slotstreamModels.js; default:
+# ~/.slotstream/models). The binary always lives in ~/.slotstream/bin.
+# SLOTSTREAM_MODEL_DIR=/path/to/slotstream/models
+
+# Abort a speculative-decoding model download after this many milliseconds with
+# no bytes received (specDecodeModels.js; default: 1200000 / 20 minutes). Raise
+# it for a slow Hugging Face/CDN handshake; a download still receiving bytes is
+# never cut off by this.
+# SPEC_DECODE_IDLE_STALL_MS=1200000
+
 # Video process grace period after output completion in milliseconds (default: 40000)
 # VIDEOGEN_COMPLETION_WATCHDOG_MS=40000
 
+# FFLF/ltx2 stage-2 pixel-frame budget (videoGen/renderArgs.js). Unset, PortOS
+# scales it to detected unified memory. Raise it on a big-memory box; lower it if
+# a render OOMs. This is the single cap both the worker and the client honour.
+# FFLF_LTX2_PIXEL_BUDGET=8000000
+
+# Megapixel ceiling for a local image regeneration render (imageGen/regen.js;
+# default: 2.0). The result is upscaled back to the source's exact dimensions, so
+# this bounds compute, not output size. Raise it on a high-memory machine.
+# PORTOS_REGEN_MAX_MP=2.0
+
 # Terminate an idle queued video job after this many milliseconds (default: 1800000 / 30 minutes)
 # MEDIA_JOB_WATCHDOG_VIDEO_MS=1800000
 
@@ -207,15 +246,42 @@ PGPASSWORD=portos
 # Automatic LoRA checkpoint resumes allowed after soft stalls (default: 2; 0 disables)
 # LORA_TRAIN_STALL_MAX_AUTO_RESUMES=2
 
+# Cap LoRA training quantization at this bit width (loraTraining/runtimes.js).
+# Only 8 or 4 are honoured; anything else is ignored and the memory-derived tier
+# stands. Set it to force a smaller quant on a machine whose auto-tier OOMs.
+# LORA_TRAIN_MAX_QUANT_BITS=4
+
 # Ingredient catalog revisions retained per ingredient (default: 50)
 # CATALOG_REVISION_RETENTION=50
 
 # LM Studio model id auto-installed for voice tool calling (default: built-in fallback chain)
 # PORTOS_VOICE_DEFAULT_TOOL_MODEL=lmstudio-community/Qwen2.5-3B-Instruct-GGUF
 
+# Signal Desktop install directory read by Signal sync (signalSync.js; default:
+# ~/Library/Application Support/Signal). SIGNAL_CONFIG_PATH and SIGNAL_DB_PATH are
+# derived from it, so relocating a Signal install usually only needs this one.
+# SIGNAL_DIR=/path/to/signal
+
 # Signal sync config file path (default: SIGNAL_DIR/config.json)
 # SIGNAL_CONFIG_PATH=/path/to/signal/config.json
 
+# Signal sync SQLCipher database path (default: SIGNAL_DIR/sql/db.sqlite)
+# SIGNAL_DB_PATH=/path/to/signal/sql/db.sqlite
+
+# Test/CI hook that supplies the "Signal Safe Storage" password instead of
+# shelling out to the macOS keychain (signalSync.js). Leave unset on a real
+# install — PortOS reads the keychain itself, and this would put a live
+# credential in a plaintext file.
+# SIGNAL_KEYCHAIN_PASSWORD=fake-keychain-password
+
+# macOS Contacts (AddressBook) directory read by contact sync (contactsSync.js;
+# default: ~/Library/Application Support/AddressBook)
+# CONTACTS_AB_ROOT=/path/to/AddressBook
+
+# macOS Messages database read by iMessage sync (imessageSync.js; default:
+# ~/Library/Messages/chat.db)
+# IMESSAGE_CHAT_DB=/path/to/chat.db
+
 # Privacy Center PII Vault encryption key — 32 bytes, hex (64 chars) or base64.
 # Auto-generated and appended to .env on the first vault write if unset. Back
 # it up: losing it makes every encrypted vault value unrecoverable.

.gitattributes

@@ -27,3 +27,18 @@
 *.woff2 binary
 *.ttf binary
 *.eot binary
+
+# Sorted catalogs and barrels: one line per module, so concurrent branches
+# conflict on the same insertion hunk. `union` keeps both sides;
+# scripts/catalog-merge-union.test.js catches a doubled or resurrected line
+# and pins this list to the barrel list in scripts/ci-test-plan.js. Rationale
+# and rules: AGENTS.md "Module Organization".
+server/lib/README.md merge=union
+server/lib/index.js merge=union
+client/src/lib/README.md merge=union
+client/src/lib/index.js merge=union
+client/src/hooks/README.md merge=union
+client/src/hooks/index.js merge=union
+client/src/utils/README.md merge=union
+client/src/utils/index.js merge=union
+client/src/services/README.md merge=union