smart-org/todo-v2-final.md

final check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/ruff check . && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app && cd ../web && node /projects/smart-org/node_modules/vitest/vitest.mjs run && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

# Smart Org v2 — last work (prepaid credit, direct tasks in the engine, Agent 2 phase 5 UI, cleanup)

Base: branch `dev`, HEAD `fef5a9d`. `todo-finish-plan.md` (T1–T27) is done and must NOT be edited.
Single alembic head today: `b9c0d1e2f3a4`. The one new migration in this file (T1) uses
`down_revision = "b9c0d1e2f3a4"`; check `ls apps/api/alembic/versions` first, and if a newer head exists, chain
off it instead.

Binding product decisions (from the owner): D-A cap 7, D-B prepaid billing, D-C build phase 5 UI here,
D-D direct tasks enter the engine + pause/resume/cancel, D-E housekeeping. Rules for every task: tenant
isolation (every query filtered by `organization_id`, a foreign id is a 404), no model/provider names for
non-owners, no secret in a response/log/event, Persian/RTL UI with `@agy/ui`, no silent `except Exception`,
never weaken an existing test (update it only where a decision below changes the behaviour, and say so in its
docstring). Do NOT commit.

What the code has today (checked, so it is not planned again, only used):
- Engine events already published: `run.log`, `run.tool` (`engine/events.py::RunFeed`, on `run:`, `task:` and
  `org:`), `task.gate` (`task:` + `org:`), `team.changed` (`org:`), `task.created` (manager CREATE_TASK).
  **`task.step` is not emitted anywhere** (T4 adds it). Stage moves have one choke point:
  `app/application/engine/state.py::advance` (used by `Scheduler._move` and the manager).
- There are **no** engine read endpoints: `routers/workforce.py` has only the legacy task/run/employee
  routes (no stage, turns, gates, diff, tier, role+tier hire). T17–T19 add a new router `routers/engine.py`.
- The diff is never stored (the worktree is gone after merge) and the pushed sha is not stored on the task
  (T1–T3 add `last_diff` and `merged_sha` to `task_pipeline_state`).
- Billing: `UsageLedgerRepository.record` (`repositories/audit.py:115`) is the single place every usage row
  is written (model calls via `record_model_usage`, sandbox, memory reflection). Nothing debits a wallet.
  `CreditWalletRepository.adjust` is a Python read-modify-write (not atomic). There is no credit history
  table. **Free-credit holes:** `POST /organizations/{org}/billing/add-credit` lets any org admin with
  `billing.manage` add positive credit, and `POST .../payments/{id}/settle` lets the same admin settle a
  pending payment as succeeded (= free credit). Both must become owner-only under prepaid (T12).
- `Scheduler._budget_reason` (`engine/scheduler.py:622-649`) pauses only on `balance < 0` and treats a
  missing wallet as "no budget" (T7 reverts). `ManagerTurns.chat` never checks credit (T8).
- `WorkforceService.create_task` (`workforce_service.py:435`) makes no pipeline state, so HTTP `POST /tasks`
  and MCP `tasks_create` (`interfaces/mcp/gateway.py:451`, calls `create_task`) run through the legacy
  one-shot `start_run` (T14). `PAUSED → PENDING_MANAGER_REVIEW` is a legal transition, but no API exists (T16).
- Web: `lib/api-engine.ts` is an empty stub; `/manager`, `/tasks`, `/tasks/[id]`, `/workforce`,
  `/workforce/[id]`, `/dashboard`, `/traces` are the pre-v2 pages (legacy task/run views, routing-policy
  select, no stage/tier). `/billing` shows add-credit + checkout to org admins. `/admin/organizations` and
  `/admin/model-grants` exist; there is no owner credit page.
- D-E verified: `tests/test_integration_thread_project.py:69-70` and `tests/test_v2_e2e_smoke.py:134-136` say
  the HTTP message route builds its manager without pipeline states (stale since
  `tests/test_integration_order_route.py`); `apps/web/src/lib/api-org.ts:303-310` says the event is not in
  `@agy/contracts` (it is, since T15 of the old plan). `docs/plan/reports/agent-3-final.md`: line 25 and
  §6 step 9 (lines 160-161) claim an MCP system route the owner can enable (only a read-only suggestion
  exists: `GET /api/admin/domains/suggested`, and the label `mcp` is refused); §5 line 128 lists a
  `system_routes` table (no such table in `models_delivery.py`); there is no sandbox restart claim in the
  final report itself — the restart gap is only in `TODO-agent-3` 6.3 / phase-6 report, so T42 adds one
  explicit "no restart" line to §8 instead of deleting a claim.

Shared test commands (abbreviated below as PYTEST / MYPY / RUFF / WEB):
- PYTEST = `cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider`
- MYPY = `PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy`
- RUFF = `PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/ruff check`
- WEB = `cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run`
- TSC = `node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json`
The `check:` lines below are written out in full.

---

## T1 — migration + ORM: `credit_transactions`, `task_pipeline_state.last_diff/merged_sha`, policy default 7
status: done
group: prepare
after: none
files: apps/api/app/infrastructure/db/models_billing.py (new), apps/api/app/infrastructure/db/models.py:1026-1028, apps/api/app/infrastructure/db/models_engine.py:51-93, apps/api/alembic/versions/c4d5e6f7a8b9_prepaid_credit_and_engine_ui.py (new)
change:
1. New `models_billing.py` (use `pk()`/`created()` from `app.infrastructure.db.columns`, never import
   `db/models.py`): `CreditTransactionRow`, table `credit_transactions`: `id` pk; `organization_id`
   FK `organizations.id` ondelete CASCADE, not null, indexed; `kind` String(16) not null
   (`owner_credit | starting_credit | usage | adjustment`); `amount` Float not null (signed: credit > 0,
   debit < 0); `balance_after` Float not null; `reason` String(500) default ""; `actor_user_id` String(32)
   nullable; `usage_event_id` String(32) nullable, **unique** (idempotency of a usage debit);
   `created_at` created(). `Index("ix_credit_tx_org_created", "organization_id", "created_at")`.
2. `models.py`: add `from app.infrastructure.db import models_billing as _models_billing  # noqa: E402,F401`
   next to the three existing lines (1026-1028).
3. `models_engine.py::TaskPipelineStateRow`: add `last_diff: Text, default "", nullable=False` (latest
   accepted diff, capped by the writer) and `merged_sha: String(64), default "", nullable=False`.
4. Migration `c4d5e6f7a8b9`, `down_revision = "b9c0d1e2f3a4"` (verify it is still the single head):
   create `credit_transactions` (+ unique on `usage_event_id`, the index), add the two columns with
   `server_default=""`, and `alter_column("org_policies", "max_employees", server_default="7")` (was "5",
   D-A). Downgrade reverses all three (server_default back to "5"). Use `batch_alter_table` for SQLite.
check: cd /projects/smart-org/apps/api && rm -f _alembic_check.db && export DATABASE_URL=sqlite+aiosqlite:///./_alembic_check.db PYTHONPATH=$PWD && A=/home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/alembic && $A upgrade head && $A check && $A downgrade b9c0d1e2f3a4 && $A upgrade head && $A heads && rm -f _alembic_check.db && unset DATABASE_URL && /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_foundation.py tests/test_engine_pipeline.py

## T2 — domain + repositories: new state fields, org turn list, paused counts
status: done
group: prepare
after: T1
files: apps/api/app/domain/workforce/pipeline.py:425-450, apps/api/app/infrastructure/repositories/engine.py:64-108,128-140,396-412, apps/api/tests/test_engine_repo_ui.py (new)
change:
1. `TaskPipelineState` dataclass: add `last_diff: str = ""` and `merged_sha: str = ""` (after `waiver_reason`).
2. `repositories/engine.py`: map both in `_state`; add both to `_PATCHABLE`; set them in `create` if it lists
   columns explicitly.
3. `EngineTurnRepository.list_for_org(organization_id, *, limit=50)`: join `TaskRow` on
   `EngineTurnRow.task_id == TaskRow.id`, filter `TaskRow.organization_id`, newest `started_at` first,
   `limit` capped at 200.
4. `PipelineStateRepository.count_at_by_org(stage) -> dict[str, int]` (group by organization_id) and
   `stage_counts(organization_id) -> dict[str, int]` (group by stage for one org).
5. Tests: patch + read back `last_diff`/`merged_sha`; `list_for_org` never returns another org's turns;
   `stage_counts` and `count_at_by_org` on two orgs.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_engine_repo_ui.py tests/test_engine_pipeline.py tests/test_engine_flow.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/infrastructure/repositories/engine.py app/domain/workforce/pipeline.py

## T3 — the scheduler stores the latest diff and the merged sha
status: done
group: prepare
after: T2
files: apps/api/app/application/engine/scheduler.py:399-447,479-545, apps/api/tests/test_engine_ui_fields.py (new)
change:
1. `_after_implementation`: in the existing `_patch(state, last_diff_hash=..., same_diff_count=...)` call
   also pass `last_diff=diff.text[:20000]` (one write, one version bump). Only after the diff guard passed.
2. `_merge_step`: right before `await self._move(state, task, Stage.COMPLETED)`, call
   `await self._patch(state, merged_sha=final_sha)`.
3. Test (import `world`, `_team`, `_task`, `_scheduler` and the scripted replies from
   `tests.test_engine_flow`, like `tests/test_integration_policy.py` does): run the happy path to COMPLETED
   and assert `state.last_diff` contains the fake diff text and `state.merged_sha` equals the sha the fake
   workspace pushed.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_engine_ui_fields.py tests/test_engine_flow.py tests/test_integration_policy.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/application/engine/scheduler.py

## T4 — publish `task.step` on every stage move
status: done
group: prepare
after: none
files: apps/api/app/application/engine/events.py:186-207, apps/api/app/application/engine/state.py:38-64, apps/api/tests/test_engine_step_event.py (new)
change:
1. `events.py`: add `async def emit_task_step(*, task_id, organization_id, from_stage, to_stage, pipeline)`
   publishing `RealtimeEvent(type="task.step", channels=(task_channel(task_id), org_channel(organization_id)),
   organization_id=..., data={"task_id", "from": from_stage, "to": to_stage, "pipeline": pipeline,
   "status": coarse_status(to_stage).value})`. Add it to `__all__`. No model/employee names in the payload.
2. `state.advance`: after a successful `states.advance(...)`, call `emit_task_step` with the returned state's
   `organization_id` and `pipeline`. Publishing never raises (`publish` swallows), so the move is unaffected.
3. Test: install a recording publisher with `set_publisher` (restore the old one in a `finally`; see how
   `tests/test_realtime.py` captures events), advance one state, assert exactly one `task.step` event on
   `task:<id>` + `org:<id>` with the right `from`/`to`; a refused (illegal) move publishes nothing.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_engine_step_event.py tests/test_engine_pipeline.py tests/test_engine_manager.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/application/engine/events.py app/application/engine/state.py

## T5 — credit ledger repository (atomic credit/debit, history) + a test helper to fund an org
status: done
group: prepare
after: T1
files: apps/api/app/domain/billing/models.py:62-85, apps/api/app/infrastructure/repositories/credit.py (new), apps/api/tests/billing_helpers.py (new), apps/api/tests/test_credit_ledger.py (new)
change:
1. Domain: `CreditKind(StrEnum)`: `owner_credit`, `starting_credit`, `usage`, `adjustment`; dataclass
   `CreditTransaction(organization_id, kind, amount, balance_after, reason="", actor_user_id=None,
   usage_event_id=None, id, created_at)`.
2. `CreditLedgerRepository(session)`:
   - `_ensure_wallet(org)`: create a 0.0 `CreditWalletRow` when missing (same as `CreditWalletRepository.ensure`).
   - `apply(*, organization_id, amount, kind, reason="", actor_user_id=None, usage_event_id=None)
     -> CreditTransaction`: **atomic SQL update** `update(CreditWalletRow).where(organization_id == org)
     .values(balance=CreditWalletRow.balance + amount, updated_at=utcnow())` (never read-modify-write in
     Python), then read the new balance and insert the transaction row with `balance_after`; flush.
   - `debit_for_usage(*, organization_id, usage_event_id, amount) -> CreditTransaction | None`: returns None
     when `amount <= 0` or a row with this `usage_event_id` already exists (idempotent); otherwise
     `apply(amount=-amount, kind=usage, usage_event_id=...)`. Catch `IntegrityError` only around a nested
     savepoint (`session.begin_nested()`) so a duplicate race returns None instead of poisoning the session.
   - `history(organization_id, *, kinds: tuple[CreditKind, ...] | None = None, limit=50)` newest first,
     limit capped at 200, always filtered by org.
   - `last_credit_at_by_org() -> dict[str, datetime]` (max created_at of non-usage rows, group by org).
3. `tests/billing_helpers.py`: `async def fund_org(session_factory, organization_id, amount=100.0)` that opens
   a session, calls `CreditLedgerRepository.apply(kind=adjustment, reason="test funding")` and commits.
   Later tasks import it to fund orgs whose tests need engine work under prepaid.
4. Tests: credit then debit gives the right `balance_after`; the same `usage_event_id` twice debits once;
   org B's wallet never moves when org A is debited; a missing wallet is created at 0 then credited.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_credit_ledger.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/infrastructure/repositories/credit.py app/domain/billing/models.py

## T6 — every usage event debits the wallet (single place: `UsageLedgerRepository.record`)
status: done
group: prepare
after: T5
files: apps/api/app/infrastructure/repositories/audit.py:109-133, apps/api/app/application/services/workforce_service.py:103-153, apps/api/tests/test_credit_debit.py (new)
change:
1. `UsageLedgerRepository.record`: give the `UsageEventRow` an explicit id (`new_id()`), flush, then in the
   **same session** (same transaction = atomic with the usage row) call
   `CreditLedgerRepository(self.session).debit_for_usage(organization_id=usage.organization_id,
   usage_event_id=row.id, amount=total)`. Return `float | None` (the new balance, None when nothing was
   debited). Update the class docstring: prepaid — the ledger is still the source of truth and every row
   debits the wallet exactly once. Keep the `UsageLedgerPort` signature compatible (returning a value from a
   `-> None` protocol method is fine for callers that ignore it; update the port annotation in
   `ports/audit.py` only if mypy demands it).
2. `record_model_usage`: when `record` returns a balance, also `await emit_wallet_changed(
   organization_id=..., balance=...)` so the sidebar badge and the billing page follow the debit live.
3. Tests: a model usage of price P on an org with balance B leaves B-P and one `usage` transaction whose
   `usage_event_id` is the usage row id; a zero-priced row creates no transaction; a sandbox usage (via
   `SandboxService` path or a direct `record`) debits too; another org is untouched; a rolled-back session
   leaves neither the usage row nor the debit.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_credit_debit.py tests/test_credit_ledger.py tests/test_workforce.py tests/test_engine_runner.py tests/test_e2e_smoke.py tests/test_workers.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/infrastructure/repositories/audit.py app/application/services/workforce_service.py

## T7 — prepaid pause: a zero, negative or missing wallet pauses engine work (D-B)
status: done
group: prepare
after: T3, T5
files: apps/api/app/application/engine/scheduler.py:89,618-649, apps/api/tests/test_engine_flow.py:88-112,536-601, apps/api/tests/test_v2_e2e_smoke.py
change:
1. `_budget_reason`: `wallet = await self.wallets.get_for_org(org)`; return `BUDGET_PAUSED_MESSAGE` when
   `wallet is None or wallet.balance <= 0`. Rewrite the docstring: billing is **prepaid**; the platform owner
   credits the wallet, every usage row debits it (T6), so zero means "no credit left". Set
   `BUDGET_PAUSED_MESSAGE = "اعتبار سازمان تمام شده است؛ کار تا افزودن اعتبار توسط مالک سامانه متوقف شد."`.
   Keep the per-task cap and the monthly budget checks unchanged.
2. `tests/test_engine_flow.py`: keep `_OverdrawnWallet` + its test; rename
   `test_a_zero_wallet_does_not_pause_a_fresh_org` → `test_a_zero_wallet_pauses_the_task_before_a_turn_is_spent`
   asserting `PAUSED`, `WAITING_APPROVAL`, `scripted.calls == 0` (docstring: prepaid decision D-B reverses the
   post-paid behaviour of the old T3); add `test_a_missing_wallet_pauses_the_task` (`_Wallets(None)`) and
   `test_a_funded_wallet_does_not_pause` (a `_FundedWallet` with `balance = 5.0`, one tick, stage not PAUSED).
   Update the module docstring bullet at line 17.
3. `tests/test_v2_e2e_smoke.py`: right after the wizard completes, `await fund_org(session_factory, org_id,
   1000.0)` (from `tests.billing_helpers`) with a comment "prepaid: the owner credits a new org before work".
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_engine_flow.py tests/test_v2_e2e_smoke.py tests/test_integration_policy.py tests/test_integration_runtime.py tests/test_error_log.py tests/test_workers.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/application/engine/scheduler.py

## T8 — the manager chat does not call a model on a zero-credit org
status: done
group: prepare
after: T5, T6
files: apps/api/app/application/engine/manager.py:208-240,383-420, apps/api/app/application/container_engine.py:197-240, apps/api/app/application/services/workforce_service.py:392-428, apps/api/tests/test_credit_chat_gate.py (new)
change:
1. `ManagerTurns.__init__`: optional kwarg `wallets: CreditWalletRepository | None = None`, stored.
2. `chat()`: after storing the user message and before any model call, when `self.wallets` is set and the
   org's wallet is missing or `balance <= 0`, store an assistant message
   `CHAT_NO_CREDIT_MESSAGE = "اعتبار سازمان صفر است؛ مدیر پس از افزودن اعتبار توسط مالک سامانه پاسخ می‌دهد."`
   and return `(user_message, assistant_message)` without calling the provider and without executing tags.
   Export the constant.
3. Pass `wallets=CreditWalletRepository(session)` in `container_engine._build_manager` and in
   `WorkforceService._manager_turns` (session = `self.tasks.session`). The bootstrap builder (line ~59) needs
   nothing (it never chats).
4. Test: an org at 0.0 → the reply is the note and `ScriptedModel.calls == 0`; after `fund_org(...)` the
   model is called once. Existing direct `ManagerTurns(...)` constructions (no `wallets`) stay unaffected.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_credit_chat_gate.py tests/test_engine_manager.py tests/test_integration_review_fallback.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/application/engine/manager.py app/application/container_engine.py app/application/services/workforce_service.py

## T9 — fund the chat tests for prepaid + fix the two stale test comments (D-E)
status: done
group: prepare
after: T7, T8
files: apps/api/tests/test_integration_order_route.py, apps/api/tests/test_integration_thread_project.py:60-80, apps/api/tests/test_e2e_smoke.py, apps/api/tests/test_v2_e2e_smoke.py:130-140
change:
1. In each test that chats with the manager on an org created over HTTP or by the wizard (wallet 0.0), call
   `fund_org(session_factory, org_id)` before the order, with a one-line comment (prepaid, D-B). Do not
   change any assertion. If `test_e2e_smoke.py` has no `session_factory` fixture in that test, add it to the
   test signature.
2. Stale comments: `test_integration_thread_project.py:69-70` and `test_v2_e2e_smoke.py:134-136` claim the HTTP
   message route builds its manager without pipeline states. Rewrite them: the HTTP route builds states too
   (`WorkforceService._manager_turns`, covered by `tests/test_integration_order_route.py`); these tests call
   `build_scheduler(session).manager.chat` directly only to read the reply/state in the same session.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_integration_order_route.py tests/test_integration_thread_project.py tests/test_e2e_smoke.py tests/test_v2_e2e_smoke.py && ! grep -n "without pipeline states" tests/test_integration_thread_project.py tests/test_v2_e2e_smoke.py

## T10 — `CreditService`: owner credit, history, balances
status: done
group: prepare
after: T2, T5
files: apps/api/app/application/services/credit_service.py (new), apps/api/tests/test_credit_service.py (new)
change:
1. `CreditService(session)` with `ledger = CreditLedgerRepository`, `wallets = CreditWalletRepository`,
   `orgs = OrganizationRepository`, `states = PipelineStateRepository`.
   - `MAX_OWNER_CREDIT = 100_000.0`.
   - `owner_credit(*, organization_id, amount, reason, actor_user_id) -> CreditTransaction`: org must exist
     (`NotFoundError("سازمان یافت نشد.")`); `0 < amount <= MAX_OWNER_CREDIT` else `ValidationError`;
     `reason.strip()` 3..500 chars else `ValidationError("دلیل افزودن اعتبار لازم است.")`;
     `ledger.apply(kind=owner_credit, ...)`; then `emit_wallet_changed(organization_id, balance_after)`.
   - `history(organization_id, limit=50)`: non-usage kinds only (owner_credit, starting_credit, adjustment).
   - `balances() -> list[OrgBalance]` (dataclass: organization_id, name, slug, balance, currency,
     paused_tasks, last_credit_at): every org (`list_all`), its wallet (0.0 when missing),
     `states.count_at_by_org(Stage.PAUSED)`, `ledger.last_credit_at_by_org()`.
   - `grant_starting_credit(organization_id)`: when `settings.billing_starting_credit > 0` (added by T13; read
     with `getattr(settings, "billing_starting_credit", 0.0)` so this task does not depend on T13) apply
     `kind=starting_credit, reason="اعتبار آغازین"`; otherwise no-op.
2. Tests: credit → balance + one row; amount 0 / negative / above max / blank reason refused; unknown org 404;
   history excludes usage rows and other orgs; balances lists two orgs with their own numbers and paused counts.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_credit_service.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/application/services/credit_service.py

## T11 — owner-only credit endpoints `/api/admin/credits`, `/api/admin/orgs/{org}/credit`
status: done
group: prepare
after: T10
files: apps/api/app/interfaces/http/routers/admin_credits.py (new), apps/api/app/interfaces/realtime/rpc_app.py:23-42,96-103, apps/api/tests/test_admin_credits.py (new)
change:
1. Router `APIRouter(prefix="/admin", tags=["admin-credits"], dependencies=[Depends(require_platform_owner)])`
   (same pattern as `admin_grants.py`):
   - `GET /credits` → `list[OrgBalanceOut]` (organization_id, name, slug, balance, currency, paused_tasks,
     last_credit_at).
   - `POST /orgs/{org_id}/credit` body `{amount: float, reason: str}` → `CreditTransactionOut` (id, kind,
     amount, balance_after, reason, created_at). Audit with `AuditAction.BILLING_CREDIT`,
     `organization_id=org_id`, `actor_user_id=owner.id`, `target_type="credit_wallet"`, metadata
     `{amount, reason, balance}` and `client_meta(request)`.
   - `GET /orgs/{org_id}/credit-history?limit=50` → `list[CreditTransactionOut]`.
   No model/provider field, no secret.
2. Register it in `rpc_app.py` (import + `include_router(admin_credits.router, prefix="/api")` in the v2 block).
3. Tests (fixture `platform_owner_token` from conftest; a manager-created org): owner credit → 200, wallet
   balance, transaction row, an audit row with the reason, a `billing.wallet` event (recording publisher);
   history lists it; list shows the org with its balance; a manager / org owner (non platform owner) gets 403
   on all three; an unknown org id 404; amount ≤ 0 and empty reason → 4xx with a Persian message.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_admin_credits.py tests/test_foundation.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/interfaces/http/routers/admin_credits.py app/interfaces/realtime/rpc_app.py

## T12 — close the free-credit holes in the tenant billing router
status: done
group: prepare
after: T5
files: apps/api/app/interfaces/http/routers/billing.py:1-30,208-300, apps/api/tests/test_billing_prepaid.py (new)
change:
1. `POST /billing/add-credit`: any amount now requires `context.user.is_platform_owner`, otherwise
   `PermissionDeniedError("اعتبار سازمان را فقط مالک سامانه افزایش می‌دهد.")`. For the owner, write through
   `CreditLedgerRepository.apply(kind=adjustment, reason="billing/add-credit", actor_user_id=...)` instead of
   `BillingService.add_credit` so it appears in the credit history, keep the existing audit, and emit
   `emit_wallet_changed`. Keep refusing a result below zero for a negative amount.
2. `POST /billing/payments/{id}/settle`: platform owner only (same message). `POST /checkout` stays as is
   (it only creates a pending payment). Update the module docstring: prepaid, the owner credits wallets.
3. Tests: org owner/admin with `billing.manage` → 403 on add-credit (positive) and settle; platform owner →
   200 and one `adjustment` transaction; `GET /billing/summary` still works for members with `billing.view`.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_billing_prepaid.py tests/test_tenant_isolation.py tests/test_e2e_smoke.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/interfaces/http/routers/billing.py

## T13 — optional starting credit for new orgs (`BILLING_STARTING_CREDIT`, default 0)
status: done
group: prepare
after: T10
files: apps/api/app/core/config.py:125-200, .env.example:90-145, apps/api/app/application/services/org_setup_service.py:205-230, apps/api/app/interfaces/http/routers/organizations.py:140-150, apps/api/tests/test_billing_starting_credit.py (new)
change:
1. `config.py`: add a new marked block `# >>> integration (billing)` … `# <<< integration` after the
   agent-3 block with `billing_starting_credit: float = 0.0` (comment: credit given to every new org at
   creation, prepaid; 0 = the owner credits by hand). Same block and line `BILLING_STARTING_CREDIT=0` in
   `.env.example`.
2. Wizard (`org_setup_service.py`, after the `CreditWalletRow(...)` add at ~line 223) and
   `organizations.py` (after line 147): `await self.session.flush()` / `await session.flush()` then
   `await CreditService(session).grant_starting_credit(org.id)` (lazy import to avoid cycles).
3. Tests: with the setting at 0 a new org (HTTP and wizard) has balance 0 and no transaction; with
   `monkeypatch.setattr(settings, "billing_starting_credit", 3.0)` both paths give 3.0 and one
   `starting_credit` row.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_billing_starting_credit.py tests/test_org_wizard.py tests/test_tenant_isolation.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/core/config.py app/application/services/org_setup_service.py app/interfaces/http/routers/organizations.py

## T14 — direct tasks enter the engine; the legacy "اجرا" refuses engine tasks (D-D)
status: done
group: prepare
after: T8
files: apps/api/app/application/services/workforce_service.py:435-470,500-520, apps/api/tests/legacy_tasks.py (new), apps/api/tests/test_workforce.py, apps/api/tests/test_direct_tasks_engine.py (new)
change:
1. `create_task`: after `self.tasks.create(...)`, create a `TaskPipelineState` with
   `PipelineStateRepository(self.tasks.session)`: `stage=PENDING_MANAGER_REVIEW`, `kind=TaskKind.FEATURE`,
   `risk=Risk.MEDIUM`, `pipeline=resolve_pipeline(manager_choice=None, task_kind=TaskKind.FEATURE,
   has_active_reviewer=False)` (the manager's triage picks the real pipeline), `project_id` = the given one or
   the org's single project (mirror `ManagerTurns._project_id_for`, manager.py:1071; store it on the task too).
   This is the "user order to the manager": the scheduler's triage turn takes it from there. The docstring
   says so. MCP `tasks_create` calls this method, so it is covered without touching the gateway.
2. `start_run`: when `PipelineStateRepository(session).get(task_id)` is not None, raise
   `ConflictError("این کار را موتور خودکار اجرا می‌کند؛ برای توقف، ادامه یا لغو از دکمه‌های همین کار استفاده کنید.")`.
3. `tests/legacy_tasks.py`: `async def legacy_task(session_factory, organization_id, created_by_user_id, *,
   title="کار قدیمی", project_id=None, assigned_employee_id=None) -> str` inserting a plain `TaskRow` (no
   state): pre-v2 tasks still exist and still run through the legacy path.
4. `tests/test_workforce.py`: every test whose purpose is the legacy run (`POST /tasks/{id}/runs`, lines
   ~229-318) creates its task with `legacy_task(...)` instead of HTTP; keep every assertion.
5. New `tests/test_direct_tasks_engine.py`: HTTP `POST /tasks` creates a state at `pending_manager_review`
   with the org's project; `POST /tasks/{id}/runs` on it → 409; MCP `tasks_create` (see `tests/test_mcp.py`
   `_call` helper) also creates a state; a legacy task still runs.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_direct_tasks_engine.py tests/test_workforce.py tests/test_integration_runtime.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/application/services/workforce_service.py

## T15 — update the remaining tests that relied on direct tasks running the legacy way
status: done
group: prepare
after: T9, T14
files: apps/api/tests/test_workers.py, apps/api/tests/test_e2e_smoke.py, apps/api/tests/test_seed.py, apps/api/tests/test_error_log.py, apps/api/tests/test_pagination.py, apps/api/tests/test_realtime.py, apps/api/tests/test_integration_tenant_project.py, apps/api/tests/test_mcp.py
change:
1. Run the full API suite first and list the failures (paste the list in your report; it must not be empty
   if any of these files posts `/tasks` then expects a legacy run/drain).
2. For each failing test: if its purpose is the legacy run/drain/metering, create the task with
   `tests.legacy_tasks.legacy_task(...)`; if its purpose is task creation, keep HTTP and assert the new
   pipeline state instead of a legacy run. Never delete an assertion; explain each change in the test's
   docstring (decision D-D).
3. `tests/test_mcp.py`: in the existing `tasks_create` test add an assertion that the created task has a
   `TaskPipelineState` at `pending_manager_review`.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider

## T16 — `Scheduler.user_action`: pause, resume, cancel, answer
status: done
group: prepare
after: T7
files: apps/api/app/application/engine/scheduler.py:586-650, apps/api/app/infrastructure/repositories/workforce.py:483-512, apps/api/tests/test_engine_control.py (new)
change:
1. `TaskRepository.append_description(task_id, text) -> Task | None` (narrow write, like `set_status`).
2. `Scheduler.user_action(*, organization_id, task_id, action: Literal["pause","resume","cancel","answer"],
   user_id: str, answer: str = "") -> TaskPipelineState`:
   - `task = await self.tasks.get_for_org(organization_id, task_id)` else `NotFoundError("کار یافت نشد.")`;
     `state = await self.states.get(task_id)` else `ConflictError("این کار در موتور خودکار نیست.")`;
     a terminal stage → `ConflictError("این کار بسته شده است.")`.
   - pause: `_move(state, task, Stage.PAUSED)` (illegal transitions surface as the existing `ConflictError`).
   - resume: only from `PAUSED` (else ConflictError "فقط کار متوقف‌شده را می‌توان ادامه داد."); if
     `await self._budget_reason(task)` is not None raise `ConflictError(reason)` (no credit → no resume);
     then `_move(..., Stage.PENDING_MANAGER_REVIEW)`.
   - cancel: `_move(..., Stage.CANCELLED)` (already releases the worktree and parks dependents).
   - answer: only from `PENDING_USER_DECISION`; `answer.strip()` 1..4000 chars; append
     `"\n\nپاسخ کاربر: " + answer` to the description; if `task.thread_id`, store a USER message in the thread
     via `self.manager.messages`; then `_move(..., Stage.PENDING_MANAGER_REVIEW)` (triage reads the answer).
   - After every move `emit_task_status(task_id, organization_id, coarse_status(target).value)`.
   Return the re-read state.
3. Tests (reuse `tests.test_engine_flow` helpers; pass a funded `_Wallets`): pause → PAUSED; resume →
   PENDING_MANAGER_REVIEW; resume with a zero wallet → ConflictError and still PAUSED; cancel → CANCELLED
   and the fake workspace's `remove_worktree` was called when a worktree existed; answer from
   PENDING_USER_DECISION moves to triage and the description contains the answer; org B id → NotFoundError.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_engine_control.py tests/test_engine_flow.py tests/test_workforce.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/application/engine/scheduler.py app/infrastructure/repositories/workforce.py

## T17 — engine read API: status, task board, task detail, recent turns
status: done
group: prepare
after: T2, T3, T11
files: apps/api/app/interfaces/http/routers/engine.py (new), apps/api/app/interfaces/realtime/rpc_app.py, apps/api/tests/test_engine_api.py (new)
change:
1. `router = APIRouter(prefix="/organizations/{org_id}/engine", tags=["engine"])`; every route resolves
   `get_org_context` (any member may read) and filters by `context.org_id`. Register in `rpc_app.py`.
2. `GET /status` → `EngineStatusOut {balance, currency, credit_ok (wallet exists and balance > 0),
   automation_enabled, max_employees, team_size (non-archived employees), stage_counts: dict[str,int]}`
   (policy from `build_model_grants(session).get_org_policy`).
3. `GET /tasks?stage=&limit=100` → `list[EngineTaskOut] {id, title, status, stage|null, pipeline|null,
   kind|null, cycle, max_cycles, thread_id, assigned_employee_id, assignee_name, created_at, updated_at}`;
   tasks via `TaskRepository.list_for_org`, states via `PipelineStateRepository.list_for_org` (dict by
   task id); legacy tasks have `stage=null`.
4. `GET /tasks/{task_id}` → `EngineTaskDetailOut` = `EngineTaskOut` + `description`, `stages: list[str]`
   (the stage list of its pipeline from `PIPELINES`), `waiver_reason`, `branch`, `depends_on`, `merged_sha`,
   `diff: str` (`state.last_diff`), `turns: [{id, run_id, role, mode, stage, employee_name, ok, error_kind,
   tool_calls, reply_excerpt (first 1000 chars), started_at, finished_at}]`, `gates: [{id, gate, ok, detail,
   created_at}]`, `runs: [{id, status, started_at, finished_at}]`. Foreign task → 404.
5. `GET /turns?limit=50` → recent turns of the org (`EngineTurnRepository.list_for_org`) with `task_title`.
6. No field can hold a model id/name, provider, account, container or port (state it in the module
   docstring, like `workforce.py`). Tests: org B member gets 404 on every path; a member (viewer) can read;
   serialised JSON of every endpoint contains none of the seeded `AiModelRow.name`/`provider` values nor
   `ai_model_id`; detail returns stages, gates, turns, diff and sha for a task built with the repositories.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_engine_api.py tests/test_tenant_isolation.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/interfaces/http/routers/engine.py app/interfaces/realtime/rpc_app.py

## T18 — engine action API: pause / resume / cancel / answer
status: done
group: prepare
after: T16, T17
files: apps/api/app/interfaces/http/routers/engine.py, apps/api/app/domain/audit/models.py:58-68, apps/api/tests/test_engine_api_actions.py (new)
change:
1. `AuditAction.TASK_CONTROL = "task.control"`.
2. `POST /tasks/{task_id}/pause|resume|cancel` and `POST /tasks/{task_id}/answer {content: str (1..4000)}`:
   `context.require(CAN_RUN_TASKS)`, `await build_scheduler(session).user_action(...)` (lazy import from
   `app.application.container`), audit `TASK_CONTROL` with metadata `{action}` (never the answer text), return
   the refreshed `EngineTaskOut`.
3. Tests: member with CAN_RUN_TASKS pauses then resumes (org funded with `fund_org`); resume on a zero wallet →
   409 with the Persian reason; cancel → stage cancelled + audit row; answer only from
   pending_user_decision (else 409); viewer → 403; org B → 404.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_engine_api_actions.py tests/test_engine_api.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/interfaces/http/routers/engine.py app/domain/audit/models.py

## T19 — engine team API: team with tier, hire (role + tier), fire
status: done
group: prepare
after: T18
files: apps/api/app/interfaces/http/routers/engine.py, apps/api/tests/test_engine_api_team.py (new)
change:
1. `GET /team` → `TeamOut {employees: [{id, name, role_key, status, tier ("fast"|"balanced"|"strong"|
   "unknown"), busy_task_id, busy_task_title, hired_by}], tiers: [{tier, label}] (distinct tiers of the org's
   granted models, labels «سریع/متعادل/قوی»), max_employees, count}`. Tier = the tier of the profile's
   `ai_model_id` in `grants.granted_models(org)`; not granted → `unknown`. Archived employees excluded.
2. `POST /team/hire {role: RoleKey (HIRABLE_ROLES), tier, name?}` (`CAN_MANAGE_EMPLOYEES`) →
   `build_scheduler(session).manager.hire(organization_id, role, tier, name, project_id=None)`; audit
   `EMPLOYEE_CREATE`; returns the team member row. `POST /team/{employee_id}/fire` → `manager.fire(...)`;
   audit `EMPLOYEE_UPDATE` with `{action: "fire"}`. Hire/fire errors keep their Persian messages (409/404).
3. Tests: hire with a granted tier → 201, the response has `tier` and no model id/name anywhere; a tier that
   is not granted → 409; the cap equals `ModelGrantService.get_org_policy(org).max_employees` (do not hard-code
   5 or 7); firing the last manager → 409; member without CAN_MANAGE_EMPLOYEES → 403; org B → 404.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_engine_api_team.py tests/test_engine_api.py tests/test_engine_manager.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/mypy app/interfaces/http/routers/engine.py && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/ruff check app tests

## T20 — `@agy/contracts`: engine event types + payloads
status: done
group: prepare
after: T4
files: packages/contracts/src/index.ts:816-842
change:
1. Append to `WsEventType` (comment `// v2 AI workforce engine`): `"task.step" | "task.gate" | "run.log" |
   "run.tool" | "team.changed"`.
2. Add payload interfaces mirroring the backend `data` key-for-key: `TaskStepEventData {task_id; from; to;
   pipeline; status}`, `TaskGateEventData {task_id; gate; ok; detail}`, `RunLogEventData {run_id; task_id;
   lines: string[]}`, `RunToolEventData {run_id; task_id; tool; ok; summary}`, `TeamChangedEventData
   {change; employee_id; organization_id}`.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/org-memory.test.tsx

## T21 — `lib/api-engine.ts`: typed client for the engine API
status: done
group: prepare
after: T17, T18, T19, T20
files: apps/web/src/lib/api-engine.ts, apps/web/src/test/engine-api.test.ts (new)
change:
1. Exported types mirroring T17–T19 exactly: `EngineStage` (string union of the 13 stages), `EngineStatus`,
   `EngineTask`, `EngineTaskDetail`, `EngineTurn`, `EngineGate`, `EngineRun`, `TeamMember`, `TierOption`,
   `TeamView`, `HireRequest`. No field named model/provider.
2. `engineApi` (keep the `satisfies` line): `status(orgId)`, `listTasks(orgId, stage?)`, `getTask(orgId, id)`,
   `listTurns(orgId, limit?)`, `pauseTask`, `resumeTask`, `cancelTask` (POST, no body), `answerTask(orgId, id,
   content)`, `getTeam(orgId)`, `hire(orgId, body)`, `fire(orgId, employeeId)`; all through `apiRequest`.
3. Test: `vi.mock("@/lib/api", ...)` capturing `apiRequest` calls; assert path + method + body for each function.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-api.test.ts && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T22 — `lib/engine-labels.ts`: stage labels, board columns, tier labels
status: done
group: prepare
after: none
files: apps/web/src/lib/engine-labels.ts (new), apps/web/src/test/engine-labels.test.ts (new)
change:
1. `STAGE_LABELS: Record<string, string>` (Persian for all 13 stages), `stageTone(stage)` → Badge tone
   (success completed, danger failed/cancelled, warning paused/pending_user_decision/error_review, info else).
2. `BOARD_COLUMNS` in this order with labels: بررسی مدیر (pending_manager_review), تحلیل (pending_analysis),
   پیاده‌سازی (pending_implementation), بازبینی (pending_review, pending_final_review), تست (pending_test),
   ادغام (merge_request), انجام‌شده (completed, cancelled, failed), نیازمند تصمیم (pending_user_decision,
   error_review, paused). `columnFor(stage: string | null, status: string)`: legacy tasks (stage null) map by
   coarse status (new→بررسی مدیر, running→پیاده‌سازی, waiting_approval→نیازمند تصمیم, done/failed/cancelled→
   انجام‌شده). `groupByColumn<T extends {stage; status}>(tasks)`.
3. `TIER_LABELS` (fast سریع, balanced متعادل, strong قوی, unknown «نامشخص»), `ROLE_LABELS` (manager مدیر,
   planner برنامه‌ریز, developer برنامه‌نویس, reviewer بازبین, tester آزمونگر).
4. Test: every stage lands in exactly one column; legacy mapping; grouping keeps order.
check: cd /projects/smart-org/apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-labels.test.ts && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T23 — shared `TaskActions` (pause / resume / cancel with confirm)
status: done
group: prepare
after: T21, T22
files: apps/web/src/components/engine/task-actions.tsx (new), apps/web/src/test/engine-task-actions.test.tsx (new)
change:
1. `TaskActions({ orgId, task: {id, stage}, canRun, onChanged, size? })`: renders «توقف» (non-terminal,
   not paused), «ادامه» (paused), «لغو» (non-terminal); each opens `ConfirmDialog` (Persian text, «لغو» marked
   destructive) and calls `engineApi.pauseTask/resumeTask/cancelTask`; a server error shows its Persian
   message inline (`ApiError.message`); renders nothing when `canRun` is false or `stage` is null.
2. Test: buttons per stage; confirm calls the API and `onChanged`; a 409 message is shown; nothing for a
   legacy task.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-task-actions.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T24 — shared `CreditNotice` + `useEngineStatus`
status: done
group: prepare
after: T21
files: apps/web/src/components/engine/credit-notice.tsx (new), apps/web/src/test/engine-credit-notice.test.tsx (new)
change:
1. `useEngineStatus(orgId)`: loads `engineApi.status`, reloads on `billing.wallet`, `task.step` and
   `team.changed` on `org:<id>` (`useLiveChannel`), returns `{status, loading, error, reload}`.
2. `CreditNotice({ status })`: when `status && !status.credit_ok` a warning `Card`:
   «اعتبار سازمان به پایان رسیده است» + «کار کارمندان هوش مصنوعی تا افزودن اعتبار توسط مالک سامانه متوقف است.
   پس از افزودن اعتبار، کارهای متوقف‌شده را از صفحهٔ وظایف ادامه دهید.» and the balance; otherwise nothing.
3. Test: renders the message at 0 and nothing when `credit_ok`; the hook reloads on a `billing.wallet` event
   (mock `@/lib/realtime` like `src/test/org-mcp.test.tsx` does).
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-credit-notice.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T25 — default per-org employee cap = 7 (D-A)
status: done
group: g1
after: none
files: apps/api/app/application/services/model_grant_service.py:49, apps/api/app/infrastructure/db/models_org.py:146, apps/api/app/infrastructure/repositories/org_grants.py:42, apps/api/tests/test_model_grants.py:332,395, apps/web/src/app/(app)/admin/model-grants/page.tsx:70
change:
1. `DEFAULT_MAX_EMPLOYEES = 7`; `OrgPolicyRow.max_employees` `default=7`; `OrgPolicyRecord.max_employees = 7`.
   `settings.engine_max_employees` (20) stays the upper bound (`min(DEFAULT, limit)` is unchanged).
   The migration server default is T1's job (already "7").
2. `tests/test_model_grants.py:332` and `:395` assert 7 (docstring note: D-A). Add one assertion in an
   existing policy test that 4 (the bootstrap team) ≤ the default cap.
3. Web: `React.useState("5")` → `"7"` at `admin/model-grants/page.tsx:70`.
check: cd /projects/smart-org/apps/api && PYTHONPATH=$PWD /home/mamad/work/smart-org-wt/agent1/apps/api/.venv/bin/pytest -q -p no:cacheprovider tests/test_model_grants.py tests/test_integration_hire_cap.py tests/test_engine_manager.py tests/test_org_wizard.py && cd ../web && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json && grep -rn "DEFAULT_MAX_EMPLOYEES = 7" ../api/app/application/services/model_grant_service.py

## T26 — `lib/api-credit.ts`: owner credit client
status: done
group: g2
after: T11
files: apps/web/src/lib/api-credit.ts (new), apps/web/src/test/billing-api-credit.test.ts (new)
change:
1. Types `OrgBalance`, `CreditTransaction` (mirror T11) and `creditApi = { balances(), credit(orgId, {amount,
   reason}), history(orgId, limit?) }` via `apiRequest` on `/api/admin/credits`, `/api/admin/orgs/{id}/credit`,
   `/api/admin/orgs/{id}/credit-history`.
2. Test: paths, methods and bodies (mock `@/lib/api`).
check: cd /projects/smart-org/apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/billing-api-credit.test.ts && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T27 — owner page `/admin/credits` + admin tab
status: done
group: g2
after: T26
files: apps/web/src/app/(app)/admin/credits/page.tsx (new), apps/web/src/lib/nav.ts:31-46, apps/web/src/test/billing-admin-credits.test.tsx (new)
change:
1. Page (the admin layout already blocks non-owners): `Table` of orgs (نام، شناسه، اعتبار، کارهای متوقف،
   آخرین افزایش), balance ≤ 0 shown with a danger `Badge` «بدون اعتبار». Per row «افزودن اعتبار» opens a `Modal`
   with amount (number > 0) + reason (required, 3+ chars) and a confirm step; on success refresh the row and
   show a toast. «تاریخچه» opens a `Drawer` with `creditApi.history` (date fa-IR, amount, reason, balance after).
   Live: reload on `billing.wallet` from `admin` channel if available; otherwise reload after each action only.
2. `nav.ts` `ADMIN_ITEMS`: add `{ href: "/admin/credits", label: "اعتبار سازمان‌ها", hint: "شارژ پیش‌پرداخت" }`
   after the organizations entry.
3. Test: rows render with balances; submit is disabled until amount and reason are valid; submit calls
   `creditApi.credit` with both; history drawer lists entries.
check: cd /projects/smart-org/apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/billing-admin-credits.test.tsx src/test/command-palette.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T28 — members: billing page is read-only + credit notice; wizard success says work starts after credit
status: done
group: g2
after: T24, T27
files: apps/web/src/app/(app)/billing/page.tsx:150-270, apps/web/src/app/onboarding/page.tsx:362-380, apps/web/src/test/billing-prepaid.test.tsx (new)
change:
1. Billing page: the «افزایش اعتبار» card (add-credit + checkout, lines ~226-270) renders only for
   `user.is_platform_owner`; everyone else sees a `CardHint` «اعتبار سازمان به صورت پیش‌پرداخت توسط مالک سامانه
   افزوده می‌شود. هر مصرف از همین اعتبار کم می‌شود.». Render `CreditNotice` (status from `useEngineStatus`) at
   the top. Keep all existing widgets and the live wallet handling.
2. Onboarding success screen: below the existing hint, when `engineApi.status(result.organization.id)` says
   `!credit_ok` (or the call fails), show «کار کارمندان پس از افزودن اعتبار توسط مالک سامانه آغاز می‌شود.».
3. Test: a member sees no add-credit button and sees the hint; the owner sees the form; the notice shows at
   balance 0. Keep `src/test/org-wizard.test.tsx` green (mock `engineApi.status` there only if it breaks).
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/billing-prepaid.test.tsx src/test/org-wizard.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T29 — manager components: inline task cards + pending-decision banner
status: done
group: g3
after: T21, T22, T24
files: apps/web/src/app/(app)/manager/_components/task-cards.tsx (new), apps/web/src/app/(app)/manager/_components/decision-banner.tsx (new), apps/web/src/test/engine-manager.test.tsx (new)
change:
1. `ThreadTaskCards({ tasks })`: compact cards (title, stage `Badge` with `STAGE_LABELS`/`stageTone`, link
   `/tasks/{id}`) for the tasks of the active thread.
2. `DecisionBanner({ orgId, tasks, onAnswered })`: for tasks at `pending_user_decision` a warning card
   «در انتظار تصمیم شما» with the task title, a textarea and «ارسال پاسخ» → `engineApi.answerTask`; errors
   inline in Persian; hidden when there is none.
3. Test: cards show the Persian stage; the banner appears only for pending decisions and posts the answer.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-manager.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T30 — wire the manager page (cards inline, banner, credit notice, live stages)
status: done
group: g3
after: T29
files: apps/web/src/app/(app)/manager/page.tsx, apps/web/src/test/engine-manager-page.test.tsx (new)
change:
1. Load `engineApi.listTasks(orgId)` next to the existing loads; render `CreditNotice` + `DecisionBanner` at
   the top and `ThreadTaskCards` (tasks with `thread_id === activeThreadId`) under the messages.
2. Live: on `task.created` reload the engine task list; on `task.step` patch the task's `stage`/`status` in
   place (data is `TaskStepEventData`). Keep `message.created` handling as is.
3. The «کار جدید» form keeps `api.createTask`; its hint says the task goes to the AI manager first.
4. Test (mock api, api-engine, realtime, session): a `task.step` event moves a card's badge; the banner shows
   for a pending decision; the notice shows at zero credit.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-manager-page.test.tsx src/test/engine-manager.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T31 — task board component (columns by stage, filters, live)
status: done
group: g4
after: T20, T22, T23
files: apps/web/src/app/(app)/tasks/_components/task-board.tsx (new), apps/web/src/test/engine-board.test.tsx (new)
change:
1. `TaskBoard({ orgId, tasks, employees, canRun, onChanged })`: columns from `BOARD_COLUMNS` (horizontal scroll
   on mobile, RTL), each card: title link, stage badge, assignee name, cycle `n/max`, `TaskActions`.
   Filters above: text search on title, assignee select, «فقط کارهای فعال» checkbox.
2. Live: subscribe `org:<id>`; `task.step` moves the card to `columnFor(to)`; `task.created` calls `onChanged`.
3. Test: grouping into the 8 columns (a fixture with every stage + one legacy task); a `task.step` event
   moves a card; the filter hides non-matching cards.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-board.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T32 — wire `/tasks` to the board
status: done
group: g4
after: T31
files: apps/web/src/app/(app)/tasks/page.tsx
change:
1. Replace the list/status filter with `TaskBoard` fed by `engineApi.listTasks(orgId)` + `api.listEmployees`.
   Keep the create form (`api.createTask`), with the hint «کار جدید ابتدا به مدیر AI سپرده می‌شود.», and
   reload after create. `CreditNotice` at the top.
2. Run the board test and add one case to `src/test/engine-board.test.tsx` only if the page needs it.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-board.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T33 — task detail: pipeline stepper + turn timeline
status: done
group: g5
after: T21, T22
files: apps/web/src/app/(app)/tasks/[id]/_components/pipeline-stepper.tsx (new), apps/web/src/app/(app)/tasks/[id]/_components/turn-timeline.tsx (new), apps/web/src/test/engine-task-detail.test.tsx (new)
change:
1. `PipelineStepper({ stages, current })`: the pipeline's stages in order with Persian labels; done stages
   check-marked, current highlighted; a side state (paused/pending_user_decision/error_review/cancelled/
   failed) shown as a badge beside the stepper.
2. `TurnTimeline({ turns })`: `Timeline` items «{ROLE_LABELS[role]} — {employee_name}», stage label, time
   fa-IR, outcome (موفق / خطا: error_kind), tool call count; the reply excerpt in a collapsible block.
3. Test: current stage highlighted; timeline renders roles in Persian; a fixture turn carrying an unexpected
   `model: "gpt-secret-x"` field never renders that text.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-task-detail.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T34 — task detail: live log panel
status: done
group: g5
after: T20
files: apps/web/src/app/(app)/tasks/[id]/_components/live-log.tsx (new), apps/web/src/test/engine-live-log.test.tsx (new)
change:
1. `LiveLog({ taskId })`: subscribes `task:<taskId>` via `useLiveChannel`; a `run.log` event appends all its
   `lines` in ONE state update; a `run.tool` event appends one line `«ابزار {tool}: موفق|ناموفق — summary»`;
   keeps the last 2000 lines; monospace, `dir="ltr"` for the log body.
2. Auto-scroll to bottom on new lines unless paused: a «توقف پیمایش / ادامهٔ پیمایش» toggle, and scrolling up
   by hand pauses it too. A «پاک کردن» button.
3. Test: one event with 3 lines renders 3 rows (batched: one render per event); a tool event renders; with
   scroll paused the container's `scrollTop` is not changed; the 2000-line cap.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-live-log.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T35 — task detail: gates panel + diff viewer + waiver + pushed sha link
status: done
group: g5
after: T21
files: apps/web/src/app/(app)/tasks/[id]/_components/gates-panel.tsx (new), apps/web/src/app/(app)/tasks/[id]/_components/diff-viewer.tsx (new), apps/web/src/test/engine-gates-diff.test.tsx (new)
change:
1. `GatesPanel({ gates, waiverReason })`: one row per gate (Persian names: tests تست‌ها، diff_guard نگهبان
   تغییرات، no_progress بدون پیشرفت، green دروازهٔ سبز، lint لینت), green/red badge, time, expandable `<pre>`
   detail; when `waiverReason` a warning box «صرف‌نظر از تست با دلیل: …».
2. `DiffViewer({ diff, mergedSha })`: read-only, `dir="ltr"`, lines starting `+` green, `-` red, `@@` muted;
   empty → «هنوز تغییری ثبت نشده است.». When `mergedSha`: «ادغام و ارسال شد: {sha.slice(0,12)}» with a link
   to `/app` («مشاهدهٔ خط لوله در صفحهٔ اپلیکیشن»).
3. Test: red gate expands to its detail; waiver shown; diff coloring classes; sha link.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-gates-diff.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T36 — wire `/tasks/[id]` (engine view for engine tasks, legacy view kept)
status: done
group: g5
after: T23, T33, T34, T35
files: apps/web/src/app/(app)/tasks/[id]/page.tsx, apps/web/src/test/engine-task-page.test.tsx (new)
change:
1. Load `engineApi.getTask(orgId, taskId)`. When `stage` is not null render: header with stage badge +
   `TaskActions`, an answer box when `pending_user_decision` (`engineApi.answerTask`), `PipelineStepper`,
   `LiveLog`, `GatesPanel`, `DiffViewer`, `TurnTimeline`. **Hide the legacy «اجرا» button** for engine tasks.
2. Legacy tasks (stage null) keep the current runs/approvals view unchanged.
3. Live: `task.step` and `task.gate` on `task:<id>` reload the detail (debounced 500 ms).
4. Test: an engine task shows the stepper and no «اجرا»; a legacy task still shows «اجرا»; a `task.gate`
   event triggers a reload.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-task-page.test.tsx src/test/engine-task-detail.test.tsx src/test/engine-live-log.test.tsx src/test/engine-gates-diff.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T37 — workforce components: team panel + hire dialog (role + tier only)
status: done
group: g6
after: T21, T22
files: apps/web/src/app/(app)/workforce/_components/team-panel.tsx (new), apps/web/src/app/(app)/workforce/_components/hire-dialog.tsx (new), apps/web/src/test/engine-workforce.test.tsx (new)
change:
1. `TeamPanel({ orgId, team, canManage, onChanged })`: rows with name (link `/workforce/{id}`), role label,
   tier label, status badge, current task link (`busy_task_title`), «حذف از تیم» with `ConfirmDialog` →
   `engineApi.fire`; header «{count} از {max_employees} نفر».
2. `HireDialog({ orgId, tiers, onHired })`: role select (manager/planner/developer/reviewer/tester), tier select
   from `team.tiers`, optional name → `engineApi.hire`; disabled when at the cap or no tier is granted
   («مالک سامانه هنوز مدلی برای این سازمان تخصیص نداده است.»).
3. Test: render with a fixture whose employee carries extra fields `ai_model_id: "m-123"` and
   `model_name: "gpt-secret-x"` and assert neither string is in `document.body.textContent`; hire posts
   role + tier; fire asks for confirm first.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-workforce.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T38 — wire `/workforce` to the team panel
status: done
group: g6
after: T37
files: apps/web/src/app/(app)/workforce/page.tsx
change:
1. Replace the template/routing-based create form and list with `TeamPanel` + `HireDialog` fed by
   `engineApi.getTeam(orgId)`; `canManage` = `CAN_MANAGE_EMPLOYEES`. Reload on `team.changed` (`org:<id>`).
2. Remove imports that become unused (`api.listAgentTemplates`, `api.createEmployee`) from this page only.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-workforce.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T39 — `/workforce/[id]`: tier instead of routing policy for non-owners
status: done
group: g6
after: T21
files: apps/web/src/app/(app)/workforce/[id]/page.tsx:55-140,240-260, apps/web/src/test/engine-workforce-detail.test.tsx (new)
change:
1. Show the employee's tier label (from `engineApi.getTeam`) and role label. The routing-policy select (and
   the `api.listRoutingChoices` call) renders only for `user.is_platform_owner`; for everyone else the update
   payload omits `routing_policy_id`.
2. Test: a non-owner sees the tier and no routing select and no routing choice names; the owner sees the select.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-workforce-detail.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T40 — dashboard engine widgets
status: done
group: g7
after: T21, T22, T24
files: apps/web/src/app/(app)/dashboard/_components/engine-widgets.tsx (new), apps/web/src/app/(app)/dashboard/page.tsx:100-125, apps/web/src/test/engine-dashboard.test.tsx (new)
change:
1. `EngineWidgets({ orgId })`: `CreditNotice` + balance `Stat`; «کارهای فعال» (up to 5 non-terminal engine
   tasks, stage badge, link); «توزیع مراحل» (one row per `BOARD_COLUMNS` column with a count bar from
   `status.stage_counts`); «آخرین کارهای انجام‌شده» (5 newest completed). Live via `useEngineStatus` + reload
   of `engineApi.listTasks` on `task.step`.
2. Render it at the top of the dashboard page; keep every existing widget.
3. Test: counts per column, active list, completed list, notice at zero credit.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-dashboard.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T41 — traces: recent engine turns widget
status: done
group: g7
after: T21, T22
files: apps/web/src/app/(app)/traces/_components/engine-turns.tsx (new), apps/web/src/app/(app)/traces/page.tsx:100-200, apps/web/src/test/engine-traces.test.tsx (new)
change:
1. `EngineTurns({ orgId })`: `engineApi.listTurns(orgId, 30)` as a `Table` (کار link, نقش, مرحله, نتیجه
   badge, ابزارها, مدت), reload on `task.step` (`org:<id>`).
2. Add it as a section of the traces page; keep the existing run/audit widgets working.
3. Test: rows render with Persian role/stage; a failed turn shows its error kind; no model text.
check: cd /projects/smart-org && cp packages/contracts/src/index.ts node_modules/@agy/contracts/src/index.ts && cd apps/web && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/engine-traces.test.tsx && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json

## T42 — D-E: stale web comment + agent-3 final report overstatements
status: done
group: g8
after: none
files: apps/web/src/lib/api-org.ts:299-311, docs/plan/reports/agent-3-final.md:25,101,125-129,159-161,193-216
change:
1. `api-org.ts`: rewrite the comment above `MEMORY_CHANGED_EVENT`: the type is part of `WsEventType` in
   `@agy/contracts`; the constant only names it. Type it `as const satisfies WsEventType` if that compiles,
   otherwise leave the value untouched.
2. `agent-3-final.md` (verify each against code first: `admin_domains.py::suggested_routes`,
   `models_delivery.py` tables, `sandbox.py` admin router):
   - line 25 and line 101: say the MCP gateway host is a read-only **suggestion**, not a route the owner can
     enable (the label `mcp` is protected).
   - §5: remove `system_routes` from the table list (the tables are `pipeline_runs`, `pipeline_steps`,
     `releases`, `app_runtimes`, `production_deploys`; MCP lives as a suggestion computed from settings).
   - §6 step 9: replace "Enable the MCP system route; `mcp.<root>` must answer" with "check that
     `GET /api/admin/domains/suggested` shows `mcp.<root>` as a suggestion (enabled=false)".
   - §8: add "`/admin/sandbox` lists and stops containers; there is no restart action (TODO 6.3 open)".
check: cd /projects/smart-org && ! grep -n "system_routes\|Enable the MCP" docs/plan/reports/agent-3-final.md && grep -n "restart" docs/plan/reports/agent-3-final.md && cd apps/web && node /projects/smart-org/node_modules/typescript/bin/tsc --noEmit -p tsconfig.json && node /projects/smart-org/node_modules/vitest/vitest.mjs run src/test/org-memory.test.tsx

## T43 — Agent 2 final report + tick Agent 2's TODO
status: done
group: g8
after: none
files: docs/plan/reports/agent-2-final.md (new), docs/plan/TODO-agent-2-ai-workforce.md:41-155
change:
1. Run this task after the other groups (it describes what exists; verify everything with `ls`/`grep`, never
   from this plan). `agent-2-final.md` per the TODO's "Final report" section: summary; a text diagram
   (order → manager chat → task + state → tick: triage → planner → developer → gates → tester → final →
   merge/push → on_branch_pushed → pipeline run); the tag protocol table (role/mode → tags, from
   `engine/protocol.py`); every endpoint added or changed (`routers/engine.py` T17–T19, `admin_credits.py`
   T11, the billing lockdown T12, `POST /tasks` creating a state and `start_run` 409 T14); tables
   (`task_pipeline_state` incl. `last_diff`/`merged_sha`, `employee_profiles`, `engine_turns`, `gate_results`,
   `credit_transactions`); settings (`ENGINE_*`, `BILLING_STARTING_CREDIT`); realtime events (`task.step`,
   `task.gate`, `run.log`, `run.tool`, `team.changed`); CHANGE REQUESTs: none open (`get_org_policy` landed
   as old T1, memory expiry as old T9); manual QA (owner credits an org → order → board moves live → task page
   log/gates/diff → pause/resume/cancel → zero credit pauses and resume is refused → hire/fire by tier with no
   model names); known limitations (turns sequential per tick, the diff is capped at 20,000 chars, budget-paused
   tasks are resumed by hand after credit is added, invoices from the billing worker are informational under
   prepaid).
2. TODO-agent-2: tick each box whose deliverable exists in code (phases 1–4 and phase 5 items 5.1–5.7 when
   their files and tests exist); anything missing stays `- [ ]` with `— open: <reason>`.
check: cd /projects/smart-org && test -s docs/plan/reports/agent-2-final.md && grep -c "^- \[x\]" docs/plan/TODO-agent-2-ai-workforce.md && grep -n "^- \[ \]" docs/plan/TODO-agent-2-ai-workforce.md; grep -n "task.step\|admin/orgs\|credit_transactions" docs/plan/reports/agent-2-final.md

## T44 — PLAN-v2 §9, README (prepaid, new env, engine UI)
status: done
group: g8
after: T43
files: docs/plan/PLAN-v2.md:282-305, README.md:12-48,233-314
change:
1. PLAN-v2 §9: replace the line "Zero-wallet pause fixed (T3): only an overdrawn wallet pauses a task" with
   the prepaid decision (D-B: owner credits, usage debits once per usage event, zero/negative/missing wallet
   pauses turns and the manager chat). Replace the "Left to Agent 2 phase 5" block with a ticked list pointing
   at `todo-v2-final.md` (UI, contracts, direct tasks through the engine, pause/resume/cancel, cap 7,
   owner credit console). Tick a line only if its task here is `status: done` at that moment.
2. README: §1 one paragraph «اعتبار پیش‌پرداخت» (the owner credits each org at `/admin/credits`; work stops at
   zero); §8 table row `BILLING_STARTING_CREDIT` (default 0); §9 note that the ai-runtime pass pauses tasks of
   orgs without credit. Persian, same tone.
check: cd /projects/smart-org && grep -n "پیش‌پرداخت\|BILLING_STARTING_CREDIT" README.md && grep -n "todo-v2-final\|prepaid" docs/plan/PLAN-v2.md

---

## final

Every task above edits one to four small files (plus its own new test), so no further split is needed:
**final**.

| id | group | title |
|---|---|---|
| T1 | prepare | migration + ORM: `credit_transactions`, `last_diff`/`merged_sha`, policy default 7 |
| T2 | prepare | domain + repositories: state fields, org turns list, paused/stage counts |
| T3 | prepare | scheduler stores the latest diff and the merged sha |
| T4 | prepare | publish `task.step` on every stage move |
| T5 | prepare | credit ledger repository (atomic credit/debit, history) + `fund_org` test helper |
| T6 | prepare | every usage event debits the wallet once (`UsageLedgerRepository.record`) |
| T7 | prepare | prepaid pause: zero/negative/missing wallet pauses engine turns |
| T8 | prepare | manager chat refuses to call a model at zero credit |
| T9 | prepare | fund the chat tests + fix the two stale test comments |
| T10 | prepare | `CreditService`: owner credit, history, balances, starting credit |
| T11 | prepare | owner-only `/api/admin/credits` + `/api/admin/orgs/{org}/credit` (+history) |
| T12 | prepare | close the free-credit holes in `/billing/add-credit` and `/settle` |
| T13 | prepare | optional `BILLING_STARTING_CREDIT` for new orgs |
| T14 | prepare | direct tasks (HTTP + MCP) get a pipeline state; legacy `start_run` refuses them |
| T15 | prepare | update the remaining tests that relied on the legacy direct-task path |
| T16 | prepare | `Scheduler.user_action`: pause/resume/cancel/answer |
| T17 | prepare | engine read API: status, board, detail, turns |
| T18 | prepare | engine action API: pause/resume/cancel/answer (audited) |
| T19 | prepare | engine team API: tier view, hire by role+tier, fire |
| T20 | prepare | contracts: engine event types + payloads |
| T21 | prepare | `lib/api-engine.ts` typed client |
| T22 | prepare | `lib/engine-labels.ts` (stages, columns, tiers, roles) |
| T23 | prepare | shared `TaskActions` with confirm |
| T24 | prepare | shared `CreditNotice` + `useEngineStatus` |
| T25 | g1 | default employee cap 7 (backend, tests, admin page default) |
| T26 | g2 | `lib/api-credit.ts` owner credit client |
| T27 | g2 | owner page `/admin/credits` + admin tab |
| T28 | g2 | billing page read-only for members + notice; wizard success note |
| T29 | g3 | manager components: inline task cards + decision banner |
| T30 | g3 | wire `/manager` |
| T31 | g4 | task board component |
| T32 | g4 | wire `/tasks` |
| T33 | g5 | pipeline stepper + turn timeline |
| T34 | g5 | live log panel |
| T35 | g5 | gates panel + diff viewer + waiver + sha link |
| T36 | g5 | wire `/tasks/[id]` |
| T37 | g6 | team panel + hire dialog (no model names) |
| T38 | g6 | wire `/workforce` |
| T39 | g6 | `/workforce/[id]`: tier for non-owners, routing only for the owner |
| T40 | g7 | dashboard engine widgets |
| T41 | g7 | traces engine turns widget |
| T42 | g8 | D-E: api-org comment + agent-3 report fixes |
| T43 | g8 | Agent 2 final report + tick TODO-agent-2 (run after the other groups) |
| T44 | g8 | PLAN-v2 §9 + README |

Assumptions made (decide before running if any is wrong):
1. **Prepaid is strict:** a missing wallet counts as zero, so it pauses (only test fakes pass `wallets=None`;
   every real org gets a wallet at creation). Debits may take a wallet below zero (a turn that started with
   credit finishes); the next turn is then paused.
2. **Budget-paused tasks are resumed by hand** (the «ادامه» button, refused while credit is still zero). The
   engine cannot tell a budget pause from a user pause (no reason column), so adding credit does not resume
   tasks automatically. The manager chat is also gated at zero credit (it costs model calls).
3. **Direct tasks** become engine tasks at `pending_manager_review` with kind `feature`; the manager's triage
   picks the real pipeline and assignee. Pre-v2 tasks without a state keep the legacy run path, and tests of
   that path use a direct-row helper.
4. Owner credit history, the owner's `add-credit`, starting credit and usage debits all live in one new table
   `credit_transactions`; the platform owner is the only one who can add credit (org admins lose
   `add-credit`/`settle`; `checkout` still only creates a pending payment). Invoices from the billing worker
   stay informational.
5. The starting credit is an env setting (`BILLING_STARTING_CREDIT`, default 0), not an owner-editable UI value.
6. The diff shown on the task page is the last accepted diff, stored on the state and capped at 20,000 chars;
   the pushed sha is stored as `merged_sha` and linked to `/app` (Agent 3's page) without a run id.
7. Org members (all roles) can read `GET /engine/status`, which includes the wallet balance, so they can see why
   work stopped. Mutations follow the existing capabilities (`CAN_RUN_TASKS`, `CAN_MANAGE_EMPLOYEES`).