fix(taskstate): tie operator actions to the transition table; keep unreadable terminal worktrees

qdbo.8 follow-ups: ActionTarget names each action's destination status, the
taskactions service records through it, and a test proves every offered action
is a legal transition. worktreeHoldsUncapturedWork now keeps a worktree on any
stat error other than not-exist. The dashboard action test covers completed, and
agent-system.md drops the no-state-machine hazard qdbo.5 resolved.
This commit is contained in:
sam committed 2026-09-27 13:29:55 +10:00
1 parent e16ba86b30
commit 5734e194c9
7 files changed
+45 -9

No files matched your search

-3
View File
@@ -311,9 +311,6 @@ implemented in different packages:
## Current workflow-feature hazards
- There is no enforced WorkflowExecution state machine. `Store.Transition`
guards on the supplied `from` state but accepts any `from` to `to` pair. See
`docs/prds/execution-tree-state-machine.md`.
- State update and transition-history insertion are separate operations, so
state and audit can diverge.
- Callers frequently discard persistence and transition errors.
+1 -1
View File
@@ -16,7 +16,7 @@
"url": "/dev/architecture/agent-system/",
"title": "Agent System",
"section": "Architecture",
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
},
{
"url": "/dev/architecture/bindings/",
+6 -1
View File
@@ -8,6 +8,7 @@ import (
"encoding/json"
"errors"
"fmt"
"io/fs"
"log/slog"
"maps"
"os"
@@ -1470,7 +1471,11 @@ func (d *Daemon) cleanupTerminalTaskWorktree(ctx context.Context, task *workflow
func (d *Daemon) worktreeHoldsUncapturedWork(ctx context.Context, trees *worktree.Manager, task *workflow.Task) bool {
dir := trees.Dir(task.Owner, task.Repo, task.IssueNumber)
if _, err := os.Stat(dir); err != nil {
return false
if errors.Is(err, fs.ErrNotExist) {
return false
}
d.Log.Warn("terminal worktree kept: it could not be read", "task", task.ID, "dir", dir, "err", err)
return true
}
uncommitted, err := trees.HasUncommittedChanges(ctx, dir)
if err != nil {
+11 -4
View File
@@ -175,6 +175,13 @@ func (s Service) Apply(ctx context.Context, scope *string, actor Actor, id int64
return nil
}
// The statuses the cancel path records, taken from the lifecycle's action table
// so the service cannot drift from the transitions it offers.
var (
declined, _ = taskstate.ActionTarget(taskstate.ActionReject)
parked, _ = taskstate.ActionTarget(taskstate.ActionStop)
)
type outcome struct {
event events.Event
verb string
@@ -199,7 +206,7 @@ func (s Service) apply(ctx context.Context, task *Task, actor Actor, action task
// A rejection ends the run's work wherever it sits, so it rides the
// one cancel path like every other operator stop.
o.event.Kind, o.event.Detail, o.verb = rejectedKind(actor), actor.describe("rejected"), "declined"
if _, err := s.Store.CancelExecution(ctx, task.ID, actor.describe("rejected"), "closed_wont_do"); err != nil {
if _, err := s.Store.CancelExecution(ctx, task.ID, actor.describe("rejected"), declined); err != nil {
return o, err
}
s.deliver(task.ID)
@@ -269,7 +276,7 @@ func (s Service) applyStop(ctx context.Context, task *Task, actor Actor, o outco
// context cancel that found nothing executing says so; the parked
// execution is recorded either way, and the task's own unwind cannot win
// the race any more -- its next step write is already stale.
if _, err := s.Store.CancelExecution(ctx, task.ID, o.event.Detail, "parked"); err != nil {
if _, err := s.Store.CancelExecution(ctx, task.ID, o.event.Detail, parked); err != nil {
return o, err
}
if !s.CancelTask(task.ID) {
@@ -283,13 +290,13 @@ func (s Service) applyCancelOrAbandon(ctx context.Context, task *Task, action ta
// Abandoning ends archie's run, not the issue: no verb, so the issue
// stays open for a human.
o.event.Kind, o.event.Detail = events.KindTaskAbandoned, actor.describe("abandoned")
if _, err := s.Store.CancelExecution(ctx, task.ID, o.event.Detail, "closed_wont_do"); err != nil {
if _, err := s.Store.CancelExecution(ctx, task.ID, o.event.Detail, declined); err != nil {
return o, err
}
return o, nil
}
o.event.Kind, o.event.Detail, o.verb = events.KindTaskCancelled, actor.describe("cancelled"), "cancelled"
if _, err := s.Store.CancelExecution(ctx, task.ID, o.event.Detail, "closed_wont_do"); err != nil {
if _, err := s.Store.CancelExecution(ctx, task.ID, o.event.Detail, declined); err != nil {
return o, err
}
s.deliver(task.ID)
+15
View File
@@ -100,6 +100,21 @@ func Actions(status string) []Action {
return actions
}
// ActionTarget returns the status an action moves a task to. Actions that
// change no status (archive, and the forge links) report false.
func ActionTarget(action Action) (string, bool) {
switch action {
case ActionApprove, ActionRetry:
return Queued, true
case ActionStop:
return Parked, true
case ActionCancel, ActionReject, ActionAbandon:
return Declined, true
default:
return "", false
}
}
// CheckAction rejects stale, illegal and unknown operator controls.
func CheckAction(status string, action Action) error {
if slices.Contains(Actions(status), action) {
+11
View File
@@ -263,3 +263,14 @@ func TestCheckStepStart(t *testing.T) {
}
}
}
func TestOfferedActionsAreLegalTransitions(t *testing.T) {
for status := range executionTransitions {
for _, action := range Actions(status) {
to, moves := ActionTarget(action)
if moves && !CanTransition(status, to) {
t.Errorf("%s offers %s, but %s -> %s is not in the transition table", status, action, status, to)
}
}
}
}
+1
View File
@@ -550,6 +550,7 @@ func TestTaskListExposesLifecycleActions(t *testing.T) {
workflow.StatusRejected: {"archive"},
workflow.StatusDead: {"archive"},
workflow.StatusClosedWontDo: {"archive"},
workflow.StatusCompleted: {"archive"},
}
number := 1