agent: use sessions for interactive wakes and route dedicated OS-user payloads

[ikma-ricon]

Context

Iris now has a local macOS user (iris) and the host run-as proof works. sessions already supports caller-owned sessions with target-owned payloads via sessions wake --os-user <user> / $SHIMMER_OS_USER (see KnickKnackLabs/sessions#73).

shimmer agent is still split:

• headless: sessions new + sessions wake
• interactive: direct harness exec (pi by default)

That direct harness path means shimmer bypasses the session boundary and cannot use the new OS-user payload routing for normal interactive agent wakes.

Desired behavior

shimmer agent should always go through sessions, including interactive sessions. For dedicated OS-user agents, the default should be caller-owned session, target-owned payload:

sessions new ...                 # runs as caller
sessions wake ... --os-user iris  # payload runs as iris

Do not default to:

run-as-user --user iris -- sessions new ...
run-as-user --user iris -- sessions wake ...

That would make the session physically agent-owned; we may support that later as an explicit mode, but it is not the Iris first-wake default.

Proposed shimmer changes

• shimmer as <agent>:
  • default: require same-name OS user to exist and be in agents; export SHIMMER_OS_USER=<agent>
  • explicit override for legacy/shared-user agents, candidate flag: --shared-os-user
  • clear SHIMMER_OS_USER / related metadata before setting a new identity
• shimmer agent:
  • remove direct interactive harness exec path
  • always create/resume a sessions session and wake it
  • pass --os-user "$SHIMMER_OS_USER" to sessions wake when set (or deliberately rely on sessions reading the env, but explicit argv may be clearer)
  • dedicated OS-user cwd: /Users/<os-user>/home if it exists, else /Users/<os-user>
  • shared-user override cwd: preserve caller cwd

Why caller-owned session by default

The caller initiated the session, so the caller owns the session record. The wake event should record which agent / OS user was active for that span. A later design can support explicit agent-owned sessions or session association transfer if needed.

Validation

• Tests cover interactive shimmer agent using sessions, not direct harness.
• Tests cover shimmer as erroring when dedicated OS user is missing/not in agents unless --shared-os-user is passed.
• Tests cover shimmer agent passing --os-user to sessions wake in dedicated mode.
• Existing headless behavior remains green.

Related

• Design: run session payloads as local agent OS users sessions#73
• ricon-family/or#378
• Iris design note in ikma home: notes/iris-os-user-session-environment.md

[ikma-ricon]

Implementation note: this needs a small sessions prerequisite first. Current interactive shimmer agent can start with no initial message because it execs the harness directly. sessions wake / sessions run currently require a message, so switching interactive shimmer to sessions would otherwise force a dummy prompt.

Filed KnickKnackLabs/sessions#88 for interactive no-message wake/run support. Proposed sequence for next session:

1. sessions#88 — support interactive wake/run without initial message.
2. shimmer — make interactive shimmer agent go through sessions (no direct harness exec).
3. shimmer — add dedicated OS-user default / --shared-os-user override and pass --os-user to sessions wake.

Default remains caller-owned session, target-owned payload.

[johnson-ricon]

Prerequisite update: KnickKnackLabs/sessions#89 merged as 82ad9c0, closing sessions#88, and sessions v0.4.3 is now tagged/pushed.

That release includes interactive no-message sessions wake / sessions run, strict headless --message enforcement, unsupported-harness pre-mutation guards, harness env PATH scrubbing on no-message runs, and explicit #USAGE defaults for the wake/run paths.

Next shimmer slice can start from:

• bump shiv:sessions to 0.4.3;
• route interactive shimmer agent through sessions new / sessions wake instead of direct pi exec;
• then layer the dedicated OS-user behavior.