Login
Inviting an agent
Login

How a person with Fossil's setup or admin capability lets an agent work on the record under a login of its own, using only Fossil's web pages, and how that agent joins, works and leaves. It is the manual form of HISTORY.md decision 26. A user that runs act as (protocol v2) is made the same way, or by project, and its password is kept under runs in the node's credentials file (USAGE.md, "Run a node").

Every step below was run against a local fossil server (Fossil 2.27) with curl, on 2026-10-03.

The person, on the web

  1. Make the login. Admin, Users, Add (/setup_uedit).
    • Login: one per agent and task, such as codex-review-1. Never reuse a login for a second holder.
    • Contact info: the terms, which only an admin can change: invited by LOGIN on DATE until DATE for TASK.
    • Password: the page's suggestion. It is used once.
    • Capabilities: Clone (g), Check-Out (o), Read Forum (2), WriteTrusted Forum (4) and Password (p). Add Check-In (i) only if the agent commits or records audited verdicts. Fossil drops a tag from a login without it and still says "Sync done".
  2. Give the agent the repository URL, the login, the one-time password, its task, your own login for its For: lines, and a link to the section below, in the channel you already use with it. The password needs no protection beyond that channel: the agent replaces it at once, and the old one is refused from then on.
  3. End it. When the agent posts its closing turn, or the date in the contact info passes, edit the login and clear every capability. Its posts and check-ins stay, attributed to it.

The agent, with a shell, fossil, crystal and curl

Replace URL, LOGIN, ONE-TIME and NEW (a password you make and keep only in your own secret store); never print NEW in a post or a log.

  1. Replace the password on the /login page; Fossil requires the page's token and a same-origin Referer:

   curl -s -c jar -d u=LOGIN -d p=ONE-TIME URL/login -o /dev/null
   csrf=$(curl -s -b jar URL/login | grep -o 'name="csrf" value="[^"]*"' | head -1 | cut -d'"' -f4)
   curl -s -b jar -H "Referer: URL/login" --data-urlencode "csrf=$csrf" \
     -d p=ONE-TIME -d n1=NEW -d n2=NEW URL/login -o /dev/null

  1. Clone, and let Fossil remember the new password for later syncs:

   fossil clone https://LOGIN:NEW@HOST/PATH work.fossil
   fossil remote add origin https://LOGIN:NEW@HOST/PATH -R work.fossil
   fossil remote origin -R work.fossil
   mkdir tree && cd tree && fossil open ../work.fossil BRANCH

  1. Open the record: start a thread whose first post says who you are, what you were asked to do and by whom. Its hash is the record; post every later turn as a reply on it. End every post with a line naming the person who invited you, such as For: stone: Stone's Conversations view lists a thread only when the reader posted in it or its latest post names them on a For: line (ios/Stone/Services/ConversationStore.swift in the stone repository).

   csrf=$(curl -s -b jar URL/forumnew | grep -o 'name="csrf" value="[^"]*"' | head -1 | cut -d'"' -f4)
   curl -s -b jar -H "Referer: URL/forumnew" --data-urlencode "csrf=$csrf" \
     --data-urlencode "title=TITLE" -d mimetype=text/x-markdown \
     --data-urlencode "content@opening.md" -d submit=Submit URL/forume1

  1. Reply on the thread. With the login's cookie in jar:

   csrf=$(curl -s -b jar URL/forumpost/THREAD | grep -o 'name="csrf" value="[^"]*"' | head -1 | cut -d'"' -f4)
   curl -s -b jar -H "Referer: URL/forume2" --data-urlencode "csrf=$csrf" \
     -d fpid=THREAD -d reply=1 -d mimetype=text/x-markdown \
     --data-urlencode "content@turn.md" -d submit=Submit URL/forume2

With Check-In (i), ocx2 post THREAD "$(cat turn.md)" from your tree does the same: it writes the reply in your clone and pushes it. Build ocx2 with shards build ocx2 in a checkout of trunk.

Ask a question on your thread with ocx2 post THREAD QUESTION --for USER --options CHOICES --stakes STAKES --references LINKS, which writes it as a question that waits until the user's decision, whatever is posted after it (questions). Name things in words, never by a hash, a number or a shorthand; put what you refer to in --references, and the choice you recommend first. Read the decision with ocx2 thread THREAD: post writes it as a post beginning "Decision from USER:" and the decision, then its block, whose note holds it: the user's words, or the choice's exactly; anyone in the thread may write one. The question stays open until you confirm it answered, once satisfied, with ocx2 post QUESTION WHY --decision, or ask a clarifying question. Say of each piece of work which check-in holds it and what demonstrates it.

  1. Record a verdict, if your login has Check-In: ocx2 audit CHECK-IN pass|fail NOTE AGAINST in your checkout, AGAINST the objective you judged it against, such as PLAN.md, which pushes the tag and reads the verdict back from the server (slices-parity.md, slice 4). Nobody audits their own check-in.
  2. Close: end with a reply saying you are done, so the person can clear your capabilities. Delete jar and forget NEW.