stack/docs/plans/2026-09-06_agent-project-workspace-foundation.md

Agent, project, and workspace foundation

Status: documentation draft for Jason's review. No implementation authorized. Date: 2026-09-06. Plan author: darkwing, current pi session 01a06e48-0718-71f2-a889-c263c4800fb9. Baseline: 69d1bb3aa4b826218aa4cca3710f2d98c0b9d7ba in mosaicstack/stack-v2. Issue: #53, opened by rocko under the authorized seat identity, POST 201 reported at 2026-09-06T00:12:33Z.

Start here for the intended behavior. Field proposals and execution evidence are in Schema and audit discussion. Phase-2 detail is now in the Record and operation contract candidate. These documents are not implemented APIs or approved JSON Schemas.

1. Why we are doing this

Jason wants one familiar interaction agent to work in several separate areas without creating another agent identity for each assignment. Workers should also reuse their definitions across projects and workspaces.

A fresh conversation must be able to continue checked work without inheriting an old conversation's confusion. Files and work records, not conversation memory alone, tell the agent what to do next.

Development must remain understandable and testable by Jason. We agree on a small result and its test, build only that result after approval, then stop for Jason to try it. Passing automated tests is not user acceptance.

2. Requirements agreed in the owner conversation

These describe intent. Exact field names, storage paths, and mechanisms below remain proposals unless separately approved.

ID	Requirement
R1	An agent has a reusable identity, type, execution program, SOUL, configuration, and permission limits. Creating an assignment need not create another agent identity.
R2	A project registers participating agents and controls their visibility and permitted work through role-based access control, RBAC. Owner round 1, Q2: the user may delegate bounded registration/assignment authority to the system; actions outside those limits require approval.
R3	A project contains N workspaces; each workspace has exactly one parent project, owner Q5. Each workspace registers participating agents and keeps its work separate. Owner Q3: project membership permits shared project information and only explicitly permitted workspaces, not all workspace content. Dependencies are references, not additional parents.
R4	The same agent can participate in many projects and workspaces, with separate working sessions. One definition per worker type may suffice; specialized definitions remain possible.
R5	Launch names the agent, project, and workspace. Those choices determine mission, tasks, state, working paths, and message destination. The agent does not guess its assignment from its seat directory.
R6	Shared instructions and skill definitions may be reused. Work-specific information points to the declared workspace and relevant project records, not a global agent task list.
R7	Resume and Fresh are distinct launch operations. Resume is the default. Owner Q4 clarification: if no conversation has ever existed in the declared agent/project/workspace scope, initial launch creates it and announces this without an offer. Missing or damaged established conversations are errors, not first use. Fresh does not automatically import the old conversation or its automatic summary.
R8	A fresh conversation supports continuing, abandoning, or selecting established work, independently of conversation choice. Owner Q8: Abandon defaults to ending this agent's selected assignments, not cancelling the shared mission/tasks. Owner Q9: an unfinished prerequisite requires an explicit authorized assignment change, never silent expansion or proceeding as if it were complete.
R9	Users and authorized system services can launch or relaunch an agent with fresh context. Mission recovery uses saved work records.
R10	Default concurrency is one active working session per agent/project/workspace. Users can tune concurrency; budgets, usage measurement, and automatic scaling are requirements for later phases.
R11	Terminal, desktop, and web interfaces refer to the same workspace work records. They show the active agent/project/workspace and do not keep competing task lists.
R12	Messages must address the appropriate workspace. Identity reuse must not mix conversations or work across projects.
R13	Separate folders provide logical organization, not a demonstrated security sandbox. Security enforcement needs its own evidence.
R14	Execution records retain the reusable agent identity and identify the particular assignment/session that acted. Capture context through the system, not agent self-description. Owner Q13: concise action records name actor/scope/session/task, operation, target, authorization, outcome, and evidence references. Detailed evidence is stored separately with access controls; no credentials in either.
R15	Jason approves progression between phases and tests implementation increments before later work depends on them. No automatic queue-running.
R16	Owner ruling, 2026-09-06: SOUL remains canonical per agent. Each Resume or Fresh launch loads the current approved revision into execution-specific inputs and records it. Running conversations do not silently reload changed instructions. Recording the revision does not permanently pin a workspace to it.
R17	Owner Q20/Q21 extends the launch fingerprint to shared behavior-affecting agent configuration: SOUL, shared instructions, applicable enabled skill versions, harness/model settings, and role configuration. Exclude credentials, chat, and task progress. TUI/GUI/WUI show automatic non-blocking mismatch notices recommending Fresh and support on-demand checks against the same record, without repeated interruption or automatic restart.
R18	Owner Q1/Q5: missions may exist at project and workspace levels, with explicit single-parent relationships. A workspace mission has at most one parent project mission, or stands alone within its owning workspace/project scope. Each mission has one owner and authoritative record. A parent may have many children; dependencies are not extra parents.
R19	Owner Q7: delegated, authorized agents may make non-destructive, goal-directed decisions and decompose work autonomously within the established plan. Routine tasks may be accepted by an authorized independent reviewer against agreed criteria. No user interaction is needed for each within-plan decision; scope deviations and declared owner checkpoints still require approval.
R20	Owner Q10: conversation and permitted workspace inspection may precede a mission/task. Requests to change things become explicit recorded assignments without requiring lengthy mission setup. Scope and permissions still apply.
R21	Owner Q11/Q15: Resume targeting an already-running session reports the conflict and offers connection to a user. A service receives an already-active result with the execution identity and must explicitly request connection or another authorized operation. No automatic connection, replacement, or duplicate launch.
R22	Owner Q12: agents share permitted workspace missions, tasks, decisions, and evidence. Reading another agent's conversation needs separate permission or an explicitly authorized handoff. Read permission never implies automatic conversation loading.
R23	Owner Q14: workspace membership removal stops affected executions and blocks further actions in that workspace. Independently authorized work elsewhere continues. Global agent disable is separate; already-issued actions need reconciliation, not an assumption that stopping undoes them.
R24	Owner Q16: one controlling interface connection per running session initially. Other authorized connections may observe; transfer of control is explicit. Observation requires conversation access permission.
R25	Owner Q17: Fresh during active work requests controlled replacement. Stop admitting new actions, preserve checked state, settle or identify unfinished actions, then launch Fresh only when safe. If safe replacement cannot be established, stop and report rather than start competing work.
R26	Owner Q18: an authorized agent/service may investigate uncertain results with non-destructive checks and resume dependent work only after evidence resolves the uncertainty. Otherwise escalate. Blindly repeating the original action is not a recovery check.
R27	Owner Q19: required audit-recording failure blocks affected executions. Other work continues only if its required recording works. Refuse before an affected action; treat effects with missing result evidence as uncertain and reconcile them.
R28	Owner Q22: only explicitly designated general user preferences are shared by default. Personal and project-specific information is supplied only where authorized and relevant, not by automatically loading the whole user profile into every launch.
R29	Owner Q23: closing a workspace retires it from active work, safely stops its work, retains files/history, and blocks ordinary new launches until reopened. Deletion and retention cleanup are separate authorized operations.
R30	Owner Q24: existing sessions remain legacy records until explicitly adopted through reviewed project/workspace assignment. No inferred membership from filenames and no automatic default-project placement. Preserve historical evidence.
R31	Owner Q25: an approved plan change pauses affected work for reconciliation. An authorized coordinator may adjust assignments within its delegation; unaffected work can continue. Account for actions already underway. Escalate adjustments beyond delegated authority or that cannot be resolved safely; do not finish obsolete assignments merely because they started earlier.
R32	Owner Q26: use standard scope permission roles with registration-specific narrowing. A project/workspace role describes what the agent may do there; it does not redefine its reusable identity/type or exceed its permission ceiling. Exact role names and grant lists require review.
R33	Owner Q27 A: initial managed commands require invocation-level evidence: actor/scope/assignment, authorized command, enforced filesystem/network limits, start/end, outcome, and controlled evidence references. Separate tracing of every internal file/network operation is not required. Isolation, credential protection, fail-closed recording, revocation, and uncertainty recovery remain mandatory.
R34	Owner Q28 A: the initial managed terminal may be Mosaic-controlled with Pi remaining the engine; native Pi screen/shortcut parity is not required. Clients use the same mediated operations, with no waiver of scope, permission, recording, privacy or recovery requirements. This is not runtime implementation approval.

3. The objects in plain language

Shared agent definition: darkwing
  Identity, type, Pi configuration, SOUL, permission limits

Project: mosaic-stack-v2
  Registered agents: darkwing, code-be-01, rev-code-01
  Project decisions and shared project state
  |
  +-- Workspace: sessions
  |     Registered agents and assignments
  |     Workspace mission, tasks, files, state
  |     Darkwing conversations and execution records
  |     Code-be-01 conversations and execution records
  |
  +-- Workspace: skills
        Separate assignments, files, state, and conversations

Project: personal
  Workspace: journal
    Darkwing registered here too, with separate work context

Agents are referenced by projects and workspaces; they are not copied into new identities for each registration. A session belongs to one agent/project/workspace combination. A running instance is one execution attempt using that session. Resuming a conversation creates another execution attempt, not another agent identity.

Owner Q5 distinguishes containment from dependencies: one project owns each workspace; a workspace mission may contribute to at most one project mission. A standalone workspace mission still belongs to its workspace and project. Dependency references do not create another parent or confer its permissions.

Proposed ownership rule: project-wide decisions have one authoritative home. Workspace records reference the relevant project revision rather than copy it into an independently editable project state. Individual assignments stay separate even when several agents share a workspace.

4. Resume, Fresh, and the work decision

Conversation operation	Work decision	Intended result
Resume	Continue	Reopen the selected conversation and reconcile it with current authorized work state.
Fresh	Continue	New conversation; load checked mission, task status, and relevant evidence. Do not import the old chat.
Fresh	Abandon	End this agent's selected assignments and start a new conversation. Underlying missions/tasks remain for reassignment unless separately cancelled with authority. Preserve history and files.
Fresh	Select	Start with explicitly selected work and relevant dependency information. An unfinished prerequisite needs an authorized assignment change before execution. Unselected work is not silently cancelled.

Owner Q4 ruling: first use creates the initial conversation automatically and announces "Starting initial conversation" without a confirmation offer. This is not replacement of existing context or a third public launch command. Subsequent default launches resume. Owner Q11: if that conversation is already running, report the conflict and offer to connect rather than automatically connecting or launching another process. Owner Q15: a service receives an already-active result with the execution identity and chooses any next connection or other operation explicitly under its authority. A missing/damaged established conversation is an error, not permission to create a replacement. Ambiguity still refuses.

Owner Q10: initial conversation and permitted inspection do not require a mission/task. Requests to make changes become recorded assignments within the user's or service's authority. No mission setup ceremony is required for chat.

Owner Q6 approved Fresh/Continue loading the assigned mission and success criteria, assigned tasks/status, relevant approved decisions, dependencies, blockers, and verified-result references. A proposed next step is labelled as a proposal, not an authorized assignment. Old chat/automatic summaries stay out; unverified notes remain labelled as unverified.

Owner Q7/Q9: an explicit assignment change need not require Jason personally. An authorized coordinator may approve prerequisite work within delegated plan limits and record the change. The worker never silently expands its assignment. This autonomy does not waive the owner-controlled phase boundaries below.

Owner Q16/Q17: an existing execution has one controlling interface connection; authorized observers do not become additional controllers. A Fresh request initiates controlled replacement, stopping new actions and preserving checked state. Unfinished actions must be resolved or explicitly identified before replacement; if safety is uncertain, stop and report. Do not copy old chat into the new session as a substitute for checked work state.

Proposals for review:

• Abandon and Select are not valid with Resume in the first version. Keeping the old conversation would retain the context the user meant to set aside.
• If the caller lacks access to a required dependency, the system refuses rather than silently omitting it.
• A relaunch first resolves the old execution's status. Starting Fresh is not permission to leave two sessions claiming the same assignment.
• A fresh launch does not delete files or cleanse incorrect files. Retained artifacts must be distinguished from active work records.

These rules need lifecycle and failure details before implementation. See open decisions.

5. What the owner has tested so far

On 2026-09-05 Jason launched the existing researcher definition with workspace and session name owner-checkpoint-1, allowing only read,ls. The supplied terminal output showed Pi 0.84.4, a successful model response, and an empty /var/lib/mosaic/workspaces/owner-checkpoint-1 listing through ls. After exiting and relaunching, the agent recalled a phrase from the conversation without a tool call.

This demonstrates the observed launch/list/resume path. It does not prove cross-workspace access controls, long-conversation correctness, execution auditing, Fresh mission recovery, or any project model. Fresh was discussed but not demonstrated. This plan does not infer broad user acceptance from the earlier test or mark unfinished tests as passed.

6. Current code references, not future guarantees

All source references below are at the baseline commit named above. These are starting points for the later independent analysis, not its verdict.

Current behavior	Source
On every launch, agent defaults and role are read from a definition and current seat SOUL is copied to a shared per-agent runtime location. This is not a one-time copy or a live update to already-running instructions.	scripts/agent.sh:78-130
Session defaults to agent-<name> under the global sessions directory, independently of workspace selection.	scripts/agent.sh:132-138
Role tools narrow requested tools; enabled skill definitions are resolved and passed as container paths.	scripts/agent.sh:140-179
Interactive mission is copied to agent-missions/<agent>.json; workspace is a separately selected folder; Compose starts the container.	scripts/agent.sh:181-199
Pi changes working directory, uses the named session directory, and adds -c when it is nonempty.	adapters/pi/adapter.sh:23-50
The whole data root is mounted at /var/lib/mosaic, not just the selected workspace.	compose.yaml:39-43
Dispatcher generates one shared system-prompt path; the loader also uses one .partial path and injects global user Markdown.	src/run-agent.sh:37-41; src/load-contracts.sh:40-41,68-77,97
Headless tasks get exclusive input snapshots and a final result containing workspace, session, tools, model, and timing.	scripts/mosaic-task.mjs:295-325,442-466

The per-agent mission/SOUL paths and shared prompt paths require explicit concurrency analysis. Do not claim that independent workspace names already prevent launch-time context mix-ups. No race reproduction has been performed in this documentation phase.

7. Scope and existing plans

Authorized now: these two planning documents, CURRENT.md routing, issue intake, and append-only build/session history. No runtime schema files, implementation, new agent definitions, credential changes, migration, release activation, map generation, or skill integration.

The auth/provider plan, issue #50, stays paused. Its seat-global selection and generated per-seat files must be reconciled with concurrent workspace sessions before implementation. OAuth refresh gate 7 is still unresolved; this plan does not approve it.

ROADMAP.md supplies earlier direction, not authority to skip this exercise. The old registry-first maps are historical candidates, not a complete plan for this object model. Issue #51 and untracked skills remain separate work. No source is moved into packages/ in this phase.

Keep the repository canon: sole system config, no new root files, no secrets in documents/images, reviewed role authority, and write-once run evidence under <dataRoot>/runs/. Runtime project/workspace records must not become a second system configuration or a way to grant themselves wider authority.

8. Phases, each stopped for owner review

Phase	Output	Required stop
1. Document, behavior confirmed	Agreed requirements, proposed record shapes, initial source references, audit limitations, and open decisions.	Jason confirmed the behavior summary on 2026-09-06 and subsequently authorized phase 2.
2. Resolve details, current	Exact object relationships, schemas, permissions, command behavior, state ownership, and action-record guarantees, with read-only investigation.	Q27 selects invocation-level command evidence with enforced limits. Complete the remaining details, then Jason approves a specific plan revision for mapping.
3. Map with Archify	Separate current/planned diagrams and a ledger tracing launch, state, permissions, messaging, and execution receipts.	Independent map review plus Jason's visual acceptance.
4. Independent gap analysis	A distinct non-authoring agent compares the pinned implementation and agreed plan; reports missing, conflicting, or unsupported connections.	A different agent reviews the report; Jason decides each finding and whether another plan/map revision is needed.
5. Plan one implementation increment	Named author/reviewer, allowed paths, acceptance test, rollback, and protected operations.	Jason authorizes that one increment.
6. Implement and user-test	Local suites, independent candidate review, verified release if needed, and a short test Jason performs.	Jason explicitly accepts before another increment begins.

Documentation, the decision interview, and phase-2 detailed design/read-only investigation are authorized. Individual behavior rulings and documentation completion are not full schema approval. A diagram passing rendering checks is not evidence that its claims are correct. No review request is implied by naming a future reviewer.

Roles: Jason owns scope, decisions, and acceptance. Darkwing authors this plan and coordinates. Proposed later map author: rocko. Proposed later independent reviewer/gap analyst: filbert, if available and not a design or map author. Proposed peer reviewer of the gap report: ms-test, if independent of its authorship. Confirm assignments at the phase boundary. If an independent seat is unavailable, report blocked; the author does not take its place.

9. Evidence required in later phases

Archify work must cite code and plan lines at named commits, separate facts from proposals and external measurements, and bind spec/ledger/HTML hashes. Use the approved lane preview and browser checks; preserve old verdicts. A reviewer verifies the exact candidate. The later gap analyst must check both code and plan, not infer correctness from the diagram or its author. Unspecified paths and missing enforcement are findings, never invented edges.

Candidate user tests, to agree before implementation:

• Same agent in two workspaces retains different files, tasks, and chats.
• Fresh/Continue remembers an approved task but not an unrecorded chat phrase.
• Resume reopens only the intended workspace's conversation. If already running, it reports the conflict and offers connection without auto-attach.
• Unassigned conversation and permitted inspection work; a change request creates an authorized recorded assignment, not untracked mutations.
• Agents can read shared work records but cannot read a colleague's transcript without a separate grant. Granting access does not auto-load the transcript.
• Change canonical SOUL while two workspaces run: both show a configuration mismatch, retain their recorded launch inputs, and recommend Fresh. Relaunch one workspace with the new revision; only that execution becomes current. Verify each interface uses the same status, and task progress alone does not produce a base-configuration warning. See R16-R17 and D16.
• Abandon preserves history and does not cancel another agent's work.
• Select includes dependency information, obtains an explicit authorized assignment change before undertaking unfinished prerequisites, and leaves unselected work explicit.
• An authorized reviewer accepts a routine task without a user prompt, with criteria and evidence recorded. A plan deviation or protected action does not inherit that permission.
• Unauthorized registration, ambiguous addressing, and stale task ownership refuse without acting in another workspace.
• Removing one workspace membership stops affected work and blocks further actions there while leaving independently authorized work elsewhere running. In-flight effects are reconciled rather than declared undone.
• Only one authorized interface controls a session; observers cannot issue controls and explicit transfer prevents the old controller from continuing.
• Fresh during active work does not overlap unsafe executions. Unknown effects block dependent work until authorized, non-destructive investigation resolves them or escalation occurs; no blind replay.
• Audit failure blocks affected work without unnecessarily stopping executions that can still meet their recording requirements.
• Configuration notices cover shared behavior-affecting inputs, appear without blocking work, and can be requested on demand without changing execution.
• Synthetic personal-journal context is absent from a coding launch unless explicitly authorized/relevant; designated shared preferences remain usable.
• Closing a workspace preserves records and blocks new launches until reopening. Adopting legacy sessions requires explicit reviewed assignment, not name-based inference, and does not rewrite their historical evidence.
• A changed approved plan pauses affected actions/dependents until reconciled; delegated reassignment and continued unaffected work retain authority evidence.
• Standard scope roles are narrowed by registration and parent/agent ceilings. A role label alone cannot grant access to other workspaces or self-acceptance.
• Each managed action can be traced to a session, execution attempt, task, authority decision, and evidence-backed outcome, including interrupted work.

Later tests must cover strict schemas, cross-project references, path escape, concurrent launch, shared-file races, stale messages, audit write failures, and partial external effects. Terminal/desktop/web clients need situational and accessibility tests when implemented; none are claimed by this draft. CI runners remain owner-deferred. Local suites plus verify.sh are the repo publication gate, with exact-candidate review and owner phase approval.

No deployment or migration occurs now, so existing operation is unchanged. Any later migration must preserve old sessions/run records, be explicit about reset/prune effects, and have an owner-reviewed recovery and rollback test.

10. First owner review

Review R1-R33 for faithful intent. The owner authorized the grill-me interview on 2026-09-06. Rounds 1-6, Q1-Q26, are recorded in the linked discussion. Q25/Q26 add affected-work reconciliation after approved plan changes and standard scope permission roles with registration-specific narrowing.

Jason confirmed the behavior summary with "That looks correct" on 2026-09-06, after Q1-Q26. Shared understanding of intended behavior is confirmed. This is not whole-schema approval or a claim that every technical branch is resolved.

Jason subsequently answered yes to phase 2: detailed records, permissions, commands, and audit guarantees with read-only technical investigation. The linked phase-2 candidate records the first source/document findings and proposed common types. Jason answered Q27 A: invocation-level command evidence with enforced limits, without a promise to enumerate every internal effect. The explicit /goal request resumed phase 2 after reboot recovery. The schema package now includes checked record/command shapes and semantic-rule proposals. Jason answered Q28 A, recorded as R34. The owner-review package now reconciles D1-D16 against the candidate schemas/rules and explicit implementation proof gates. Phase-2 acceptance remains Jason's decision. No mapping, independent gap review, implementation, publication, or migration follows automatically.