xlsx-win v2: sandboxed-agent-to-desktop-user-session handoff is untested and undocumented

[dachent]

Parent: #33
RFC: #32, amended by RFC 0002

Background

The v1 skill's SKILL.md was explicit that a Codex/agent sandbox often cannot create Excel.Application via COM (wrong Windows logon/session context), and provided a specific handoff pattern: run the shared Office preflight (office_com_preflight.ps1), and if it reports can_use_com = false, hand the actual Excel COM step off to scripts/invoke-xlsx-win.ps1 run from a signed-in desktop-user PowerShell window instead of the sandbox.

Every real Excel test performed across this entire v2 effort (#36, #39, #70-#72, and the v2 cutover in #80) ran directly from a Claude Code session's own Bash/PowerShell tool execution -- and every one of them succeeded: real Excel.Application COM creation, real refresh/recalc/save, zero 0x80070520/"class not registered"/"retrieving the COM class factory" errors, zero orphaned processes. That is itself a concrete, positive data point, not silence -- but it only proves that this specific deployment mode (Claude Code CLI, tool execution inheriting the interactive desktop user's own logon session) is not at risk. It does not test the thing v1's guidance actually worried about: a genuinely different, more restricted session -- a non-interactive Windows service account, a scheduled task set to "run whether user is logged on or not," an RDP session left in Disc state, or a cloud/headless agent sandbox that isn't the interactive desktop session at all.

No v2-era equivalent of the old preflight-and-handoff pattern has been designed, and (until this update) this issue didn't spell out what a real test of the negative case would actually require. This was surfaced during the SKILL.md cutover pass (#80) and documented there as a known open question, not fixed as part of that cutover.

What "fully testing this" actually requires, and why

A same-session, same-account re-run (what's already been done, repeatedly, throughout #36/#39/#70-#72/#80) can only ever reconfirm the positive case. To get a real negative-case data point -- the only thing that would actually validate or retire v1's original concern for v2 -- requires two distinct Windows session contexts to compare, not one:

1. The interactive desktop user session -- already proven to work; this is the baseline.
2. A genuinely different, more-restricted session -- this does not currently exist on this machine as a separate thing, and creating one is real work, not a config toggle:
   • Simplest option: a second local Windows user account (non-elevated, distinct from the interactive desktop user), used to run the built supervisor either via runas /user:<otheraccount> from a non-interactive context, or via a Scheduled Task registered under that account with "Run whether user is logged on or not" checked (this is the logon type that actually reproduces the wrong-session COM failures v1's error-kind mapping documents -- an ordinary second interactive login, by itself, usually does not).
   • Alternative: an RDP session deliberately left Disconnected (matches query session's Disc state, the same session-state precondition this repo's own docs already flag as a hard precondition for Office COM automation) while the supervisor is launched against it.
   • Alternative: a genuinely headless/non-interactive agent runtime (a cloud or CI-hosted agent sandbox, as opposed to Claude Code CLI on an interactive desktop) -- if and when this skill is ever run from one of those, that run is the test; nothing needs to be manufactured.

Why this can't be done unattended, by the agent, from inside this session: creating a new Windows local user account, or registering a Scheduled Task under a different account's credentials, is a system/account-configuration change -- outside what this agent should do without a human with admin rights explicitly setting it up (or authorizing it). This agent also cannot self-elevate in this non-interactive session (the same limitation hit earlier in this project for installing the .NET SDK). So this is not "untested because nobody got around to it" -- it is untested because the negative-case test genuinely needs infrastructure (a second account/session) that has to be provisioned by whoever has admin rights on the target machine, not conjured by an agent call.

Scope

• Provision a second, genuinely-restricted session per the options above (repo maintainer / whoever has admin rights on the target machine -- not something to automate).
• From that session, attempt to launch the built XlsxWinSupervisor.exe directly, and separately via control_plane/cli.py run against a trivial job manifest (no Power Query needed -- open -> recalc -> save_as on a synthetic workbook is enough to prove or disprove COM creation).
• Capture whatever failure actually surfaces (or the fact that it succeeds) verbatim -- don't assume it matches v1's old 0x80070520/"class not registered" categories; confirm empirically.
• If a genuine failure reproduces: design and document the v2-era equivalent of the old preflight-and-handoff pattern -- most likely a precondition check inside cli.py run (or a new standalone cli.py preflight subcommand) before it ever attempts to launch the supervisor, giving a clear, actionable error and pointing at running from an interactive desktop session instead, mirroring what .shared/office-com/scripts/office_com_preflight.ps1 already does for the v1-era skills.
• If it does not reproduce (e.g. because the C# supervisor's COM activation path behaves differently than the old PowerShell scripts', or because whatever session it's launched from turns out not to matter the way v1 assumed): document why, with the actual evidence, and close this out as "checked, doesn't apply" rather than leaving it open indefinitely on an unverified assumption.

Trigger to act on this

Parking this deliberately, not indefinitely-by-default. Pick it back up when either:

• This skill is actually deployed via something other than an interactive Claude Code desktop session (a headless/cloud agent runtime, a scheduled/service-account execution path, CI), or
• A real, reproduced COM/session failure is observed in practice (a confusing crash instead of a clear message is exactly the failure mode this issue exists to prevent).

Until one of those happens, this stays a documented, deliberately-untested gap -- not a blocker for anything currently shipped.

Acceptance criteria

• A documented, empirically-tested answer (not an assumption) to whether the built supervisor works when launched from a session that is genuinely not the interactive desktop user's own session.
• If a handoff/preflight pattern turns out to be needed, SKILL.md and xlsx-win/README.md describe it concretely, the same way the v1 skill's guidance did, with the actual error signature(s) observed.
• If it turns out not to be needed, that conclusion is recorded here with the evidence, not just assumed from the fact that Claude Code's own session happened to work.