sysadmin-chronicles/OPEN_ISSUES.md

SYSADMIN CHRONICLES — OPEN ISSUES

Version 2.0 | Last updated: Phase 1 skeleton build

All known design gaps, content bugs, and deferred decisions. Items here must NOT be implemented with a best-guess — wait for a resolution. Mark items RESOLVED with the fix details when closed.

---

AGENT INSTRUCTIONS (READ FIRST)

Added during Phase 1 skeleton build. Document any decisions you make here.

When you resolve an open issue:

1. Move it to the RESOLVED ISSUES section at the bottom.
2. Add resolution details and the file(s) changed.
3. Update ROADMAP.md to mark relevant tasks complete.

When you make a minor direction change (non-game-changing):

1. Note it here under NEW DECISIONS.
2. Update the relevant doc (ARCHITECTURE.md, SAVE_SYSTEM.md, etc.)
3. Do NOT silently patch content files — note it here first.

CODE QUALITY AUDIT — COMPLETE All P1, P2, and P3 items from docs/CODEX_AUDIT_FIXES.md have been resolved. docs/CODEX_AUDIT_FIXES.md has been deleted per its own WHEN DONE instruction.

---

NEW DECISIONS (Made During Phase 1 Build)

ND-001 — T005-T008 bundled file needs split (same as OI-008 pattern)

The file T005-T008.json is a bundled array. Content loader expects one file per ticket with an "id" field. It has been kept as-is (content loader skips arrays). Split into T005.json–T008.json before Phase 5 ticket loading is implemented.

ND-002 — OI-006 (persists: false) already resolved in SAVE_SYSTEM.md v1.3

SAVE_SYSTEM.md v1.3 defines shift-boundary reset. SaveState.js implements the reset_shift_flags() equivalent at shift start. Closed.

ND-003 — OI-007 (Q002 blast_radius) safe to fix mechanically

Q002-syntax-error.json blast_radius: ["I001"] should be []. Mechanical fix — the next agent can apply it directly without asking. See OI-007.

ND-004 — Stack is Node.js + Svelte

The game runs as a Node.js/Express server with a Svelte web HUD. The workstation is a real XFCE VM (sc-workstation). All game logic lives in server/src/.

ND-005 — opsbridge/sudo SSH path for host→workstation validation

The validation path from the host uses the opsbridge management user then sudo -H -i -u player inside the guest, because Q001 intentionally removes /home/player/.ssh/authorized_keys. The correct form is:

ssh opsbridge@<guest> sudo -H -i -u player -- sh -c '<command>'

Separated sudo flags (-H -i -u) required — combined -Hiu misparses on some builds.

Status: RESOLVED — confirmed working in ValidationEngine.js SSH path.

ND-006 — build_machine snapshot chain now materializes baseline.post-q006 from Q006 clean state

tools/setup/seed-vms.sh now builds sc-build-machine in two authored stages: Q006-prep.sh creates the broken baseline.clean state for "Time Is A Flat Circle", and Q006-post-clean.sh applies the clean branch outcome before taking baseline.post-q006.

Q008 is still a separate multi-VM provisioning gap. Its authored starting state touches both vulcan and hermes, so it should not be guessed into the single-domain snapshot chain until that flow is designed explicitly.

ND-007 — terminal UX: Tilix is the player's terminal (no in-game simulation)

Status: RESOLVED. The player uses a real Tilix terminal inside the workstation XFCE VM. All terminal UX (history, scrollback, copy/paste) is handled by Tilix. No terminal simulation needed. See docs/WORKSTATION_POLISH_BACKLOG.md for outstanding workstation desktop polish items.

ND-008 — vulcan player shell/PATH is still misprovisioned

Status: RESOLVED 2026-04-24. Root cause: inetutils (provides /usr/bin/hostname on Arch) was not in the build-build-machine.sh pacman install. Hermes (Debian) has hostname pre-installed. Fix applied in tools/vm/build-build-machine.sh:

• Added inetutils to the runcmd pacman install line.
• Added runcmd entries to write /home/player/.bashrc (explicit PATH) and .bash_profile (sources .bashrc), then chown to player. Regression gate added to tools/setup/seed-vms.sh (STEP 1b): after builds, SSH-tests hostname on sc-web-server and sc-build-machine; fails fast if missing.

---

MUST RESOLVE BEFORE PHASE 3

OI-001 — Q001 permissive-setup branch contradictory logic

File: content/quests/Q001-welcome-aboard.json Option A: bad-but-not-fatal permissions (755 dir), quest completes with warning. Option B: fatally wrong permissions (777), quest does NOT complete via this branch. Decision needed: Which option? Status: RESOLVED — permissive-setup branch (Option A/lenient) was already correctly implemented. Q001 branch validates file_exists + file_owner without checking mode, so 755 directory case completes the quest with trust_delta 0. marcus-Q001.json already has complete-permissive stage.

OI-002 — Q008 rollback-only vs rollback-and-pin have identical validation

File: content/quests/Q008-bad-upstream.json Need a distinguishing rule for pinned vs unpinned. Likely an IgnorePkg entry in /etc/pacman.conf (detectable via file_contains). Status: RESOLVED — Q008 already has file_contains check for IgnorePkg in /etc/pacman.conf on rollback-and-pin branch, and a not-rule on the rollback-only branch to ensure mutual exclusion. Confirmed in Q008 internal_notes.

---

MUST RESOLVE BEFORE PHASE 5

OI-003 — Incident files I002 and I003 are missing

Author I002-backup-pressure-recurrence.json and I003-app-update-recurrence.json following the I001 pattern before Phase 6. Status: RESOLVED — both files authored (content/incidents/I002-backup-pressure-recurrence.json, I003-app-update-recurrence.json). Content validator passes zero errors.

OI-004 — pressure_profile field is referenced but never defined

Recommend: separate files in content/pressure_profiles/ with a defined schema. Status: RESOLVED — created content/pressure_profiles/ with web_outage_escalation.json and app_outage_escalation.json. Schema uses trigger_after_seconds steps with notification, notification_severity, and escalate_linked_ticket fields. escalate_linked_ticket resolves to the quest's own ticket_id at runtime.

OI-005 — check_mode: explicit trigger mechanism undefined

A "Verify Fix" button in the ticket panel UI, shown per-objective when check_mode == explicit. Status: RESOLVED — Verify Fix button implemented in TicketsPanel.svelte. Button appears per-objective when check_mode == explicit, disables during check, re-enables with 2s delay on failure.

---

LOW PRIORITY / ANYTIME

OI-007 — Q002 blast_radius incorrectly references I001

Fix: change blast_radius: ["I001"] to blast_radius: [] in Q002. Status: RESOLVED — blast_radius set to [] in Q002-syntax-error.json; _blast_radius_note added explaining I001 triggers only from Q003 quick-fix branch.

OI-008 — tier2-dialogue.json naming convention

Individual files exist: marcus-Q005.json, marcus-Q006.json, marcus-Q008.json, priya-Q007.json. The bundled file is kept as tier2-dialogue.SPLIT_PENDING.json. Verify individual files are complete then delete the SPLIT_PENDING file. Status: RESOLVED — individual files confirmed present. Bundled file removed.

OI-009 — sarah-web series has only one member

sarah-Q003-angry.json declares series_id: "sarah-web" but no second member exists. Either add sarah-Q004+ or remove series_id until a second file is authored. Status: RESOLVED — series_id and series_position removed from sarah-Q003-angry.json. Series grouping deferred until a second sarah-web member is authored.

OI-011 — Snapshot baseline chain

seed-vms.sh implements the chain. Need formal policy in QUEST_AUTHORING.md. Chain: workstation: baseline.day-one; web_server: clean→post-q002→post-q003→post-q004; build_machine: clean→post-q006. Each post-qXXX baseline from CLEAN branch resolution. Status: RESOLVED — Baseline Snapshot Chain subsection added to docs/QUEST_AUTHORING.md in VM PROVISIONING HOOKS section. Documents chain per VM, the clean-branch-only rule, and naming convention.

---

RESOLVED ISSUES

OI-006 — persists: false flag semantics

Resolution: Shift-boundary reset handled in SaveState.js at shift start.

OI-010 — file_absent and file_owner_is_not undocumented rule types

Resolution: Added to ValidationEngine.js as full rule types. Still needs: update QUEST_AUTHORING.md rule reference table.

OI-012 — SSH execution contract

Resolution: server/src/lib/ssh.js — Promise-based, structured result (stdout/stderr/exitCode), BatchMode key-based auth, 30s default timeout.

OI-013 — Language choice

Resolution: Node.js + Svelte. See ND-004.

---

ADDITIONAL RESOLUTIONS (Phase 1 continued)

OI-003 — I002 and I003 incident files authored

Resolution:

• I002-backup-pressure-recurrence.json authored — triggers on hermes_backup_partial flag, 3-step escalation, resolves when cron+ownership+disk all correct.
• I003-app-update-recurrence.json authored — triggers when rollback-only branch taken on Q008, re-installs broken version unless pinned. Resolves when IgnorePkg + correct version confirmed.
• Content validator now passes zero errors.

ND-001 — T005-T008 split complete

T005.json, T006.json, T007.json, T008.json created from the bundled file. Content validator now loads all 8 tickets correctly.

OI-007 — Q002 blast_radius fix

Resolution: The validator was fixed to normalize world_flags.json array format. The Q002 blast_radius: ["I001"] issue is documented — apply this one-line fix directly: change blast_radius in Q002-syntax-error.json from ["I001"] to [].

VALIDATOR FIXES applied this session:

• validate-content.js now normalizes world_flags.json array format correctly
• Advisory clue_fingerprint rule types (service_state_is, file_size_above, etc.) are now accepted — they describe evidence, not runtime-evaluated rules
• T005-T008 bundled file is now skipped correctly (SPLIT_DONE suffix)
• WorldFlags handling now normalizes both Array and Dict flag formats

CONTENT STATUS: validate-content.js exits 0 (zero errors, 2 warnings)

Warnings are all expected and documented:

• priya-ops series: 1 member (needs future dialogue)
• T005-T008.SPLIT_DONE.json: skipped (bundled file, split done) (sarah-web series warning removed — series_id stripped from sarah-Q003-angry.json per OI-009) (tier2-dialogue.SPLIT_PENDING warning removed — renamed to .SPLIT_DONE.bak per OI-008)