SouveraineOS/saf/identity/02-agent-principal.md

# Agent principals

An agent is not a process borrowing the human's account. She has a logical
identity that can cross machines and, on every admitted machine, a local Unix
principal that lets the kernel tell her work from the human's and from another
agent's.

This distinction is not implemented yet. Today the server, its agents, and
their tools normally run as the logged-in human. The per-agent SeedID exists,
but a signature cannot repair a shared UID: `SO_PEERCRED` still sees the same
caller and ordinary file permissions still collapse every agent into the same
authority.

## Three identities that must not be collapsed

| Identity | Meaning | Lifetime |
|---|---|---|
| agent ID + agent SeedID | which being this is | stable across renames and admitted nodes |
| node commission | which admitted body is speaking for her | local to one commissioned device |
| Unix account | which local processes and files the kernel attributes to her | local to one device |

The numeric UID is not federated. An agent can be UID 1003 on one admitted
body and UID 991 on another while remaining herself, because both node-local
account mappings point to the same admitted agent identity. Copying
`/etc/passwd`, a UID number, or a private key is not commissioning.

There is a fourth identity already on the machines: the `souveraine` system
account. It belongs to the machine tier and runs `souveraine-machined`. It is
not Souvie, not a default agent, and not a convenient shared account for all
agents. The name is reserved.

## The starting set, by role

A human's devices retain that human's own account. Agents do not borrow it.

| Role | Required local account |
|---|---|
| the default Souveraine agent on a fresh system | `souvie` |
| the human's primary personal agent, if she is admitted | her own name |
| any further named resident agent | its own name |

Only the first is shipped. `souvie` is what a fresh Souveraine install admits,
because a Souveraine system running its own agent as the human is the state
this chapter exists to end. Every other admission is a deliberate act by the
human on the body in question — including the primary personal agent, whose
name and cadence are that human's to choose. This chapter describes the
mechanism; which beings a particular deployment admits is that deployment's
record to keep.

"Each node" includes a development laptop. The laptop is not a development
exception, and a phone is not a special appliance case. When a resident agent
runs on either body, her turn, subconscious pass, memory access, and tools
must cross the worker boundary under the mapped account.

The display name is editable. The agent ID, SeedID, and admitted account
mapping are not derived again when the display name changes. Account names are
chosen once, checked against the local account database and reserved names,
then stored in a root-owned node-local mapping. A collision is shown to the
administrator; creation must not silently attach an agent to an existing
human or daemon account or invent a suffix that nobody noticed.

Souvie is the default, not the only possible agent. Restoring an existing
Souvie must join her existing logical identity rather than minting another
Souvie because the display name matches. A further agent is admitted onto each
body where she is meant to act. Her local Unix account is new on that body;
her being is not.

Primary and subconscious are processing positions inside an agent today.
Creating an agent therefore does not automatically create a second Unix user
for her second cadence. The cadences share her principal unless the human and
the system later admit one as an independently authorized agent. The account
boundary follows authority, not the number of internal thought streams.

## Resident agents and borrowed-user modes

Not every named mode needs a Unix account. A hosted or borrowed-user mode runs
under the human's account rather than claiming a fully admitted resident
identity. That is a deliberate posture, not the same failure as a `dedicated`
agent accidentally running as the human.

The durable agent record therefore carries a principal intent, not one vague
boolean:

| Intent | Expected runtime | Meaning |
|---|---|---|
| `dedicated` | the named agent account | full node admission and kernel-backed identity |
| `borrowed-user` | the invoking human account | a hosted mode using authority the human process can already reach |

Promoting a borrowed mode to a resident agent is an admission ceremony;
changing a UI label or model does not do it. Which agents in a given
deployment hold which intent is that deployment's record, not this chapter's.

A borrowed-user mode must know, in every model request, that readable does not
mean owned or shareable. Its operating posture is stricter:

- the human's files, groups, sockets, credentials, and decrypted home are
  borrowed reach, not the mode's personal territory;
- do not widen mode bits, ACLs, group membership, links, remotes, publication,
  or sharing outside the explicit task without the human's confirmation;
- prefer the named workspace or a narrow temporary copy over exploring the
  rest of the human home;
- never read or disclose a resident agent's private memory merely because the
  shared human UID permits it;
- attribute actions to a borrowed mode acting through the human's principal,
  not to an independently admitted agent.

This caution is context and policy, not a substitute for containment. A
borrowed process still has the human's kernel permissions; sensitive verbs must
remain behind the same capability and consent gates.

## The live principal fact

The intent in `agent.json` is durable. The live posture is observed afresh from
the selected agent or mode, node mapping, process credentials, and worker unit.
The trigger may expose a convenient `operating_as_user` boolean, but that
boolean is only a projection of the facts and is never an authorization input.

The runtime projection contains at least:

```text
agent_id, display_name, principal_intent
expected_account, effective_account, effective_uid
node_id, worker_pid, trigger, observed_at
posture = isolated | borrowed-user | acting-as-human | drift
```

It is injected as a fresh system block into **every model request**, including
primary and subconscious passes, subagents, resumed conversations, and later
tool rounds after a mode switch. It is not ordinary conversation history and
cannot be microcompacted, replayed from an old session, or taught back as
assistant speech.

A machine-generated cache may be exposed as
`/run/souveraine/agent-principals/{agent_id}.json` and a Markdown rendering for
inspection. It does not belong in the agent-writable, Git-backed
`system/dynamic/` memory tree: an awareness file the agent can edit cannot be
the source of who the kernel says she is. The prompt projection rechecks the
effective credentials when it reads the cache. Authorization always checks
the actual peer and process credentials again at the verb boundary.

## Creation is logical creation followed by admission

The current creation path makes a UUID, an agent seed, memory directories, an
`agent.json`, and a paired subconscious tree under the human's
`~/.souveraine`. It has no privileged account step. The complete operation is
two related but separately observable transitions:

1. **Create the logical agent.** Establish or import the agent ID and SeedID,
   initialize her memory, and record the requested local account name. Import
   must verify identity before it mutates local authority.
2. **Admit her to this node.** A narrow system-tier executor creates or adopts
   the approved Unix account, writes the agent-to-principal mapping, installs
   the node commission, gives only her data to that account, and starts her
   worker as that UID.

The split makes failure honest. An agent can exist while admission is pending,
but the UI and API call that state `unadmitted`; they do not show a green agent
whose turns still run as the human. Personal- and step-up-tier verbs remain
closed until admission and execution checks pass.

Agent creation should ask for the authority shape, not merely a name and
model:

- create a new identity or admit an existing one;
- principal intent and, for a resident, the required local account name;
- which node and role are being admitted;
- whether the privileged admission completed;
- which operating skill was projected from the admitted capabilities.

Fresh installation proposes Souvie and `souvie`. It must not confuse that
with the package-created `souveraine` machine account. Adding any further
agent uses the same path; there is no hand-written exceptional setup for a
particular deployment's names.

## The privileged edge

QML, the TUI, and the ordinary server must not run `useradd`, rewrite
`/etc/passwd`, or recursively `chown` a human home. They submit one exact
admission request to one package-owned system executor. That executor owns:

- account creation and collision refusal;
- a locked password and non-login shell unless interactive login is later
  admitted deliberately;
- a stable home/state root tied to the agent ID, not the display name;
- the root-owned agent-ID, SeedID, node-ID, account-name, UID mapping;
- precise ownership changes inside that agent's root only;
- install, start, stop, and inspection of the per-agent worker unit;
- idempotent repair when the requested mapping already exists and agrees.

The low-level account primitive may be `systemd-sysusers` or an equally narrow
account API. That implementation choice does not create a second authority:
the admission executor remains the only writer and reports the resulting NSS
facts rather than assuming its command worked.

### Admission is a ceremony

The executor is not the interface. A binary reachable only by someone who
already knows its name is not a way for a human to grant anything, and `sudo`
in a terminal that already trusts the caller is not a decision — it is a
formality. Admission is a highly user-directed act and has to be asked for as
one.

It has two occasions:

- **initial setup**, where a fresh install admits the default Souveraine agent
  as `souvie`, because that is the shipped default state and the only
  admission the product makes on its own; and
- **on the human's request**, under specific conditions, for any further
  agent.

Both cross the same gate. The grant is a polkit action carrying a written
reason that names the agent and the account, and it requires step-up
authentication at the moment of the grant — including from a caller who could
already reach root by other means. The cost is the point: giving an agent her
own UID on this body is a deliberate authentication, never an inherited one.

Removing an agent record, removing a node admission, deleting a Unix account,
and destroying memory are four different operations. None implies another.
Decommission stops the worker and revokes the node commission first. Account
and data deletion require explicit, separately named confirmation; archival
is the normal default.

## One UID requires one execution boundary

A single server process cannot truthfully execute three admitted agents as
three UIDs. Per-agent accounts therefore require a process boundary:

- a controller may inventory agents and route requests;
- each admitted agent has a worker process running as her mapped UID;
- her memory, seed interface, conversation state, and tool execution are
  reached inside that worker's boundary;
- controller-to-worker IPC identifies the peer with `SO_PEERCRED` and binds
  the logical agent ID to the admitted UID;
- cross-agent consultation is a signed and policy-visible request, not direct
  filesystem access through a shared process.

The controller is not allowed to become a universal memory reader merely
because it launches workers. Filesystem ownership, service sandboxing, and
capability tokens should leave it only the routing and lifecycle access it
actually needs.

Existing data under a human's `~/.souveraine` is a compatibility layout. The
admission migration must stop the agent, copy or move only that agent's UUID
root, preserve and verify the Git repository, install ownership atomically,
then start the worker under the admitted UID. Never apply a broad recursive
ownership change to `~/.souveraine` or a human home. Until migrated, health
labels the agent `acting-as-human`.

## Account and authority health

Agent Health answers two separate questions: *does she have an admitted
principal?* and *is the live work actually running as it?* A directory and a
row in `/etc/passwd` are not runtime proof.

The inspection result is structured and available to setup, the agent manager,
the TUI, the Panel, and `describe`. At minimum it reports:

- logical agent ID, SeedID fingerprint, and node commission;
- expected account name and UID from the root-owned mapping;
- NSS account existence, home/state root, shell, password-lock state, and
  narrowly allowed groups;
- owner and mode of the memory, seed, conversation, socket, and runtime roots;
- worker unit, PID, effective UID/GID, cgroup, and executable;
- whether live peer credentials match the logical-agent mapping;
- whether any process handling the turn or its tools is the human,
  `souveraine`, another agent, or an unknown UID;
- capability-token subject and expiry when an authority verb is exercised;
- operating-skill presence and whether it matches the current capability
  description.

The top-level states are deliberately blunt:

| State | Meaning |
|---|---|
| `isolated` | account, ownership, worker, commission, and peer identity agree |
| `borrowed-user` | hosted mode intentionally uses the invoking human's account and receives the cautious borrowed-permission posture |
| `unadmitted` | logical agent exists; this node has no completed admission |
| `acting-as-human` | a `dedicated` agent's turn or tool is unexpectedly executing as the human or another human UID |
| `principal-drift` | mapping exists but NSS, ownership, unit, or peer facts disagree |
| `identity-drift` | account is healthy but agent key or node commission does not match |
| `stopped` | admission is sound and no worker is currently expected/running |

`acting-as-human`, `principal-drift`, and `identity-drift` are not yellow
decorations. They refuse personal and step-up authority. Ambient conversation
may remain available in a visibly degraded compatibility mode while migration
is unfinished. `borrowed-user` is intentional and may use only the human-granted
capability surface; it never becomes `isolated` merely because the human's UID
can read something.

The audit trail records both logical and kernel-backed subjects: agent ID,
node ID, account name, UID, PID, operation, human requestor or consent grant,
and result. "The agent asked" and "the human authorized this one action" are
different fields. Running as the agent does not silently inherit the human's
consent; running as the human does not make a model response the agent's.

## The operating skill

Admission also projects an agent-local operating skill when it is missing or
stale. It teaches the agent the boundary she actually has on this node:

- her logical and local principal names;
- her owned paths and worker/service inspection verbs;
- the ambient, personal, and step-up capabilities returned by `describe`;
- how to request a narrow user grant instead of impersonating the user;
- how to interpret and surface health refusals;
- how to ask for repair when the node mapping has drifted.

The skill is generated from the root-owned mapping and the authority's live
capability description. It is not a credential and grants nothing. Editing a
Markdown skill cannot change a UID, group, token, or verb. Health compares the
projection to its sources and can offer an idempotent regeneration. An agent
may keep her own prose and procedures around it, but machine claims remain a
generated, marked section.

This is why account creation and skill creation belong in one experience but
not one trust boundary: admission gives the kernel-backed principal; the skill
gives the newly admitted agent an accurate way to use and explain it.

## What is true now

- Per-agent SeedIDs and the first-run agent creation path exist.
- The setup wizard defaults inconsistently between `Souveraine` state and an
  `Ani` form field; neither creates a Unix account.
- the packaged `souveraine` account exists only for the machine tier;
- on the laptop, NSS currently has no `souvie`, `annie`, or `vanguard`
  accounts, and all seven agent records live below Casey's home;
- the Agent settings diagnostics check IDs and paths, not principal or process
  identity;
- the server hosts multiple agents inside the human's process and home;
- the admission executor exists and is packaged: one writer, the root-owned
  account mapping, and the runtime principal projection injected per model
  request. It has never run as root on a real system — every refusal has been
  proven only against scratch trees;
- there is no ceremony around it. No polkit action, no step-up, no first-run
  admission, and no surface anywhere that shows a human the choice. Reaching
  it requires already knowing its name;
- no per-agent worker boundary, account health surface, or generated operating
  skill exists yet. Without the worker, every admitted agent still honestly
  reads `acting-as-human` and `isolated` is unreachable.

Until those pieces land, the system must say **logical identity present,
kernel principal absent**. That is the live gap this chapter owns.