@things-factory/ai-assistant 10.1.203 → 10.1.205

package/server/service/unattended-run/run-store.ts

@@ -0,0 +1,162 @@
+/*
+ * Where runs are kept - one row per occurrence, attempts on the same row (design/ai/unattended-run.md §5).
+ *
+ * Two calls for one occurrence at once are parted by the unique index: one insert wins, the other reads the row it
+ * made. Taking an occurrence over is one update guarded by the attempt it saw, so two servers cannot both take it.
+ * Finishing is guarded the same way: an attempt that was taken over and ends late does not write over the next one.
+ */
+import type { Repository } from 'typeorm'
+
+import { AssistantRun } from './assistant-run.js'
+import { nextStep } from './run-ledger.js'
+
+export interface RunIdentity {
+  domainId: string
+  source: string
+  subject: string
+  scheduledAt: Date
+}
+
+export interface RunStart {
+  name: string
+  modeKind: string
+  modeTarget?: string
+  /** Absent when the account named does not exist - the row still says the run was refused. */
+  runAsId?: string
+  startedAt: Date
+  deadlineAt: Date
+}
+
+export type RunEnding = Partial<
+  Pick<
+    AssistantRun,
+    | 'status'
+    | 'finishedAt'
+    | 'draft'
+    | 'reads'
+    | 'doors'
+    | 'outcomeCode'
+    | 'outcomeParams'
+    | 'groundingWarnings'
+    | 'agentId'
+    | 'clientId'
+    | 'modelCalls'
+    | 'inputTokens'
+    | 'outputTokens'
+    | 'cardsDropped'
+  >
+>
+
+export interface RunStore {
+  /** The row of this occurrence, and whether this call holds its attempt now. */
+  claim(identity: RunIdentity, start: RunStart, now: Date): Promise<{ claimed: boolean; row: AssistantRun }>
+  /** Ends the attempt the caller holds. A later attempt's row is returned untouched. */
+  finish(held: { id: string; attempt: number }, ending: RunEnding): Promise<AssistantRun>
+}
+
+/** What a fresh attempt starts with - nothing of the attempt before it. */
+const CLEARED = {
+  finishedAt: null,
+  draft: null,
+  reads: null,
+  doors: null,
+  outcomeCode: null,
+  outcomeParams: null,
+  groundingWarnings: null,
+  agentId: null,
+  clientId: null,
+  modelCalls: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+  cardsDropped: 0
+}
+
+function endingOf(row: AssistantRun) {
+  /* A running attempt being taken over did not end by itself - it is closed as abandoned. */
+  const abandoned = row.status === 'running'
+  return {
+    attempt: row.attempt,
+    status: abandoned ? 'failed' : row.status,
+    outcomeCode: abandoned ? 'assistant-run-abandoned' : row.outcomeCode ?? null,
+    startedAt: row.startedAt ?? null,
+    finishedAt: abandoned ? null : row.finishedAt ?? null
+  }
+}
+
+export function typeormRunStore(repository: () => Repository<AssistantRun>): RunStore {
+  const where = (identity: RunIdentity) => ({
+    domain: { id: identity.domainId },
+    source: identity.source,
+    subject: identity.subject,
+    scheduledAt: identity.scheduledAt
+  })
+
+  const read = (identity: RunIdentity) => repository().findOne({ where: where(identity) as any })
+
+  async function retake(row: AssistantRun, start: RunStart): Promise<boolean> {
+    const history = [...((row as any).attemptsJson ?? []), endingOf(row)]
+    const result = await repository()
+      .createQueryBuilder()
+      .update(AssistantRun)
+      .set({
+        ...CLEARED,
+        status: 'running',
+        attempt: row.attempt + 1,
+        attempts: JSON.stringify(history),
+        startedAt: start.startedAt,
+        deadlineAt: start.deadlineAt,
+        modeKind: start.modeKind,
+        modeTarget: start.modeTarget ?? null,
+        runAs: start.runAsId ? { id: start.runAsId } : null,
+        updater: start.runAsId ? { id: start.runAsId } : null
+      } as any)
+      .where('id = :id AND attempt = :attempt AND status = :status', { id: row.id, attempt: row.attempt, status: row.status })
+      .execute()
+    return result.affected === 1
+  }
+
+  return {
+    async claim(identity, start, now) {
+      let row = await read(identity)
+      if (!row) {
+        try {
+          await repository().insert({
+            ...where(identity),
+            name: start.name,
+            modeKind: start.modeKind,
+            modeTarget: start.modeTarget,
+            ...(start.runAsId ? { runAs: { id: start.runAsId }, creator: { id: start.runAsId }, updater: { id: start.runAsId } } : {}),
+            status: 'running',
+            attempt: 1,
+            startedAt: start.startedAt,
+            deadlineAt: start.deadlineAt,
+            modelCalls: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            cardsDropped: 0
+          } as any)
+          return { claimed: true, row: (await read(identity))! }
+        } catch (error) {
+          /* Another call made the row first - the unique index said so. Anything else is not that and is thrown. */
+          row = await read(identity)
+          if (!row) throw error
+          return { claimed: false, row }
+        }
+      }
+
+      if (nextStep(row, now) === 'return') return { claimed: false, row }
+      const took = await retake(row, start)
+      return { claimed: took, row: (await read(identity))! }
+    },
+
+    async finish(held, ending) {
+      await repository()
+        .createQueryBuilder()
+        .update(AssistantRun)
+        .set(ending as any)
+        .where('id = :id AND attempt = :attempt AND status = :status', { id: held.id, attempt: held.attempt, status: 'running' })
+        .execute()
+      return (await repository().findOne({ where: { id: held.id } as any }))!
+    }
+  }
+}

package/server/service/unattended-run/run-unattended.test.ts

@@ -0,0 +1,477 @@
+/*
+ * A mode run with no person in it (operato-application/design/ai/unattended-run.md), on sqlite with stand-in models.
+ *
+ * What it guards, in the order the design note says it:
+ *   §2  the run is the owner and no one else - judged again now, refused before any model is asked
+ *   §3  only the mode's reads, behind the owner's own doors; the draft and the reads it rested on are what is kept
+ *   §4  the mode's limits: requests, tokens, wall time - each a failure by its own code
+ *   §5  one occurrence is one row - a retry hands it back, a dead attempt is taken over, a late one writes nothing
+ *   §6  every call goes to the recorders, and they can tell the run's from a turn's
+ *   §7  a failure is a failure: no empty draft, no cut-short draft, never "succeeded" without text
+ *
+ * Races between two servers are measured on postgres (`run-store-race.pg.test.ts`); sqlite cannot run them.
+ */
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+const { clearToolRegistry, registerToolCategory, registerToolCallRecorder, clearToolCallRecorders } = require('@things-factory/ai-client-base')
+
+import type { UnattendedRunDeps } from './run-unattended'
+
+/* The entity is a type-graphql class and needs tsc's decorator metadata, so the compiled module is read - as the
+   other database suites of this repository do. */
+function loadCompiled(modulePath: string): any {
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+  const resolved = join(__dirname, '..', '..', '..', 'dist-server', 'service', `${modulePath}.js`)
+  if (!existsSync(resolved)) throw new Error(`ai-assistant has no build output: ${resolved}\nBuild first:\n  yarn workspace @things-factory/ai-assistant build:server`)
+  return require(resolved)
+}
+const { clearAssistantModes, registerAssistantMode } = loadCompiled('assistant-mode/registry')
+const { unattendedToolCategories } = loadCompiled('assistant-mode/mode-categories')
+const { AssistantRun } = loadCompiled('unattended-run/assistant-run')
+const { runAssistantUnattended } = loadCompiled('unattended-run/run-unattended')
+const { typeormRunStore } = loadCompiled('unattended-run/run-store')
+const { nextStep } = loadCompiled('unattended-run/run-ledger')
+const { unattendedLimits, UNATTENDED_DEFAULTS, ABANDON_MARGIN_MS } = loadCompiled('unattended-run/limits')
+const { languageName, UNATTENDED_RULES } = loadCompiled('unattended-run/unattended-prompt')
+const { assistantRunOutcomeText, ASSISTANT_RUN_OUTCOME_ENGLISH } = loadCompiled('unattended-run/run-outcome')
+
+let db: DataSource
+let domain: any
+let owner: any
+let locked: any
+let admin: any
+
+beforeAll(async () => {
+  db = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, AssistantRun],
+    logging: false
+  })
+  await db.initialize()
+  domain = await db.getRepository(shell.Domain).save({ name: 'acme', subdomain: 'acme' })
+  owner = await db.getRepository(authBase.User).save({ name: 'owner', username: 'owner', email: 'owner@example.com', status: 'activated', locale: 'ko' })
+  locked = await db.getRepository(authBase.User).save({ name: 'locked', username: 'locked', email: 'locked@example.com', status: 'locked' })
+  admin = await db.getRepository(authBase.User).save({ name: 'admin', username: 'admin', email: 'admin@example.com', status: 'activated' })
+})
+
+afterAll(async () => db?.destroy())
+
+const T = (name: string, args: any = {}, id = name) => ({ id, name, arguments: args, type: 'tool_use' })
+const said = (text?: string, calls: any[] = []) => ({ text, toolCalls: calls, stopReason: calls.length ? 'tool_use' : 'end_turn' })
+
+/** A stand-in model: answers from a script, reports usage, and keeps what it was handed. */
+function scriptedModel(script: any[], usage = { inputTokens: 100, outputTokens: 20 }) {
+  const seen: Array<{ messages: any[]; tools: any[]; options: any }> = []
+  let turn = 0
+  const client: any = {
+    id: 'stand-in:model',
+    agent: { id: 'agent-1', name: 'stand-in', provider: 'stand-in', model: 'model' },
+    chat: async () => ({ text: '' }),
+    generateJSON: async () => ({}),
+    listModels: async () => [],
+    chatWithTools: async (messages: any[], tools: any[], options: any) => {
+      seen.push({ messages, tools, options })
+      const step = script[Math.min(turn++, script.length - 1)]
+      options?.onUsage?.(usage)
+      if (typeof step === 'function') return step(options)
+      if (step instanceof Error) throw step
+      return step
+    }
+  }
+  return { client, seen }
+}
+
+let ran: Array<{ tool: string; context: any }>
+let gatesAsked: Array<{ gate: any; userId: string }>
+let clientRequests: any[]
+
+function deps(over: Partial<UnattendedRunDeps> & { model?: any; member?: boolean; granted?: boolean; doors?: string[]; now?: () => Date } = {}): UnattendedRunDeps {
+  const doors = new Set(over.doors ?? ['Query.goals', 'Query.sales', 'Query.cards'])
+  return {
+    store: typeormRunStore(() => db.getRepository(AssistantRun)),
+    runAs: {
+      findUser: id => db.getRepository(authBase.User).findOne({ where: { id } }),
+      mayCheckin: async () => over.member ?? true,
+      permits: async (gate, user) => {
+        gatesAsked.push({ gate, userId: user.id })
+        return over.granted ?? true
+      }
+    },
+    clientFor:
+      over.clientFor ??
+      (async request => {
+        clientRequests.push(request)
+        return over.model ?? scriptedModel([said('the draft')]).client
+      }),
+    toolAccess: over.toolAccess ?? (state => async (door: string) => state.user?.id === owner.id && doors.has(door)),
+    now: over.now ?? (() => new Date())
+  }
+}
+
+let occurrence = 0
+const input = (over: any = {}) => ({
+  domain,
+  runAs: owner.id,
+  run: { source: 'office.strategy-review', subject: 'policy-9', scheduledAt: new Date(Date.UTC(2026, 10, 1, 7, 0, 0) + ++occurrence * 60000) },
+  mode: { kind: 'office.strategy-review', target: 'policy-9' },
+  instruction: 'Review the monthly goals against sales and write the draft.',
+  ...over
+})
+
+beforeEach(() => {
+  ran = []
+  gatesAsked = []
+  clientRequests = []
+  clearToolRegistry()
+  clearToolCallRecorders()
+  clearAssistantModes()
+
+  const read = (name: string, door: string, builder: (args: any) => any) => ({
+    kind: 'read',
+    name,
+    description: name,
+    doors: [door],
+    schema: { type: 'object', properties: {} },
+    builder: (args: any, context: any) => {
+      ran.push({ tool: name, context })
+      return builder(args)
+    }
+  })
+  registerToolCategory({
+    name: 'strategy',
+    guidance: 'Read before you write.',
+    specs: [
+      read('readGoals', 'Query.goals', () => ({ read: 2, rows: [{ id: 'g-1' }, { id: 'g-2' }] })),
+      read('readSales', 'Query.sales', () => {
+        throw new Error('sales could not be read')
+      }),
+      read('readCard', 'Query.cards', () => ({ proposed: true, kind: 'workspace', label: 'a table', forScreen: {} })),
+      read('readPayroll', 'Query.payroll', () => ({ rows: [] }))
+    ]
+  } as any)
+  /* What a conversation of this mode would also open - an unattended run must not. */
+  registerToolCategory({ name: 'data-entry:expense', guidance: 'Propose rows.', specs: [read('proposeExpense', 'Query.goals', () => ({ proposed: true, kind: 'entry' }))] } as any)
+  registerToolCategory({ name: 'assistant-workspace', guidance: 'Put tables there.', specs: [read('showOnWorkspace', 'Query.goals', () => ({ proposed: true, kind: 'workspace' }))] } as any)
+
+  registerAssistantMode({
+    kind: 'office.strategy-review',
+    systemPrompt: 'You review a strategy for its owner.',
+    toolCategories: ['strategy'],
+    entryTargets: ['expense'],
+    unattended: { maxModelCalls: 4, maxTokens: 1000, timeoutMs: 300 }
+  } as any)
+  registerAssistantMode({ kind: 'office.strategy', systemPrompt: 'You talk about strategy with a person.', toolCategories: ['strategy'] } as any)
+})
+
+describe('§3 what runs, and what is kept', () => {
+  it('★ the draft, the reads it rested on with each one ok or failed, the doors, what it spent', async () => {
+    const { client, seen } = scriptedModel([
+      said(undefined, [T('readGoals', { goalId: 'g-1' }), T('readSales'), T('readCard')]),
+      said('Goals are behind; sales could not be read.')
+    ])
+    const run = await runAssistantUnattended(input({ lng: 'ko' }), deps({ model: client }))
+
+    expect(run.status).toBe('succeeded')
+    expect(run.draft).toBe('Goals are behind; sales could not be read.')
+    expect(run.attempt).toBe(1)
+    expect(run.runAsId).toBe(owner.id)
+    const reads = (run as any).readsJson
+    expect(reads.map((one: any) => [one.tool, one.ok, one.errorCode ?? null])).toEqual([
+      ['readGoals', true, null],
+      ['readSales', false, 'tool-threw'],
+      ['readCard', true, null]
+    ])
+    expect(reads[0]).toMatchObject({ category: 'strategy', targetIds: ['g-1'], resultCount: 2 })
+    expect(run.doors).toEqual(['Query.cards', 'Query.goals', 'Query.sales'])
+    expect(run.cardsDropped).toBe(1)
+    expect(run).toMatchObject({ modelCalls: 2, inputTokens: 200, outputTokens: 40, agentId: 'agent-1', clientId: 'stand-in:model' })
+    expect(run.outcomeCode).toBeNull()
+    expect(seen).toHaveLength(2)
+  })
+
+  it('★ only the mode\'s own reads are offered - no 입력안, no 작업판, and none behind a door the owner cannot pass', async () => {
+    const { client, seen } = scriptedModel([said('drafted')])
+    await runAssistantUnattended(input(), deps({ model: client }))
+    expect(seen[0].tools.map((tool: any) => tool.name).sort()).toEqual(['readCard', 'readGoals', 'readSales'])
+  })
+
+  it('★ the tools see the owner as the request user, and the run as context.run', async () => {
+    const { client } = scriptedModel([said(undefined, [T('readGoals')]), said('drafted')])
+    const run = await runAssistantUnattended(input({ hostContext: { policyId: 'policy-9' } }), deps({ model: client }))
+    expect(ran[0].context.state.user.id).toBe(owner.id)
+    expect(ran[0].context.state.domain.id).toBe(domain.id)
+    expect(ran[0].context.host).toEqual({ policyId: 'policy-9' })
+    expect(ran[0].context.mode).toEqual({ kind: 'office.strategy-review', target: 'policy-9' })
+    expect(ran[0].context.run).toEqual({ id: run.id, source: 'office.strategy-review', subject: 'policy-9', scheduledAt: run.scheduledAt.toISOString?.() ?? new Date(run.scheduledAt).toISOString() })
+  })
+
+  it('★ the model is told no one is reading and to write in the owner\'s language - their account\'s when none is given', async () => {
+    const { client, seen } = scriptedModel([said('drafted')])
+    await runAssistantUnattended(input(), deps({ model: client }))
+    expect(seen[0].options.systemPrompt).toContain('You review a strategy for its owner.')
+    expect(seen[0].options.systemPrompt).toContain(UNATTENDED_RULES)
+    expect(seen[0].options.systemPrompt).toContain('Write the draft in Korean.')
+    expect(seen[0].messages).toEqual([{ role: 'user', content: 'Review the monthly goals against sales and write the draft.' }])
+  })
+
+  it('★ every call is handed to the recorders as a turn\'s are, and they can tell it is this run', async () => {
+    const recorded: any[] = []
+    registerToolCallRecorder((record: any, context: any) => {
+      recorded.push({ record, context })
+    })
+    const { client } = scriptedModel([said(undefined, [T('readGoals'), T('readSales')]), said('drafted')])
+    const run = await runAssistantUnattended(input(), deps({ model: client }))
+    expect(recorded.map(one => [one.record.tool, one.record.ok])).toEqual([
+      ['readGoals', true],
+      ['readSales', false]
+    ])
+    expect(recorded.every(one => one.context.run?.id === run.id && one.context.mode.kind === 'office.strategy-review')).toBe(true)
+  })
+
+  it('the categories an unattended run opens - the mode\'s own and the lists it reads', () => {
+    expect(unattendedToolCategories({ toolCategories: ['strategy'], readTargets: ['sales.orders'] })).toEqual(['strategy', 'data-read:sales.orders'])
+    expect(unattendedToolCategories({ toolCategories: ['strategy'], entryTargets: ['expense'], attachments: { kinds: ['image'] } } as any)).toEqual(['strategy'])
+  })
+})
+
+describe('§2 who it runs as', () => {
+  it('★ an owner who is no longer active is refused, and no model is asked', async () => {
+    const run = await runAssistantUnattended(input({ runAs: locked.id }), deps())
+    expect(run).toMatchObject({ status: 'refused', outcomeCode: 'assistant-run-as-inactive', draft: null })
+    expect(clientRequests).toHaveLength(0)
+  })
+
+  it('★ an owner who lost the privilege is refused - the gate asked is the one a person passes to ask, of the owner and no one else', async () => {
+    const run = await runAssistantUnattended(input(), deps({ granted: false }))
+    expect(run).toMatchObject({ status: 'refused', outcomeCode: 'assistant-run-as-not-permitted' })
+    expect(gatesAsked).toEqual([{ gate: { category: 'ai-assistant', privilege: 'mutation', owner: true }, userId: owner.id }])
+    expect(clientRequests).toHaveLength(0)
+  })
+
+  it('★ an owner who cannot enter the domain is refused', async () => {
+    const run = await runAssistantUnattended(input(), deps({ member: false }))
+    expect(run).toMatchObject({ status: 'refused', outcomeCode: 'assistant-run-as-not-member' })
+  })
+
+  it('an owner who does not exist is refused', async () => {
+    const run = await runAssistantUnattended(input({ runAs: '00000000-0000-0000-0000-000000000000' }), deps())
+    expect(run).toMatchObject({ status: 'refused', outcomeCode: 'assistant-run-as-unknown', runAsId: null })
+    expect((run as any).outcomeParamsJson).toEqual({ userId: '00000000-0000-0000-0000-000000000000' })
+    expect(clientRequests).toHaveLength(0)
+  })
+
+  it('★ the model client is the owner\'s - asked for this domain, this person and this mode', async () => {
+    await runAssistantUnattended(input(), deps())
+    expect(clientRequests).toHaveLength(1)
+    expect(clientRequests[0].domain.id).toBe(domain.id)
+    expect(clientRequests[0].user.id).toBe(owner.id)
+    expect(clientRequests[0].modeKind).toBe('office.strategy-review')
+  })
+
+  it('a domain with no AI is refused by its own code', async () => {
+    const error: any = new Error('AI is not set up for this domain.')
+    error.code = 'ai-not-configured'
+    const run = await runAssistantUnattended(input(), deps({ clientFor: async () => Promise.reject(error) }))
+    expect(run).toMatchObject({ status: 'refused', outcomeCode: 'ai-not-configured' })
+  })
+
+  it('★ a mode that did not declare unattended does not run without a person; nor does one nobody registered', async () => {
+    const plain = await runAssistantUnattended(input({ mode: { kind: 'office.strategy' } }), deps())
+    expect(plain).toMatchObject({ status: 'refused', outcomeCode: 'assistant-mode-not-unattended' })
+    const unknown = await runAssistantUnattended(input({ mode: { kind: 'office.nothing' } }), deps())
+    expect(unknown).toMatchObject({ status: 'refused', outcomeCode: 'unknown-assistant-mode' })
+    expect(clientRequests).toHaveLength(0)
+  })
+
+  it('an unusable request is thrown back and stores nothing', async () => {
+    const before = await db.getRepository(AssistantRun).count()
+    await expect(runAssistantUnattended(input({ run: { source: 'office.strategy-review', subject: 'p', scheduledAt: new Date('nope') } }), deps())).rejects.toMatchObject({
+      code: 'assistant-run-input-invalid',
+      params: { field: 'run.scheduledAt' }
+    })
+    await expect(runAssistantUnattended(input({ instruction: '  ' }), deps())).rejects.toMatchObject({ params: { field: 'instruction' } })
+    expect(await db.getRepository(AssistantRun).count()).toBe(before)
+  })
+})
+
+describe('§4 · §7 limits, and failures said as failures', () => {
+  it('★ past the token limit the next request is refused, and the run failed by that limit', async () => {
+    const { client, seen } = scriptedModel([said(undefined, [T('readGoals')])], { inputTokens: 700, outputTokens: 100 })
+    const run = await runAssistantUnattended(input(), deps({ model: client }))
+    expect(run).toMatchObject({ status: 'failed', outcomeCode: 'assistant-run-budget-exceeded', draft: null, modelCalls: 2, inputTokens: 1400 })
+    expect((run as any).outcomeParamsJson).toEqual({ limit: 'tokens', max: 1000, used: 1600 })
+    expect(seen).toHaveLength(2)
+  })
+
+  it('★ a run that reaches its last step without an answer failed - no wrap-up call, no cut-short draft', async () => {
+    const { client, seen } = scriptedModel([said('half a thought', [T('readGoals')])])
+    const run = await runAssistantUnattended(input(), deps({ model: client }))
+    expect(run).toMatchObject({ status: 'failed', outcomeCode: 'assistant-run-step-limit', draft: null })
+    expect(seen).toHaveLength(4)
+    expect(seen.every(one => one.options.toolChoice !== 'none')).toBe(true)
+  })
+
+  it('★ past its time the run is stopped and failed by time - the provider request was told to stop', async () => {
+    let signal: AbortSignal | undefined
+    const { client } = scriptedModel([
+      (options: any) =>
+        new Promise(() => {
+          signal = options.signal
+        })
+    ])
+    const started = Date.now()
+    const run = await runAssistantUnattended(input(), deps({ model: client }))
+    expect(run).toMatchObject({ status: 'failed', outcomeCode: 'assistant-run-timeout', draft: null })
+    expect((run as any).outcomeParamsJson).toEqual({ timeoutMs: 300 })
+    expect(Date.now() - started).toBeLessThan(2000)
+    expect(signal?.aborted).toBe(true)
+  })
+
+  it('★ an empty answer is not a draft', async () => {
+    const { client } = scriptedModel([said('   ')])
+    const run = await runAssistantUnattended(input(), deps({ model: client }))
+    expect(run).toMatchObject({ status: 'failed', outcomeCode: 'assistant-run-empty-draft', draft: null })
+  })
+
+  it('★ a provider that fails is a failure, never a success with the stop notice as its draft', async () => {
+    const failure: any = new Error('upstream exploded')
+    failure.status = 400
+    const { client } = scriptedModel([failure])
+    const run = await runAssistantUnattended(input(), deps({ model: client }))
+    expect(run).toMatchObject({ status: 'failed', outcomeCode: 'assistant-run-model-error', draft: null })
+    expect((run as any).outcomeParamsJson.message).toContain('upstream exploded')
+  })
+
+  it('the limits are the mode\'s, each absent one at its default', () => {
+    expect(unattendedLimits(undefined)).toEqual(UNATTENDED_DEFAULTS)
+    expect(unattendedLimits({ maxModelCalls: 3, timeoutMs: -1 } as any)).toEqual({ ...UNATTENDED_DEFAULTS, maxModelCalls: 3 })
+    expect(languageName('ko-KR')).toBe('Korean')
+    expect(languageName(undefined)).toBe('English')
+  })
+})
+
+describe('§5 one occurrence, one row', () => {
+  it('★ the same occurrence again hands the stored draft back and asks no model', async () => {
+    const first = scriptedModel([said('the draft')])
+    const at = input()
+    const run = await runAssistantUnattended(at, deps({ model: first.client }))
+    clientRequests.length = 0
+    const again = await runAssistantUnattended({ ...at, run: { ...at.run, scheduledAt: new Date(at.run.scheduledAt) } }, deps())
+    expect(again.id).toBe(run.id)
+    expect(again).toMatchObject({ status: 'succeeded', draft: 'the draft', attempt: 1 })
+    expect(clientRequests).toHaveLength(0)
+    expect(await db.getRepository(AssistantRun).count({ where: { subject: 'policy-9', scheduledAt: at.run.scheduledAt } as any })).toBe(1)
+  })
+
+  it('★ a failed occurrence runs again as the next attempt, and the first attempt\'s ending is kept', async () => {
+    const at = input()
+    const failing = scriptedModel([said('')])
+    await runAssistantUnattended(at, deps({ model: failing.client }))
+    const run = await runAssistantUnattended(at, deps({ model: scriptedModel([said('second time')]).client }))
+    expect(run).toMatchObject({ status: 'succeeded', draft: 'second time', attempt: 2, outcomeCode: null })
+    expect((run as any).attemptsJson).toEqual([expect.objectContaining({ attempt: 1, status: 'failed', outcomeCode: 'assistant-run-empty-draft' })])
+  })
+
+  it('★ a refused occurrence runs again once the owner may - and is judged again, not remembered', async () => {
+    const at = input()
+    const refused = await runAssistantUnattended(at, deps({ granted: false }))
+    expect(refused.status).toBe('refused')
+    const run = await runAssistantUnattended(at, deps())
+    expect(run).toMatchObject({ status: 'succeeded', attempt: 2 })
+  })
+
+  it('★ a running attempt is left alone until its deadline, then taken over as abandoned', async () => {
+    const at = input()
+    const t0 = Date.now()
+    /* A server that started the run and died: the row is running with a deadline. */
+    const store = typeormRunStore(() => db.getRepository(AssistantRun))
+    const { row } = await store.claim(
+      { domainId: domain.id, ...at.run },
+      { name: 'x', modeKind: at.mode.kind, runAsId: owner.id, startedAt: new Date(t0), deadlineAt: new Date(t0 + 300 + ABANDON_MARGIN_MS) },
+      new Date(t0)
+    )
+
+    const early = await runAssistantUnattended(at, deps({ now: () => new Date(t0 + 1000) }))
+    expect(early).toMatchObject({ id: row.id, status: 'running', attempt: 1 })
+    expect(clientRequests).toHaveLength(0)
+
+    const late = await runAssistantUnattended(at, deps({ now: () => new Date(t0 + 300 + ABANDON_MARGIN_MS + 1) }))
+    expect(late).toMatchObject({ id: row.id, status: 'succeeded', attempt: 2 })
+    expect((late as any).attemptsJson).toEqual([expect.objectContaining({ attempt: 1, status: 'failed', outcomeCode: 'assistant-run-abandoned' })])
+  })
+
+  it('★ an attempt that was taken over and ends late writes nothing over the next one', async () => {
+    const at = input()
+    const store = typeormRunStore(() => db.getRepository(AssistantRun))
+    const identity = { domainId: domain.id, ...at.run }
+    const t0 = Date.now()
+    const start = (at0: number) => ({ name: 'x', modeKind: at.mode.kind, runAsId: owner.id, startedAt: new Date(at0), deadlineAt: new Date(at0 + 1000) })
+    const first = await store.claim(identity, start(t0), new Date(t0))
+    const second = await store.claim(identity, start(t0 + 2000), new Date(t0 + 2000))
+    expect([first.claimed, second.claimed, second.row.attempt]).toEqual([true, true, 2])
+
+    const after = await store.finish({ id: first.row.id!, attempt: 1 }, { status: 'succeeded', draft: 'stale' })
+    expect(after).toMatchObject({ status: 'running', attempt: 2, draft: null })
+  })
+
+  it('the ledger rule by itself', () => {
+    const now = new Date('2026-11-01T07:00:00Z')
+    expect(nextStep({ status: 'succeeded' }, now)).toBe('return')
+    expect(nextStep({ status: 'running', deadlineAt: new Date(now.valueOf() + 1) }, now)).toBe('return')
+    expect(nextStep({ status: 'running', deadlineAt: new Date(now.valueOf() - 1) }, now)).toBe('retake')
+    expect(nextStep({ status: 'running', deadlineAt: null }, now)).toBe('return')
+    expect(nextStep({ status: 'failed' }, now)).toBe('retake')
+    expect(nextStep({ status: 'refused' }, now)).toBe('retake')
+  })
+})
+
+describe('no one else to run as', () => {
+  it('★ the request has one user field - a refused owner is never swapped for anyone with the privilege', async () => {
+    const run = await runAssistantUnattended(input({ runAs: locked.id }), deps())
+    expect(run.status).toBe('refused')
+    expect(gatesAsked.some(one => one.userId === admin.id)).toBe(false)
+    expect(ran).toHaveLength(0)
+  })
+})
+
+describe('§7 the outcome as a person reads it', () => {
+  it('★ every code a run can end with has its sentence, filled from its values', async () => {
+    const source = require('fs').readFileSync(require('path').join(__dirname, 'run-unattended.ts'), 'utf8') + require('fs').readFileSync(require('path').join(__dirname, 'run-as.ts'), 'utf8') + require('fs').readFileSync(require('path').join(__dirname, 'run-store.ts'), 'utf8') + require('fs').readFileSync(require('path').join(__dirname, 'run-budget.ts'), 'utf8')
+    const codes = [...new Set([...source.matchAll(/'((?:assistant-run|assistant-mode|unknown-assistant)-[a-z-]+)'/g)].map(match => match[1]))].filter(code => code !== 'assistant-run-input-invalid')
+    expect(codes.length).toBeGreaterThanOrEqual(12)
+    expect(codes.filter(code => !ASSISTANT_RUN_OUTCOME_ENGLISH[code])).toEqual([])
+
+    const { client } = scriptedModel([said('')])
+    const run = await runAssistantUnattended(input({ mode: { kind: 'office.strategy' } }), deps({ model: client }))
+    expect(assistantRunOutcomeText(run)).toBe('the assistant mode office.strategy does not run without a person.')
+    const asked: any[] = []
+    assistantRunOutcomeText(run, (key: string, options: any) => (asked.push([key, options]), 'translated'))
+    expect(asked).toEqual([['ai-assistant.run.assistant-mode-not-unattended', { kind: 'office.strategy', defaultValue: ASSISTANT_RUN_OUTCOME_ENGLISH['assistant-mode-not-unattended'] }]])
+    expect(assistantRunOutcomeText({ outcomeCode: null })).toBeUndefined()
+  })
+
+  it('★ every locale says every outcome, with the same values in it as the English', () => {
+    const { readFileSync } = require('fs')
+    const { join } = require('path')
+    const holes = (text: string) => [...String(text).matchAll(/\{(\w+)\}/g)].map(match => match[1]).sort()
+    const wrong: string[] = []
+    for (const lng of ['en', 'ko', 'ja', 'zh', 'es', 'ms']) {
+      const entries = JSON.parse(readFileSync(join(__dirname, '..', '..', '..', 'translations', `${lng}.json`), 'utf8'))
+      for (const [code, english] of Object.entries(ASSISTANT_RUN_OUTCOME_ENGLISH)) {
+        const said = entries[`ai-assistant.run.${code}`]
+        if (!said) wrong.push(`${lng} ${code}: missing`)
+        else if (JSON.stringify(holes(said)) !== JSON.stringify(holes(english as string))) wrong.push(`${lng} ${code}: ${said}`)
+        else if (lng === 'en' && said !== english) wrong.push(`en ${code}: differs from the default`)
+      }
+    }
+    expect(wrong).toEqual([])
+  })
+})