Make organisation and instance setup coherent #47
Notifications
Due Date
No due date set.
Blocks
Depends on
Reference: sam/archie#47
Reference in new issue
Block a user
Implement navigation derived from the approved ownership model after backend resource contracts work. Organisation selector establishes context for Workflows, Tasks, Connections and Organisation settings. Instance administration is separate and administrator-only; personal security stays in the account menu. Setup is contextual to the requested capability, never a mandatory repository/model/channel wizard. Failed tasks link to authorised recovery actions from structured service diagnostics. The initial page-rearrangement proposal was rejected.
Design
Contract-First Setup & Navigation Architecture (archie-core-3z4fd.1)
1. Foundational Contracts (Established Before Navigation)
A. Ownership Contract (instance -> org -> workspace -> object)
self/identity.KindUser): Personal passkeys (/api/passkeys), personal bearer tokens (/api/tokens), password & recovery code. Moved out of/orginto/account.orgID):/org/access).bot/service_accountviaorg.AgentAssignment), including Git commit author (commit_name,commit_email), forge connection binding, and container credential grants (identity-grants) (/org/agents).type,host,token: SecretRef), repository policies (repository-policies), messaging channels (channel-settings), org credential bindings (credential-bindings), and subscription harnesses (/org/connections).provider-settings), model aliases (model-aliases), soul (soul), curators (curators), skills (skills), and review rules (review-settings) (/org/models).workflow-definitions,workflow-enablement,workflow-execution-settings), playbooks (eda-playbooks), schedules (schedules), and event sources/mappings/bindings (/workflows,/events).workspaceID): Scopes work items and repositories within an organisation.org-sysadmins only): Secret engines (env,bws), installed extensions & authority acceptance (extension-settings,plugin-settings), compute/container runtime (container-runtime-policies,agent-profiles,tool-settings,scheduling-policy,task-policy), instance model policy (org-model-policy), service apply status & release updates (update-settings), and control-plane history/audit (/settings/*).B. Identity & Authority Contract (No Split Identity Model)
Five distinct roles are separated and never conflated:
user): Authenticates interactive sessions and personal API tokens; authorized viaorg.Membershipand Cedar.publisherIdentity): The user, webhook binding, schedule, or parent workflow that initiated a task (mayRunWorkflowcheck at intake).iface.Identity— "Runs as"): Activebotorservice_accountidentity insys_identitiesassigned to the org (org.AgentAssignment).config.toml[[identities]]vssys_identitiessplit-brain: startupbot_user/[[identities]]seed intosys_identities(DefaultOrgID), anddeclaredIdentity,identityMayAct, andidentity-grantsresolve against State StoreIdentityIDs (with"root"aliased to the org's default agent identity).RunCredentialbound to(TaskID, OrgID, WorkspaceID, IdentityID, Capabilities)that is revoked on container exit.SecretRefcredential used byarchiedand itsSurfaceForgeextension to poll, clone, push, and open PRs.commit_nameandcommit_emailstored on the Agent Identity and stamped into<worktree>/.git/configbyworktree.Manager.C. Connections & Credentials Contract
SecretRef), Model provider API keys (SecretRef), Messaging channel bot tokens (SecretRef). Resolved only byarchied,archie-gateway, orarchie-messaging.credential-bindings(service -> SecretRef) granted to specific Agent Identities viaidentity-grants(or OAuthharnesses), injected through the daemon egress proxy and revoked when the task container exits.D. Execution Contract (Capability-Driven, Optional Repository)
repository: none | optional | required.repository: noneworkflows): (1) Org & Admin Account -> (2) Secret Engine (envorbws) -> (3) Model Provider +defaultAlias -> (4) Active Org Agent Identity (bot) -> (5) Workflow (repository: none, runs inPrepareScratch).repository: required | optional): (6) Installed/Accepted/Enabled Forge Extension (github/gitea) -> (7) Active Forge Connection (SecretRefresolved inarchied+ plugin started) -> (8) Repository Policy (owner/name) verified against that Forge Connection.E. Configuration Lifecycle & End-to-End Readiness Contract
Persisted Versionvs per-serviceApplyStatus(archied,archie-gateway,archie-messaging).forge.*) and Agent Identities move out of startup-lockedDeniedKeys/preserveForgeIdentitysoarchiedhot-reloadsb.forgeClient,b.trees, andb.identityRunners.archied), not by a standalone secret-reference string check:SurfaceForgeextension installed, authority accepted, enabled, and running, (3) tokenSecretRefresolved inarchied, and (4) forge client active (notforge.NewNoop).Verify Repository Accesscheck fromarchied.F. Failure & Recovery Contract (Structured Service Diagnostics)
task.HasRepository()is true andd.Forgeisforge.NewNoop,archiedparks the task immediately with a structured blocker (forge.extension_disabledorforge.token_unresolved,ParkNeedsHuman) instead of running an anonymousgit clonethat fails with a misleading 401.archiedparks any task or raises a condition alert, it records a structuredTaskBlocker{Kind, Subject, Title, Detail, ActionKind, ActionLink}(and raises/syncs the correspondingalert.Alert).ActionUpdateonActionKindfor the current principal and surfacesActionLinkin the Task Detail header, Stage Rail, and Dashboard Needs Attention banner without frontend regex matching.2. Navigation & Page Disposition Summary
/(Dashboard),/tasks,/workflows(tabs: Definitions, Playbooks, Schedules + execution defaults; removes duplicate/settings/workflows),/events(tabs: Stream, Sources & Bindings)./org):/org(Overview & Readiness),/org/agents(Agent Identities, Commit Author, Identity Grants),/org/connections(Forge Connections, Repositories, Messaging Channels, Org Credential Bindings),/org/models(Org Providers, Model Aliases, Soul, Curators, Skills, Review),/org/access(Members, Invites, Workspaces, Cedar Policies)./settings,org-sysadmins only):/settings/status(Apply Status & Updates),/settings/extensions(Secret Engines, Forge/MCP Extensions & Plugins),/settings/runtime(Containers, Agent Profiles, Tools/MCP, Scheduling/Task Policies),/settings/model-policy(Instance fallback &org-model-policy),/settings/history(Control-Plane History & Audit)./account): Personal API Tokens, Passkeys, Password & Recovery Code.Acceptance criteria
An operator can follow visible links from initial setup to configuring a model, private repository access and starting a task. Organisation, personal and instance settings have clear homes; no duplicate organisation name. Agree the navigation map before moving pages.
Notes
Approved proposal is the maintainer-approved organisation-owned automation model in this session. Review any externally supplied design field against that approval; it is not independently approved. Do not preserve conflicting startup/config identity models with explanatory copy. No UI implementation begun in this handoff.
Implementation 2026-10-17 (navigation slice).
Landed (commits
21eff9ef, 2a73b291):Verified in the live dev UI (Vite): every new route renders with no console errors, old paths redirect, drafts survive in-app navigation within the config shell.
Remaining, blocked on this Bead's dependencies:
Slice done (failed-task recovery, part 1): parks record a structured blocker (taskstate.Blocker, tasks.park_blocker) at the park site for workflow disabled, workflow identity missing or invalid, execution identity not assigned or inactive, and policy denial. GET /api/tasks/{id}/attempts returns recovery {blocker,label,link} only when the viewer's principal is authorised for the fixing page's API write (and is an instance viewer for instance-only routes); the task header shows it as a link. Still open: forge/connection, model credential and clone-permit blockers, Stage Rail and Needs Attention surfaces, alert sync.
2026-10-27 navigation slice (branch worktree-agent-a7419d510e132bb69, 2e9ff657, 834ffe44, e7098e01). Done: /api/capabilities now also reports org_members, org_agents, org_policies and org_config per caller by asking the access chain whether the page's own API write is allowed (mayCall, shared with task recovery); org routes carry those sections so the sidebar, Jump to and the Org overview hide pages the caller cannot operate. Appearance moved out of the Instance sidebar to /account/appearance (account menu), old paths redirect. Recovery blockers added for repository not configured, connection credential and forge extension (daemon accessBlocker maps AccessError codes); GET /api/tasks rows carry recovery so Needs attention links to the fix. Setup checklist is now org-derived (active agent identity, first task), no longer instance-only, chat channel step removed (optional capability). Remaining: org selector scoping Tasks/Workflows (no org parameter on those APIs, selector still only in /org for instance admins); model-credential blocker and Model setup step (needs effective-model read); Stage Rail recovery link; alert sync; forge/repository readiness badges; Audit still lives under Instance (org-scoped read). Not run: e2e stack (port 9091 held by another stack), browser checks not done; ui unit tests and task check pass.
2026-10-27 org context slice (branch worktree-agent-ace615df341d7afec, 156ecbcc, 602fb547). Done: caller-selected org flows end to end. Cookie set by PUT /api/orgs/current, honoured per request only for orgs the principal holds a membership in (access.Principal.Select, the single gate); forwarded to the State Store as metadata and re-checked there before scope is set, so Tasks/Workflows/SSE read the selected org. GET /api/orgs reports member_orgs; top bar switcher shows for callers with more than one. Model: model_credential park blocker (egress open failures) with Set up model link; setup checklist adds Model step only when the org has no aliases (CallerModels); task alert now raised for any parked task carrying a blocker. Stage Rail shows the recovery link on the parked attempt. Repo/connection badges (No connection, Verified, Check failed, Forge not enabled, No credential) derived from page state and manual access check. Audit moved to /org/audit (old paths redirect), gated by org_audit capability. Remaining: server-served readiness (saved/applied/verified/failed) from archied instead of page-derived badges; credential-validity of providers is not in the effective-model read (aliases only); /org/{id} pages still need the org selected first (path org is not honoured for members); e2e and browser checks not run (port 9091 held by another stack).
2026-10-27: org selector, model setup step and blocker, Stage Rail recovery, readiness badges and audit move landed (34b68228..e42e4239), deployed. Remaining: archied-reported readiness for badges, model step checking provider credentials, browser verification.
Imported from beads
archie-core-3z4fd.1· GitHub #1690 · type task · priority P1 · created 2026-10-16