Open Files

What the Open Files activity is, when it appears, and what your two action buttons actually do.

When to use this

• You started a sentient or node switch and the app pushed an unfamiliar list-of-files screen instead of the spinner
• You want to understand which subsystem is holding the hive open and why
• You're deciding whether Force continue is safe in your situation

For the conceptual background — what an identity switch does and why open files block it — see Identity Switching.

Why it exists

When you switch sentient (or in some cases switch node), the IdentitySwitchService runs the §SP-8a Save → Teardown → Mount cascade. Teardown unmounts the encrypted volume. If a process inside the app still has an open file handle beneath that mount, the unmount either fails or — worse — succeeds while the open handle points at freed memory, risking SIGSEGV.

To prevent that, the service runs OpenFileTracker::filesUnder(mountPath) before Save. If the tracker reports any open handle beneath the affected mount, the service:

1. Pauses the switch (no Save runs yet — your previous identity is still fully alive)
2. Pushes OpenFilesActivity listing every tracked file
3. Hands the decision to you

This is §SP-8c.2's "detection at switch time" — the per-subsystem dirty-flag probe of §SP-8b doesn't catch in-memory open handles, so a separate tracker is needed.

What you'll see

OpenFilesActivity is a table view, one row per open file. Columns:

The activity has two buttons.

Cancel switch

Pops the activity, abandons the in-flight switch, leaves you on your previous identity. Always safe. Pick this if you're not sure what's holding the hive open.

Force continue

Iterates every tracked entry and calls the owning subsystem's forceClose(path) callback. If the owner registered with a callback (the §SP-8c.4 contract), it gets a chance to flush its in-memory state to disk before its handle releases. If the owner registered without a callback (legacy code paths still being retrofitted under §OF-3), the handle releases at the OS level with no flush — anything dirty in that owner is lost.

After every entry is closed, the service proceeds with Save → Teardown → Mount.

When Force continue is safe

When in doubt, Cancel switch and resolve the open handles manually, then retry.

Reach it as a diagnostic

OpenFilesActivity also runs in a diagnostic mode — same table, different two buttons — when reached from the Hive Lobby's Open files entry. This lets you inspect the tracker without an in-flight switch:

• Close handles — same as Force continue but doesn't proceed with a switch (because there isn't one)
• Close — just pops the activity

Use this when something feels wrong and you want to see what the app is holding open right now.

Troubleshooting

The activity shows a row but I have nothing visible open. A subsystem that opens files at startup may register without you knowing. Common culprits: the audit DB (opal-history.db), discovery's cache, courier blob writers from a recent transfer. The row is normal; pick Force continue if all rows are read-only.

The activity shows an empty list but the switch still pauses. Shouldn't happen — file a bug. The probe runs after a Save-pending check, so a non-empty result is the only thing that should push this activity.

Force continue completed but the next switch still surfaces the same row. The owner's forceClose callback didn't actually release the handle. File a bug with the owner subsystem name; the §SP-8c.4 contract requires release-on-callback.

Related