Totebox session

@@ -0,0 +1,100 @@
---
schema: foundry-doc-v1
title: "Totebox Session"
slug: totebox-session
category: architecture
type: topic
quality: complete
short_description: "A Totebox Session is an AI-assisted contributor session opened within a single Totebox Archive — scoped to the archive's declared repositories, unable to write outside them, and the standard entry point for all development work in Totebox Orchestration."
status: active
bcsc_class: forward-looking
last_edited: 2026-05-08
editor: pointsav-engineering
paired_with: totebox-session.es.md
---

A Totebox Session is an AI-assisted contributor session opened within a single Totebox Archive. It is scoped to the archive's declared repositories and cannot write outside them. From the contributor's perspective, opening a Totebox Session is how every development task in Totebox Orchestration begins. The session protocol mirrors the customer experience: the contributor's entry point in the workspace and the customer's entry point through `os-console` perform the same function.

This article describes how a session is opened, what it can and cannot do, the four permission tiers, and the inbox-and-outbox protocol that coordinates work across archives.

## How to open a session

The intended entry point is `bin/open-archive.sh <archive-name>`, planned for invocation from the Command Session. When invoked, it is intended to:

1. Read the archive manifest at `clones/<archive>/.agent/manifest.md`
2. Print the archive name, tetrad status, AI gateway endpoint, and count of pending inbox messages
3. Check the contributor's permission tier against the personnel record (see [[personnel-permissions]])
4. Set the `FOUNDRY_ARCHIVE` and `FOUNDRY_MODULE_ID` environment variables
5. Open an AI session at the archive's root directory

This mirrors the customer experience: a community member or customer opens a Totebox Archive through `os-console`. The development workflow uses the same entry point, adapted for the workspace.

## Session scope

A Totebox Session:

- Writes to any repository declared in the archive's manifest
- Commits to the archive's staging branch (never directly to the canonical `main`)
- Routes inference through the shared `service-slm` access-control gateway using the archive's module identifier
- Sends cross-archive requests as messages to the Command Session (never writes to other archives)
- Stages wiki drafts in `.agent/drafts-outbound/` for the editorial pipeline

A Totebox Session does not:

- Write workspace files (`CLAUDE.md`, `AGENT.md`, `bin/`, `pairings.yaml`)
- Write to the identity store
- Access the canonical `vendor/` or `customer/` trees directly (those receive content by promotion, not direct write)
- Open connections to sibling archive sessions

## The Project Tetrad

Every Totebox Archive declares four legs of the Project Tetrad. A session's work contributes to all four:

| Leg | Session writes to |
|---|---|
| vendor | Feature code in the archive's `pointsav-monorepo` clone |
| customer | Operational guides in the archive's `woodfine-fleet-deployment` clone |
| deployment | Provisioning the running instance in `~/Foundry/deployments/` |
| wiki | TOPIC draft files staged in `.agent/drafts-outbound/` |

The Command Session ratifies tetrad completeness when all four legs are present.

## The AI session coordination protocol

Sessions communicate through the inbox-and-outbox file protocol:

- Each archive holds `.agent/inbox.md` and `.agent/outbox.md` files
- A Totebox Session reads its inbox at session start and archives actioned messages
- Outbound requests to other archives or to the Command Session are prepended to `.agent/outbox.md` (newest on top)
- The Command Session sweeps cluster outboxes during workspace review and routes messages

In the planned next phase, `app-orchestration-command` (CommandCentre) is intended to broker all cross-archive messages by HTTP, with each message transiting the access-control gateway and the immutable ledger automatically. The file-based protocol is intended to remain as the fallback and the development-mode mechanism.

## Permission tiers

Four tiers govern what a contributor — and the session they open — can do:

| Tier | Label | Pairing set |
|---|---|---|
| P1 | System Administrator | Command + every archive + every infrastructure node |
| P2 | Package Manager | Specific archives plus Stage 6 promotion paths |
| P3 | User | Specific archives; no Command pairing; read-only cross-archive |
| P4 | Interface | Read-only API surface only |

Tiers are enforced by pairings, not string comparisons. A P3 contributor's `os-console` is not paired to the Command — the connection does not exist. See [[pairing-as-permission]] for the formal mechanism.

## Relationship to os-console

`os-console` is the customer-facing entry point for opening a Totebox Archive. In the workspace, `bin/open-archive.sh` is the equivalent. Both are intended to perform the same function: read the archive manifest, validate the contributor's permission scope, set the session context, and open a working session inside the archive. The development environment uses the same pattern the customer is intended to use.

## See also

- [[totebox-orchestration-development]]
- [[pairing-as-permission]]
- [[personnel-permissions]]
- [[doorman-protocol]]

## References

- **`DOCTRINE.md`** — Foundry constitutional charter.
- **`conventions/project-tetrad-discipline.md`** — ratified Project Tetrad specification.