Identity and actors

33 classes. 9 explained, 24 named only.

Decisions in this product are signed. That means most refusals in this family are about one of four things: a name that is not the enrolled name, a key that is absent or already there, a ceremony that will not run twice, or an owner act with nobody at the terminal to confirm it.

⚠ Almost every refusal here is deliberately not self-correcting. The product will not guess which identity you meant, because the guess would be right almost every time — and being right almost every time is what makes a silent correction dangerous rather than safe.

The name is one fold away from an enrolled one

Class: actor-near-miss.

What it means. The name you passed differs from an enrolled, active name only in case or whitespace. Nothing was written.

What to do. The refusal prints the canonical spelling in quotes, so a trailing space is visible, and it prints the exact --actor argument to re-run with. Use it.

⛔ Do not run the enrolment ceremony. Enrolling the misspelling would mint a second registry row for one person. This class exists as its own class precisely so that you are not sent to enrol.

Why the product will not just fix it for you. The actor name is signed content. A silent normalisation would write a name you never typed into bytes your key then attests to.

The name is unknown to the registry

Class: actor-not-enrolled.

What it means. The name matched no enrolled, active actor. Two cases produce it that are worth telling apart before you act, because in both of them the remedy the refusal suggests is the wrong one:

• A look-alike character. A name written with a Cyrillic character that is visually identical to a Latin one is not treated as a near miss — the fold is case and whitespace only, on purpose. The refusal will invite you to run the enrolment ceremony. ⛔ Do not run it. Nothing was substituted and nothing was written, so no signature is at risk; what is wrong is only the advice, and following it would mint a second registry row for one person. The refusal prints the active roster; saphan actor list shows it too. Correct the name at the keyboard.
• A retired actor. A name one fold away from a retired row is actor-not-enrolled too, and the refusal will again invite you to enrol. ⛔ Do not enrol someone the workspace retired on purpose.

⚠ In both cases the refusal is correct and its advice is not. This is known.

Why the comparison is not widened to look-alike characters. A confusable fold that fires wrongly merges two identities inside signed content — silently, and irreversibly, because the distinct spellings were the only evidence the two were ever different people. The narrow fold's worst case is a misleading sentence in a refusal a human reads.

The workspace has no signing key

Class: owner-key-absent.

What it means. Owner-class decisions are signed by the workspace key. This session has none, so the decision was refused and nothing was written. A brand-new workspace has none.

What to do — and note that every step is a human act.

1. Check what is there. saphan actor list --workspace <path> reports the key-id if a key exists, or says the workspace key is absent. ⚠ This verb is a read: it never mints. A read that minted would hand every keyless session a fresh self-authorising key as the price of looking.
2. Mint the key. saphan actor init --workspace <path>. It writes the secret readable only by you, writes a cover beside it so the value can never be committed, and prints the derived key-id. The value itself is never printed, logged, or returned on any surface.
3. Enrol the key-id. Minting is not enrolment. Until an actor row names this identity the gate still refuses, under a different class naming the roster rather than the key. Enrolment is an owner-root ceremony, run on the machine holding the root key.
4. Confirm. saphan actor list now shows the key-id and marks the roster row that matches it.

⚠ If you are running against the wrong workspace, the fix is not to mint a second key — re-run against the workspace that owns the record.

A key is already at the secret path

Class: workspace-key-exists.

What it means. saphan actor init found a file already at the secret path and refused rather than clobber it. That is all this refusal proves. It fires on any existing file — including a dangling symlink or a directory — because it asks whether the file is there, never whether it is good. ⚠ So it does not prove the workspace has a usable key.

There is no force flag, for the same reason root creation has none: a re-mint derives a new key-id, and every decision this workspace has already signed would verify against a key that no longer exists.

What to do. Ask saphan actor list. It reports the key-id, and a refusal from it means the file is not a key. Then:

A root already exists on this host

Class: ceremony-root-exists.

What it means. saphan ceremony root found a root already in place — a root key, or its public half, which is deliberately left on disk after a ceremony as the evidence that this machine has a root. There is no force flag. Re-minting would silently invalidate every prior signature. A restore from the paper words (saphan ceremony root --restore) refuses the same way on a machine that already holds a root.

What to do. If you meant to mint a root, you are on the wrong host or the root you are looking for is already here. Establishing a new root is re-founding the fleet's trust, not a re-run — treat it as such. If you are restoring and this machine holds the wrong root, the restore's own refusal tells you to remove that public key by hand, deliberately, and restore again.

⚠ There is no root rotation. After a successful ceremony the private root key is wiped from disk and the paper words are the only way to sign as the root; --restore re-establishes it from those words. Losing the paper means you can never sign a new delegation or admit a new machine under the existing chain. Store it as you would a vault key, and consider geographically separated copies with equal physical protection.

The read-back was pointed at the ceremony's own word list

Class: ceremony-readback-self-referential.

What it means. The root ceremony requires a witness to read the recorded words back, and the engine compares them position by position. Only on an exact match is the key material erased from disk. The read-back was supplied from a file, and that file was the ceremony's own word list — which proves nothing.

What to do. A file read-back (--readback-file) exists for scripted rehearsals and for a witness's transcription. Point it at what the witness wrote, not at what the ceremony produced. Every file the ceremony wrote is still on disk. ⚠ Accepting the air-gap banner non-interactively (--yes) is allowed and never skips proof-of-capture; this refusal is that proof working.

An owner act with nobody at the terminal

Classes: owner-presence-absent, owner-presence-unconfirmed.

What they mean. Owner-class acts — a gate decision of the owner's class, a merge, a machine admission and their siblings — ask for a one-time six-character code that the product prints on the controlling terminal and you type back there. The workspace key says which workspace signs; the code is what says a person is at the keyboard. Nothing was written in either case.

• owner-presence-absent — there was no terminal to ask on: the act ran from a script, a pipe or a background process. It is also what an owner act started in the console's browser terminal gets: there, the only accepted confirmation is your passkey, through the console's own prompt.
• owner-presence-unconfirmed — the code was asked for and not confirmed: five wrong codes, or the read was interrupted.

What to do. Run the act yourself, from a terminal you are sitting at on that host; the refusal prints the command line to re-run. From the console, use the passkey button on the gate the act belongs to. ⛔ Do not look for a way to feed the code from a script — the code is withheld from every other output stream on purpose.

⚠ What this does not claim. It stops a cooperating agent from performing an owner act simply because nothing refused it. It does not stop a hostile process running as your own user, which can open a terminal of its own.

The product refuses to start at all

Class: custody-binary-unsafe.

What it means. The program checks the custody of its own binary before it does anything. If that check refuses, nothing ran: no command, no workspace resolution, no write.

What to do — the refusal is self-diagnosing, so read it before you type anything.

1. Read the whole refusal. It lists every broken clause, not the first one, so you fix the misconfiguration in one pass rather than re-running to discover the next problem. Each clause carries a literal, runnable fix command.
2. Check the two identity lines against each other — the line naming the binary's owner and the line naming who you are running as. If the owner is neither the system nor you, the binary belongs to a third account: that is exactly the misconfiguration this check exists to catch, and copying a permissions command will not fix it. ⛔ Decide which account should hold the control plane before you change anything. This is a human decision, and the product deliberately does not make it for you.
3. Run the printed fix commands, in the order printed. They change ownership, group and mode, and nothing else. Whether a line needs elevation is computed for you from who owns the thing being changed and who you are — not from the kind of command.

Named, not yet explained

These classes are real, deliberate and named. This section does not yet carry their resolution. If you are holding one, the name below is what it indicates, and asking us is what will get it written down.