@things-factory/ai-assistant 10.1.203 → 10.1.205

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.203",
+  "version": "10.1.205",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -35,13 +35,13 @@
     "@operato/shell": "^10.29.39",
     "@operato/styles": "^10.0.0",
     "@operato/utils": "^10.29.39",
-    "@things-factory/ai-client-base": "^10.1.203",
-    "@things-factory/apptool-base": "^10.1.188",
-    "@things-factory/attachment-base": "^10.1.203",
-    "@things-factory/auth-base": "^10.1.203",
+    "@things-factory/ai-client-base": "^10.1.205",
+    "@things-factory/apptool-base": "^10.1.205",
+    "@things-factory/attachment-base": "^10.1.205",
+    "@things-factory/auth-base": "^10.1.205",
     "@things-factory/env": "^10.1.149",
-    "@things-factory/setting-base": "^10.1.203",
-    "@things-factory/shell": "^10.1.188",
+    "@things-factory/setting-base": "^10.1.205",
+    "@things-factory/shell": "^10.1.205",
     "dompurify": "^3.0.0",
     "exceljs": "4.2.0",
     "graphql-scalars": "^1.22.0",
@@ -55,5 +55,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "031aaae3b75b2975e6bce007b3ad7d8d74fe60c8"
+  "gitHead": "7311492aa5eaa00993c0325053f5f7ae8b1fb024"
 }

package/server/service/assistant-mode/index.ts

@@ -13,5 +13,5 @@ export {
 } from './registry.js'
 export { resolveModeSettings, assistantModeView } from './resolve.js'
 export { ABSENCE_RULE, NEXT_REQUEST_RULE, conversationPrompt, splitNextRequest } from './screen-rules.js'
-export type { AssistantModeSpec, AssistantModeSlash, AssistantModeWarning } from './types.js'
+export type { AssistantModeSpec, AssistantModeSlash, AssistantModeWarning, UnattendedLimits } from './types.js'
 export type { AssistantModeRef, ModeSettings, AssistantModeView, AssistantModeSlashView, Translate } from './resolve.js'

package/server/service/assistant-mode/mode-categories.ts

@@ -13,3 +13,13 @@ export function modeToolCategories(mode: { toolCategories?: string[]; attachment
   ]
   return [...new Set([...(mode.toolCategories ?? []), ...extra])]
 }
+
+/**
+ * The categories an unattended run of a mode opens: its own and the lists it reads (design/ai/unattended-run.md §3).
+ *
+ * Not the 입력안 tools - nobody is there to press the card - nor the AI 작업판 or the attachment reader: there is no
+ * conversation for a card or a file to belong to.
+ */
+export function unattendedToolCategories(mode: { toolCategories?: string[]; readTargets?: string[] }): string[] {
+  return [...new Set([...(mode.toolCategories ?? []), ...(mode.readTargets ?? []).map(key => `data-read:${key}`)])]
+}

package/server/service/assistant-mode/types.ts

@@ -95,6 +95,21 @@ export interface AssistantModeSpec {
   stagedNoticeKey?: string
   /** Follow-up chips for a proposal that arrived without its own. */
   proposalChoices?: any[]
+  /**
+   * This mode may run with no person in it - a scheduled draft (design/ai/unattended-run.md §4). Absent: it may not.
+   * The limits are the mode's, as every limit is (ADR-0061 decision 7); the caller does not name them.
+   */
+  unattended?: UnattendedLimits
+}
+
+/** What one unattended run of a mode may spend. Each absent one takes the default in `unattended-run/limits.ts`. */
+export interface UnattendedLimits {
+  /** Model requests of one run, the wrap-up included. */
+  maxModelCalls?: number
+  /** Input and output tokens of one run together. The request that crosses it is the last one. */
+  maxTokens?: number
+  /** Wall time of one run, model requests and tool calls together. */
+  timeoutMs?: number
 }
 
 /** A declaration that registered but is not what the contract asks for. Code + params, not prose. */

package/server/service/index.ts

@@ -13,6 +13,7 @@ import './chat-session/session-purge.js'
 import './chat-session/attachment-route.js'
 import { EntryProposalResolver } from './data-entry/entry-resolver.js'
 import './workspace/workspace-tools.js'
+import { entities as UnattendedRunEntities } from './unattended-run/index.js'
 
 export * from './types.js'
 export * from './chat-session-resolver.js'
@@ -61,8 +62,10 @@ export * from './chat-session-participant/mention-invite.js'
 export * from './chat-session-participant/presence.js'
 export * from './chat-message/index.js'
 export * from './chat-session-participant/index.js'
+/* A mode run with no person in it - a scheduled draft (operato-application/design/ai/unattended-run.md). */
+export * from './unattended-run/index.js'
 
-export const entities = [...ChatSessionEntities, ...ChatMessageEntities, ...ChatSessionParticipantEntities]
+export const entities = [...ChatSessionEntities, ...ChatMessageEntities, ...ChatSessionParticipantEntities, ...UnattendedRunEntities]
 
 export const schema = {
   resolverClasses: [

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

@@ -0,0 +1,199 @@
+/**
+ * AssistantRun — one occurrence of a mode run with no person in it, and what it left (design/ai/unattended-run.md).
+ *
+ * The one place the facts of an AI run are kept: its attempts, its state, the draft, the reads the draft rested on,
+ * what it spent and the doors behind it. The application that scheduled it keeps its own facts and points here by
+ * (source, subject, scheduledAt) or by id - it does not copy these (chief architect ruling, 2026-10-20).
+ */
+import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId, UpdateDateColumn } from 'typeorm'
+import { Field, ID, Int, ObjectType } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+import { config } from '@things-factory/env'
+
+const ORMCONFIG = config.get('ormconfig', {})
+const DATABASE_TYPE = ORMCONFIG.type
+
+const LONG_TEXT = {
+  type:
+    DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+      ? 'longtext'
+      : DATABASE_TYPE == 'oracle'
+        ? 'clob'
+        : DATABASE_TYPE == 'mssql'
+          ? 'nvarchar'
+          : 'text',
+  length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined,
+  nullable: true
+} as const
+
+const parsed = (text?: string | null) => {
+  if (!text) return null
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+@Entity()
+/* One occurrence, one row - two first calls at once make one row and the other reads it (§5). */
+@Index('ix_assistant_run_0', (run: AssistantRun) => [run.domain, run.source, run.subject, run.scheduledAt], { unique: true })
+@Index('ix_assistant_run_1', (run: AssistantRun) => [run.domain, run.source, run.subject, run.createdAt])
+@ObjectType({ description: 'One scheduled run of an assistant mode with no person in it, and the draft it left.' })
+export class AssistantRun {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Run id.' })
+  readonly id?: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'The domain the run is in.' })
+  domain?: Domain
+
+  @RelationId((run: AssistantRun) => run.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'Readable name of the occurrence - source, subject and time.' })
+  name: string
+
+  @Column({ type: 'text', nullable: true })
+  @Field({ nullable: true, description: 'Description.' })
+  description?: string
+
+  @Column({ length: 64 })
+  @Field({ description: "Who scheduled it - '<app>.<work>', e.g. 'office.strategy-review'." })
+  source: string
+
+  @Column({ length: 64 })
+  @Field({ description: "What it is about in the source's terms, e.g. a policy id." })
+  subject: string
+
+  @Column()
+  @Field({ description: 'The occurrence this run is.' })
+  scheduledAt: Date
+
+  @Column({ length: 64 })
+  @Field({ description: 'The assistant mode that ran.' })
+  modeKind: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'What the mode was about.' })
+  modeTarget?: string
+
+  @ManyToOne(type => User)
+  @Field(type => User, { nullable: true, description: 'The person the run acted as - its privileges and doors were theirs.' })
+  runAs?: User
+
+  @RelationId((run: AssistantRun) => run.runAs)
+  runAsId?: string
+
+  @Column({ length: 16 })
+  @Field({ description: "'running' | 'succeeded' | 'failed' | 'refused'." })
+  status: string
+
+  @Column({ type: 'int', default: 1 })
+  @Field(type => Int, { description: 'Which attempt at this occurrence the row holds, from 1.' })
+  attempt: number
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When this attempt started.' })
+  startedAt?: Date
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Past this a running attempt is taken as gone and the next call takes the occurrence over.' })
+  deadlineAt?: Date
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When this attempt ended.' })
+  finishedAt?: Date
+
+  @Column(LONG_TEXT as any)
+  @Field({ nullable: true, description: 'The draft - only when the run succeeded.' })
+  draft?: string
+
+  /** Each call of the run as the audit digests it (`ToolCallRecord`, never raw values), as JSON. */
+  @Column(LONG_TEXT as any)
+  reads?: string
+
+  @Field(() => GraphQLJSON, { nullable: true, description: 'The reads the draft rested on: tool, category, ids, rows, hash, ok or the error code.' })
+  get readsJson(): any {
+    return parsed(this.reads)
+  }
+
+  @Column({ type: 'simple-array', nullable: true })
+  @Field(() => [String], { nullable: true, description: 'GraphQL doors the reads went through. A reader of the draft must pass all of them.' })
+  doors?: string[]
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Why it failed or was refused - a code; the screen says it.' })
+  outcomeCode?: string
+
+  @Column({ type: 'text', nullable: true })
+  outcomeParams?: string
+
+  @Field(() => GraphQLJSON, { nullable: true, description: 'Values of the outcome code.' })
+  get outcomeParamsJson(): any {
+    return parsed(this.outcomeParams)
+  }
+
+  /** The earlier attempts' endings, `[{ attempt, status, outcomeCode, startedAt, finishedAt }]`, as JSON. */
+  @Column({ type: 'text', nullable: true })
+  attempts?: string
+
+  @Field(() => GraphQLJSON, { nullable: true, description: 'How the earlier attempts ended.' })
+  get attemptsJson(): any {
+    return parsed(this.attempts)
+  }
+
+  @Column({ type: 'varchar', length: 1024, nullable: true })
+  groundingWarnings?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The AI agent that answered.' })
+  agentId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'provider:model.' })
+  clientId?: string
+
+  @Column({ type: 'int', default: 0 })
+  @Field(type => Int, { description: 'Model requests of this attempt.' })
+  modelCalls: number
+
+  @Column({ type: 'int', default: 0 })
+  @Field(type => Int, { description: 'Input tokens of this attempt.' })
+  inputTokens: number
+
+  @Column({ type: 'int', default: 0 })
+  @Field(type => Int, { description: 'Output tokens of this attempt.' })
+  outputTokens: number
+
+  @Column({ type: 'int', default: 0 })
+  @Field(type => Int, { description: 'Cards a read offered that were not kept - there was no person to press them.' })
+  cardsDropped: number
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'Creator.' })
+  creator?: User
+
+  @RelationId((run: AssistantRun) => run.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'Last updater.' })
+  updater?: User
+
+  @RelationId((run: AssistantRun) => run.updater)
+  updaterId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Creation timestamp.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'Last update timestamp.' })
+  updatedAt?: Date
+}

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

@@ -0,0 +1,10 @@
+import { AssistantRun } from './assistant-run.js'
+
+export { AssistantRun }
+export { runAssistantUnattended, findAssistantRun } from './run-unattended.js'
+export type { UnattendedRunInput, UnattendedRunDeps } from './run-unattended.js'
+export { UNATTENDED_DEFAULTS } from './limits.js'
+export { assistantRunOutcomeText, ASSISTANT_RUN_OUTCOME_ENGLISH } from './run-outcome.js'
+export type { AssistantRunStatus } from './run-ledger.js'
+
+export const entities = [AssistantRun]

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

@@ -0,0 +1,24 @@
+/* Pure. What one unattended run of a mode may spend (design/ai/unattended-run.md §4). */
+import type { UnattendedLimits } from '../assistant-mode/types.js'
+
+export const UNATTENDED_DEFAULTS: Required<UnattendedLimits> = {
+  maxModelCalls: 8,
+  maxTokens: 60000,
+  timeoutMs: 120000
+}
+
+/**
+ * How long past its time limit a running attempt is still taken as alive. A server that died mid-run leaves the row
+ * `running`; past this the next call takes the occurrence over (§5).
+ */
+export const ABANDON_MARGIN_MS = 30000
+
+/** The mode's limits, each absent or unusable one at its default. */
+export function unattendedLimits(declared: UnattendedLimits | undefined): Required<UnattendedLimits> {
+  const pick = (value: unknown, fallback: number) => (typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback)
+  return {
+    maxModelCalls: Math.floor(pick(declared?.maxModelCalls, UNATTENDED_DEFAULTS.maxModelCalls)),
+    maxTokens: pick(declared?.maxTokens, UNATTENDED_DEFAULTS.maxTokens),
+    timeoutMs: pick(declared?.timeoutMs, UNATTENDED_DEFAULTS.timeoutMs)
+  }
+}

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

@@ -0,0 +1,38 @@
+/*
+ * Who the run is - judged again at every run (design/ai/unattended-run.md §2, ADR-0142 §8.1).
+ *
+ * The run acts for the policy owner and for no one else. There is no second user to fall back to: a refused owner
+ * means a refused run, never one under an administrator.
+ */
+
+/** The same door a person passes to ask the assistant (`assistantChat`). */
+export const ASK_ASSISTANT_GATE = { category: 'ai-assistant', privilege: 'mutation', owner: true }
+
+export type RunAsRefusal =
+  | 'assistant-run-as-unknown'
+  | 'assistant-run-as-inactive'
+  | 'assistant-run-as-not-member'
+  | 'assistant-run-as-not-permitted'
+
+export interface RunAsChecks<TUser, TDomain> {
+  /** The user as stored now - not as the caller last saw them. */
+  findUser: (id: string) => Promise<TUser | undefined | null>
+  /** Whether they can enter this domain - auth-base `canUserCheckinDomain`. */
+  mayCheckin: (user: TUser, domain: TDomain) => Promise<boolean>
+  /** auth-base `checkPermission`, with no address and no prohibitions: there is no request. */
+  permits: (gate: typeof ASK_ASSISTANT_GATE, user: TUser, domain: TDomain) => Promise<boolean>
+}
+
+/** `user` is the account as `findUser` read it just now - absent when there is none. */
+export async function judgeRunAs<TUser extends { id?: string; status?: string }, TDomain>(
+  user: TUser | undefined | null,
+  domain: TDomain,
+  checks: Omit<RunAsChecks<TUser, TDomain>, 'findUser'>
+): Promise<{ user: TUser } | { refused: RunAsRefusal }> {
+  if (!user) return { refused: 'assistant-run-as-unknown' }
+  /* Only an account that can sign in now. Locked, banned, deleted, or one waiting for a password reset is not. */
+  if (user.status !== 'activated') return { refused: 'assistant-run-as-inactive' }
+  if (!(await checks.mayCheckin(user, domain))) return { refused: 'assistant-run-as-not-member' }
+  if (!(await checks.permits(ASK_ASSISTANT_GATE, user, domain))) return { refused: 'assistant-run-as-not-permitted' }
+  return { user }
+}

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

@@ -0,0 +1,58 @@
+/*
+ * The client one unattended run talks through - it counts what the run spends and refuses the request past the limit
+ * (design/ai/unattended-run.md §4).
+ *
+ * It wraps the domain's metered client, so every request still writes its AiUsage row at the provider boundary
+ * (ADR-0061 decision 6); this only adds the run's own ceiling.
+ */
+import type { AgentClient } from '@things-factory/ai-client-base'
+
+export interface RunSpend {
+  modelCalls: number
+  inputTokens: number
+  outputTokens: number
+  /** Set once a request was refused, with the limit it hit. */
+  exceeded?: { limit: 'model-calls' | 'tokens'; max: number; used: number }
+}
+
+export class RunBudgetExceeded extends Error {
+  readonly code = 'assistant-run-budget-exceeded'
+  constructor(readonly params: NonNullable<RunSpend['exceeded']>) {
+    super(`the run reached its ${params.limit} limit (${params.used} of ${params.max})`)
+  }
+}
+
+export function budgetedClient(client: AgentClient, limits: { maxModelCalls: number; maxTokens: number }): { client: AgentClient; spend: RunSpend } {
+  const spend: RunSpend = { modelCalls: 0, inputTokens: 0, outputTokens: 0 }
+
+  const admit = () => {
+    if (spend.modelCalls >= limits.maxModelCalls) {
+      spend.exceeded ??= { limit: 'model-calls', max: limits.maxModelCalls, used: spend.modelCalls }
+    } else if (spend.inputTokens + spend.outputTokens >= limits.maxTokens) {
+      spend.exceeded ??= { limit: 'tokens', max: limits.maxTokens, used: spend.inputTokens + spend.outputTokens }
+    }
+    if (spend.exceeded) throw new RunBudgetExceeded(spend.exceeded)
+    spend.modelCalls++
+  }
+
+  const counted = (options: any) => ({
+    ...options,
+    onUsage: (usage: any) => {
+      spend.inputTokens += Number(usage?.inputTokens) || 0
+      spend.outputTokens += Number(usage?.outputTokens) || 0
+      options?.onUsage?.(usage)
+    }
+  })
+
+  const wrapped: AgentClient = {
+    id: client.id,
+    agent: client.agent,
+    chat: (messages, options) => (admit(), client.chat(messages, counted(options))),
+    generateJSON: (prompt, options) => (admit(), client.generateJSON(prompt, counted(options))),
+    ...(client.chatWithTools && {
+      chatWithTools: (messages, tools, options) => (admit(), client.chatWithTools!(messages, tools, counted(options)))
+    }),
+    listModels: () => client.listModels()
+  } as AgentClient
+  return { client: wrapped, spend }
+}

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

@@ -0,0 +1,31 @@
+/*
+ * Pure. What a call for an occurrence that already has a row does (design/ai/unattended-run.md §5).
+ *
+ * One row is one occurrence - (domain, source, subject, scheduledAt). scheduler-client calls again when an answer came
+ * late or failed; a second call must not run the model a second time while the first is alive or after it succeeded.
+ */
+
+export type AssistantRunStatus = 'running' | 'succeeded' | 'failed' | 'refused'
+
+export interface LedgerRow {
+  status: AssistantRunStatus | string
+  deadlineAt?: Date | string | null
+}
+
+/**
+ * `return` - hand the stored row back, run nothing. `retake` - start the next attempt on the same row.
+ *
+ * A succeeded run is the answer. A running one is left alone until its deadline; past it the server that held it is
+ * taken as gone. A failed or refused one runs again - a retry is for exactly that, and how many retries there are is
+ * the caller's limit (scheduler-client `max_retry_count`), not this one's.
+ */
+export function nextStep(row: LedgerRow, now: Date): 'return' | 'retake' {
+  if (row.status === 'succeeded') return 'return'
+  if (row.status === 'running') {
+    const deadline = row.deadlineAt ? new Date(row.deadlineAt).valueOf() : NaN
+    /* A running row with no readable deadline is not taken over - two runs at once is the one thing this prevents. */
+    if (!Number.isFinite(deadline)) return 'return'
+    return deadline > now.valueOf() ? 'return' : 'retake'
+  }
+  return 'retake'
+}

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

@@ -0,0 +1,43 @@
+/*
+ * Why a run failed or was refused, as a person reads it (design/ai/unattended-run.md §7).
+ *
+ * The run keeps a code and its values (ADR-0054); the sentence is made where it is shown, under this package's key
+ * `ai-assistant.run.<code>` - an outcome is a stored value, not a thrown refusal. The English below is the sentence
+ * when no translation has the key; the application that shows a run does not write its own.
+ */
+
+export const outcomeKey = (code: string) => `ai-assistant.run.${code}`
+
+export const ASSISTANT_RUN_OUTCOME_ENGLISH: Record<string, string> = {
+  'assistant-run-as-unknown': 'the account the run was to act as does not exist.',
+  'assistant-run-as-inactive': "the owner's account is not active, so the run did not start.",
+  'assistant-run-as-not-member': 'the owner can no longer enter this domain, so the run did not start.',
+  'assistant-run-as-not-permitted': 'the owner may no longer ask the AI assistant, so the run did not start.',
+  'assistant-mode-not-unattended': 'the assistant mode {kind} does not run without a person.',
+  'unknown-assistant-mode': 'this server has no assistant mode {kind}.',
+  'assistant-run-budget-exceeded': 'the run reached its {limit} limit ({used} of {max}) and stopped.',
+  'assistant-run-step-limit': 'the run did not finish within {steps} steps.',
+  'assistant-run-timeout': 'the run did not finish within {timeoutMs} ms.',
+  'assistant-run-empty-draft': 'the run ended without writing a draft.',
+  'assistant-run-model-error': 'the AI model failed during the run.',
+  'assistant-run-abandoned': 'the run stopped partway and was started again.',
+  'ai-not-configured': 'AI is not set up for this domain.',
+  'ai-agent-not-available': 'the AI agent picked for this run is not available here.'
+}
+
+type Translate = (key: string, options?: Record<string, unknown>) => string
+
+/** The sentence for a run's outcome, or undefined when it has none (running, or succeeded). */
+export function assistantRunOutcomeText(run: { outcomeCode?: string | null; outcomeParams?: string | null }, t?: Translate): string | undefined {
+  const code = run?.outcomeCode
+  if (!code) return undefined
+  let params: Record<string, unknown> = {}
+  try {
+    params = run.outcomeParams ? JSON.parse(run.outcomeParams) : {}
+  } catch {
+    params = {}
+  }
+  const english = ASSISTANT_RUN_OUTCOME_ENGLISH[code] ?? code
+  const fill = (text: string) => text.replace(/\{(\w+)\}/g, (_, name) => (params[name] === undefined ? `{${name}}` : String(params[name])))
+  return t ? t(outcomeKey(code), { ...params, defaultValue: english }) : fill(english)
+}

package/server/service/unattended-run/run-store-race.pg.test.ts

@@ -0,0 +1,83 @@
+import { join } from 'path'
+
+/**
+ * Two calls for one occurrence at the same moment, on postgres (operato-application/design/ai/unattended-run.md §5).
+ *
+ * sqlite holds one connection and cannot run two transactions side by side, so what it says about this is no
+ * evidence either way. This needs a real server, and runs only when AI_ASSISTANT_PG_URL names one:
+ *
+ *   docker run -d --name ai-run-pg -e POSTGRES_PASSWORD=airun -e POSTGRES_USER=airun -e POSTGRES_DB=airun \
+ *     -p 55434:5432 postgres:14-alpine
+ *   AI_ASSISTANT_PG_URL=postgres://airun:airun@localhost:55434/airun npx jest --runInBand \
+ *     packages/ai-assistant/server/service/unattended-run/run-store-race.pg.test.ts
+ *
+ * It reads `dist-server` - build ai-assistant first.
+ *
+ * Each round must end with exactly one of the two holding the attempt: two first calls make one row, and two calls
+ * taking over one failed occurrence make one next attempt. Both holding it is the defect - the model runs twice.
+ */
+
+const url = process.env.AI_ASSISTANT_PG_URL
+const maybe = url ? describe : describe.skip
+
+maybe('two calls for one occurrence at once, on postgres', () => {
+  const { DataSource } = require('typeorm')
+  const { entityClosure } = require(join(__dirname, '..', '..', '..', '..', 'ops-master', 'test', 'support', 'database.cjs'))
+  const { NamingStrategy } = require('@things-factory/shell/dist-server/initializers/naming-strategy.js')
+  const DIST = join(__dirname, '..', '..', '..', 'dist-server', 'service', 'unattended-run')
+  const { AssistantRun } = require(join(DIST, 'assistant-run.js'))
+  const { typeormRunStore } = require(join(DIST, 'run-store.js'))
+  const { Domain } = require('@things-factory/shell')
+  const { User } = require('@things-factory/auth-base')
+
+  let db: any
+  let domain: any
+  let owner: any
+
+  beforeAll(async () => {
+    db = new DataSource({
+      type: 'postgres',
+      url,
+      synchronize: true,
+      dropSchema: true,
+      entities: entityClosure([AssistantRun]),
+      namingStrategy: new NamingStrategy()
+    })
+    await db.initialize()
+    domain = await db.getRepository(Domain).save({ name: 'd', subdomain: 'd' })
+    owner = await db.getRepository(User).save({ name: 'o', username: 'o', email: 'o@example.com', status: 'activated' })
+  }, 60000)
+
+  afterAll(async () => db?.destroy())
+
+  /* Each call on its own connection, as two servers would be. */
+  const store = () => typeormRunStore(() => db.getRepository(AssistantRun))
+  const start = (at: number) => ({ name: 'race', modeKind: 'office.strategy-review', runAsId: owner.id, startedAt: new Date(at), deadlineAt: new Date(at + 1000) })
+
+  it('★ two first calls make one row, and only one of them holds it', async () => {
+    for (let round = 0; round < 25; round++) {
+      const identity = { domainId: domain.id, source: 'office.strategy-review', subject: 'p', scheduledAt: new Date(Date.UTC(2026, 0, 1) + round * 60000) }
+      const now = Date.now()
+      const [a, b] = await Promise.all([store().claim(identity, start(now), new Date(now)), store().claim(identity, start(now), new Date(now))])
+      const rows = await db.getRepository(AssistantRun).count({ where: { subject: 'p', scheduledAt: identity.scheduledAt } })
+      expect(rows).toBe(1)
+      expect([a.claimed, b.claimed].filter(Boolean)).toHaveLength(1)
+      expect(a.row.id).toBe(b.row.id)
+    }
+  }, 60000)
+
+  it('★ two calls taking over one failed occurrence make one next attempt', async () => {
+    for (let round = 0; round < 25; round++) {
+      const identity = { domainId: domain.id, source: 'office.strategy-review', subject: 'q', scheduledAt: new Date(Date.UTC(2026, 1, 1) + round * 60000) }
+      const now = Date.now()
+      const first = await store().claim(identity, start(now), new Date(now))
+      await store().finish({ id: first.row.id, attempt: 1 }, { status: 'failed', outcomeCode: 'assistant-run-model-error', finishedAt: new Date(now) })
+
+      const [a, b] = await Promise.all([store().claim(identity, start(now + 10), new Date(now + 10)), store().claim(identity, start(now + 10), new Date(now + 10))])
+      const row = await db.getRepository(AssistantRun).findOne({ where: { id: first.row.id } })
+      expect([a.claimed, b.claimed].filter(Boolean)).toHaveLength(1)
+      expect(row).toMatchObject({ status: 'running', attempt: 2 })
+      expect(JSON.parse(row.attempts)).toHaveLength(1)
+    }
+  }, 60000)
+})