[twilightsaurus]

Scope

Slice 26 PR 1 only: TinyFugue onboarding and startup integration. Based on main at 8a2007972c0a78a738749ada05b8a517d5ac8e5b / v0.4.1. Do not merge until reviewed.

Problem

The installer rejected a missing default startup file, appended the capture hook after possible connection/login commands, and called textual hook presence "configured" without verifying the active TinyFugue invocation.

Changes

• Prompt for an explicit existing startup path only when the default is absent and stdin/stdout are terminals. Explicit --tf-startup never falls back or prompts. Validate regular-file status, current ownership and read/write access before installation mutations.
• Prepend new hooks before original commands only for the bounded, safely inspectable command format; preserve original bytes/newline style, inode ownership and permissions, with unique original-content backups.
• Preserve existing canonical, indented, absolute/same-file and supported one-level literal nested hook loads. Do not relocate existing hooks. Warn about duplicates and unresolved order.
• Leave legacy world-list, BOM and recognized unsupported/computed include cases unchanged with manual instructions. Legacy guidance avoids switching the TinyFugue loader mode before world definitions. No unrestricted parser or login-macro rewriting.
• Report insertion, exact-line preservation, equivalent/nested preservation and manual-required uncertainty separately. Always require confirmation that the actual invocation (including tf -f FILE) loads the selected file before connection/login.
• Explain manual reload for running TF sessions and checkpoint-based recovery without promising identity that was never captured.
• Extend the existing real-installer harness and frozen acceptance expectations. Cover PTY selection, invalid explicit paths, spaces, early placement, LF/CRLF/no-final-newline content, equivalent/nested hooks, repeated installation and exact byte/metadata restoration after failure.
• Update README/deployment/TinyFugue walkthroughs. Record Slice 26 In progress with all five bounded items; leave Slice 25 Complete.

Verification

• Focused real-installer onboarding regression passed before frozen bundle build, including final reviewed edge cases.
• scripts/build-server-bundle.sh: passed with the pinned uv-managed interpreter; no release versions changed.
• test-installer-connections.py --tf-startup-only <frozen bundle>: passed under the host-Python execution guard.
• Complete test-installer-connections.py <frozen bundle> matrix: passed, including legacy upgrades, signal/rollback and connection ownership acceptance.
• test-frozen-server.py <frozen bundle>: passed; real frozen relay/feed/gateway/action-consumer flow, isolated native user-systemd units, kernel denial of host Python/pip.
• Native TinyFugue restart/checkpoint/consumer-ownership acceptance passed using TFLIBDIR=/home/tai/src/tinyfugue/lib/tf and /home/tai/bin/tf.
• Native startup smoke observed imp_capture_gmcp already defined at the first original command in the installer-modified startup file; TF exited 0. The local native binary emitted sanitizer diagnostics in tfio.c:900 and variable.c:945; these are not suppressed or claimed fixed.
• npm run check, shell syntax and git diff --check: passed. The gate includes formatting, documentation references, release-version consistency, types, component tests, end-to-end behavior and production build.

Limits and retained scope

The all-purpose test-server-bundle.sh was attempted but could not complete here: host loopback 8787 returns EADDRINUSE without a visible Linux listener. A private-network/user-namespace attempt bypassed that port conflict but the Direct credential safety check rejected remapped home-directory ownership. Installer-specific frozen acceptance and native frozen-runtime acceptance passed separately; no claim of a complete all-purpose bundle run.

Runtime invocation, arbitrary nested/macros execution, and existing-hook order remain operator-confirmed. No live VPS/NAT VM/public Caddy/certificate/credential/DNS changes, protocol changes, GMCP normalization changes, CHANGELOG edits or release-version edits.

Subsequent Slice 26 PRs retain: warning before discarding saved Direct credentials; NAT preflight error classification; recovery of exact-owned inactive legacy edges without gateway.env; remaining installation documentation/completion-message corrections.