Auth-on agent services need super-admin credentials at every launch, but
svc only forwarded them from the current environment, and recover/watchdog
relaunch with a cleared environment, so a bare restart or recovery failed
closed. svc now records only the absolute path of AGENT_SYSTEM_ENV_FILE as
superadmin_envfile= after checking it is a regular, owner-only (0600) file
before stopping anything, and forwards that path when no explicit
credentials are set. An empty AGENT_SYSTEM_ENV_FILE clears the record. The
file content is never read, copied or printed.
Why: prod restarts and recovery required re-exporting AGENT_SYSTEM_ENV_FILE.
Evidence: agent-exec unit dev-svc-superadmin-envfile-persist (cursor, attempt 1, terminal=success); unittest test_svc_superadmin_envfile + test_svc_recover + test_svc_identity: 51 OK (1 skipped).
Impact: svc.sh agent launch and svc.env gain superadmin_envfile; docs/svc.md 4.2 note.
Refs: Dev task fix/svc-superadmin-envfile-surface-conv.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: include the current integration baseline before verification.
Evidence: fetched origin/main=d9ac28f89159e17781e2a8ef3094965130f29d2f.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
Why: Settings plaintext loses to secret_keys, so replacing the env key did not change the key a conversation actually sent.
Evidence: python3 -m unittest tests.test_svc.SvcDbRecoveryTests.test_seed_replaces_old_system_secret tests.test_svc.SvcDbRecoveryTests.test_seed_warns_when_old_secret_stays_active tests.test_svc.SvcDbRecoveryTests.test_seed_puts_without_credentials_when_auth_off (SELF).
Impact: Embedded databases now compare the active system secret fingerprint after seeding, and the backend gitlink carries the adoption fix.
Refs: fix/model-key-secret-overlay
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: include the current integration baseline before verification.
Evidence: fetched origin/main=692735e91d6a9ab07ddd3686feb60a56b270728a.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: The dev service is an rdm build, so startup skipped model seeding and kept the old MiniMax chat model. Later starts need the saved env file applied even without an admin key command.
Evidence: seed and rdm launcher tests passed. The live dev database now uses the four-model chat route and keeps the original MiniMax endpoint as reserve.
Impact: Restart of a service with envfile set rewrites system model settings. HTTP seeding is unchanged for builds that can mint an admin key. MiniMax is stored separately because fallbacks cannot switch gateways.
Refs: .task/feature-four-model-vision.md
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: Chat, lightweight, fallback and vision settings need a seed path, and the backend now sends current-turn images only to models declared capable of seeing them.
Evidence: The backend change is cfde38d. The seed test covers fallback and vision settings. A local image conversation on each builtin profile returned the pictured content from the expected model, and removing the chat model from the capable list switched that turn to the vision model.
Impact: New runs can use the four builtin profiles and image input. Secrets stay in the ignored env file. The live 8788 process is unchanged.
Refs: .task/feature-four-model-vision.md
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: deploy needs to choose registered plugins and ship them inside one agent-system, then refuse the release when they are not active.
Evidence: python3 -m unittest tests.test_svc_plugins tests.test_svc_user_help tests.test_svc tests.test_svc_u2 (SELF, 63 passed, 1 skipped). Real compose build and make test-lifecycle are NOT_RUN.
Impact: --with is mutually exclusive with --from rdm and --from release. Existing non-interactive deploys stay without plugins unless plugins= is already recorded. Changing the plugin id set on a live service requires --allow-source-switch.
Refs: .task/feature-svc-plugin-compose.md modules/documents/docs/proposals/2026-10-14-svc-plugin-compose-deploy.md
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: include the current integration baseline before verification.
Evidence: fetched origin/main=4f84c2e1630cd0311643529fae1c3a99f1dd5d64.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
Why: Operators need the approved no-password initialization and owner-confirmed recovery contract, and stage 6 reviewers need an exact component/evidence map.
Evidence: SELF task-card precheck and make test-governance receipts; component receipts listed in the task card with separate source identities.
Impact: svc rejects obsolete credential commands before storage binding, help points to protected delivery and recovery proposals, and the task card records stage 6 scope with formal pin/CI dependencies still pending.
Refs: IAM U3 r1 Documents c236d309; Backend 3e01614; RDM 265d33e; Frontend a961b19
Why: include the current integration baseline before verification.
Evidence: fetched origin/main=d852c159b6b3387a2f418a42ab6d3696ac873d01.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
Why: Dev has to follow the commits that landed on Backend and Documents main, which share trees with the drilled objects.
Evidence: Backend dc736e339d01 tree 498f61947564 equals 46073d30. Documents 05c13a42b14d tree equals 5335499. GATE run 2794 on 6d8b746 succeeded before this pin.
Impact: gitlinks move to the merge commits. Second-instance writes stay closed.
Refs: #186#92#497
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: the restored drill passed artifact recovery, and the handbook, checklist, and collaboration plan have to say so without opening write traffic.
Evidence: backup-20261013-013354 on Dev a83588dd and backend 46073d30; K1-K7 true, RPO 65s, RTO 3s, five artifacts matched, cross-user access 404. SELF. Documents 5335499 is PR #92.
Impact: C5 is marked SELF-pass. Second-instance writes stay closed until REPLAY or CI and a second host exist.
Refs: docs/svc.md docs/release-multi-instance.md modules/documents
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: The measured backup, PITR, and disconnect steps were only in the drill scripts, and the checklist still said those rows were not run.
Evidence: Results pgbench-20261012-131948, fault-20261012-142734, and backup-20261012-153441 (SELF). K4 stays failed.
Impact: Second-instance write traffic stays closed. The handbook records the upload panic and the short socket path.
Refs: feature/u7-ops-drills
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: the integration tree has to carry the single-transaction account changes, and operators need to see that --dsn and --password still work while warning.
Evidence: Backend 545a75b. SELF store tests named in that branch. PostgreSQL, cross-process, and SIGKILL password checks are NOT_RUN locally.
Impact: Dev gitlink moves to 545a75b. scripts/svc.sh is unchanged and can keep passing --dsn and --password.
Refs: docs/svc-deploy/u7-account-tx-audit.md
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: include the current integration baseline before verification.
Evidence: fetched origin/main=b4b042630a352eca2a399a7a64931c74978bca7f.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
Why: make the six instance-bound user commands discoverable (T5-1) and pin Documents r2/r3.
Evidence: python3 -m unittest tests.test_svc_user_help; existing test_svc_user_binding still green.
Impact: scripts/svc.sh help accounts|user; docs/svc.md topic list; documents gitlink to plan branch tip.
Refs: Documents #87; feature/svc-account-durability-plan
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: RDM agent deploy left workbench htdocs unserved (prompt-only), so
environments like dev silently offered API-only 404 pages after a source
switch; static first-start also misclassified http.server as dead when
pidcheck was unset.
Evidence: CMD="make test-governance" make evidence (200 ok, 1 skipped; SELF).
Impact: rdm deploy auto-starts <name>web and asserts UI 200; cross-kind
redeploy needs --allow-source-switch; list/info flag missing workbench.
Refs: .task/feature-svc-rdm-ui-gate.md; docs/svc.md §5.4
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: After capability gate hid 追溯审计 on plain base, the shared dev
entry needs a pinned RDM combo and a candidate-then-cutover runbook.
Evidence: RDM #250 (310c3fe) pins to Dev main; candidate+cutover R1–R5
SELF receipts imported; FE preview showed audit entry on :8788.
Impact: docs/svc.md §5.4.1; local runtime/dev is rdm@310c3fe (ops, not
in git). Owner password was reset via recover key during verification.
Refs: feature/rdm-audit-combo-integration; RDM pulls/250
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: the 2026-10-11 runtime/ deletion lost all agent SQLite data with no
backup; the svc-autorecover closing report left "agent SQLite backup" as
a follow-up and the user asked to land it (recovery plan U2 residue).
Evidence: tests/test_svc_backup.py 11/11 green locally (live WAL writer,
manifest sha, retention, guards); make test-governance full suite green
(159 tests, rerun twice after one unreproduced flake).
Impact: new service-level actions backup/backups; snapshots live in
runtime-backups/<name>/ outside runtime/; rm --purge removes them; pg
backup and other flows unchanged.
Refs: modules/documents/docs/proposals/2026-10-12-service-restart-data-recovery.md r2 (sec 6, U2 residue); task card .task/feature-svc-agent-backup.md.
Why: include the current integration baseline before verification.
Evidence: fetched origin/main=3de5791e0841e9c7c40c3dc236be6d95b3969827.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
Why: RDM capabilities (two-trees-one-net, rdm.* trace-audit command face)
only exist in the downstream Agent-System-RDM composite binary; svc's three
existing sources all produce the Dev binary, so none of it could be deployed
or lifecycle-managed. This adds --from rdm[@<sha>] with the same isolated
source-repo semantics as the dev source.
Evidence: make test-governance 138/138 (two new stub cases: deploy E2E and
commits/update track); real deployment rdm@2aef3fc recorded in the task card
(pins materialized, pure-Go build, web workbench to htdocs, serve health OK,
rdm.ping/rdm.inspect.capabilities committed, update --check reports latest);
make test full suite exit=0. All segments written by make evidence.
Impact: scripts/svc.sh (rdm source resolution/materialization/deploy/update/
commits, probe timeouts, rdm seed skip, ELF env-DSN evidence fallback),
docs/svc.md 5.4, tests/test_svc.py. RDM-side CLI alignment landed as RDM
PR #228; no base submodules touched.
Refs: task card .task/feature-svc-rdm-source.md; RDM PR #228/#229.
Why: svc services are bare nohup'd processes with persisted registration
but no supervision -- a crash, an OOM kill, or a reboot left them dead
until manual restart (2026-10-11 outage: dev service lost, runtime/ also
wiped by hand, nothing brought services back).
Evidence: tests/test_svc_recover.py 10 cases green (start records
autostart, stop clears it incl. dead-process stop, SIGKILL then recover
revives with persisted exec=, lock-held skips, port-stolen fails with
recover fail event, watchdog unit text via --print); make test-governance
146/146 OK locally; real-machine watchdog install + kill -9 revival to be
recorded on the task card.
Impact: svc.sh gains autostart key in svc.env, `recover [name]
[--quiet]` (postgres-first, per-service .start.lock, recover history
events), `watchdog install|remove|status` (systemd user timer, cron
fallback hint), lifecycle lock across start/stop/restart/deploy/update;
spawned services no longer inherit the lock fd (9>&-), and lock release
no longer clobbers script stderr. Makefile adds svc-recover/svc-watchdog;
docs/svc.md documents semantics and boundaries.
Refs: task card .task/feature-svc-autorecover.md; docs/svc.md 6.5/6.6;
parallel planning card feature/service-restart-recovery-plan (same
problem space, plan-stage).
Why: the exec= reuse path stripped --dsn into the process environment (G1-7)
and record_state then persisted a DSN-less exec=, while the dbref fallback only
existed in the explicit-rebuild branch - the second bare restart after a
rebind silently dropped the database (SQLite fallback on loopback). Auth
preflight also matched --dsn on the command line only, so env-delivered DSN
with auth=auto was misjudged as unauthenticated.
Evidence: bash -n OK; make test-governance 115 tests OK (new tests/test_svc.py
11 cases; 10/11 fail against the pre-fix script); make test green; make build
OK; isolated real PostgreSQL 18.6 + real binary validation 27/27 (consecutive
restarts/deploy keep binding, psql-verified database identity, DB-down restart
fails without SQLite fallback or config loss, no credential leakage) - all
recorded via make evidence in the task card.
Impact: svc.env gains db=/dbref=/dsn= recovery keys (atomic 0600 writes);
start/restart/deploy/update/db share one resolver; invalid bindings, config
conflicts, mock coexistence and env-DSN-incapable binaries now refuse to
start instead of silently downgrading; legacy exec= DSN migrates idempotently;
docs/svc.md and script help updated.
Refs: task card .task/feature-svc-db-config-recover.md; user-approved plan
(2026-10-11 session message); AGENTS.md evidence gates.
Why: The research record, HTML cleaning, listen guard, secret store, and context controls land together, and the parent pointers have to name those commits.
Evidence: Child commits are core bd63223, agent-native 3a110a7, ui d76a8e6, frontend 36b92ed, documents f3f823e, backend 42cca8f. svc.sh forwards the listen switches and info prints them.
Impact: A reverse proxy or a LAN hostname needs allowedHosts or an unauthenticated host check returns 403. Startup moves raw API keys into the secret table after a settings snapshot.
Refs: .task/feature-sillytavern-review.md
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: beyond database binding, services needed a way to switch the JSON config
file they run with and have the new config take effect promptly; hand-editing
exec= risks restarting a service into an invalid config.
Evidence: in the task worktree with a real agent binary -- a config with an
unknown key is rejected by the binary's strict schema check before any state
change; a valid file binds via --config in exec= + conffile= (survives
record_state rewrites), restarts the running service, and the config's dsn
verifiably drives the process (wrong-password variant failed PG auth in the
log; correct variant connected and created 21 tables); editing the file and
re-running 'config <same file>' re-validates and restarts (pid changes);
'--clear' removes both the flag and conffile; db and config coexist in exec=;
view mode shows masked JSON content plus 'config explain' effective values
with masked dsn; list DB column also resolves dsns that live only inside the
config file. Full log in the task card.
Impact: new service-level action 'svc.sh <name> config [file | --clear]
[--no-restart]' for agent services; config-file content snapshots (masked,
--reveal to show) in info; a config-file line in status; conffile persisted
in svc.env. No agent binary changes.
Refs: task card .task/feature-svc-db-bind.md (same doc as PR #182);
docs/svc.md sections 2/4.5/4.6/6/10.1
Why: info showed services and postgres instances but no service-to-database
correspondence, and switching an agent service to another database required
redeploying with a hand-built DSN. While wiring this up, adjust_args_for_bin
was found matching Go flag help with '--dsn' although Go prints '-dsn', so
deploy-built --dsn/--auth args were silently dropped on current binaries.
Evidence: full E2E in the task worktree with a real agent binary and a real
PostgreSQL 18 instance -- 't-app db bpg' persisted exec=/dbref, auto-restarted
(dbref survives record_state rewrites), and the agent created 21 tables in the
bound database; 'db bpg --db t2' auto-created and switched databases (21
tables in t2); '--clear' returned the service to embedded SQLite; --no-restart
and error paths behave; list gains a DB column, status a database line, info a
reverse bound-services line; legacy deployments without dbref resolve by DSN
host:port; single-dash detection proven with positive and negative cases;
regressions list/db dsn/db ls/info/history/--help pass; make test exit 0.
Full log in the task card.
Impact: new service-level action 'svc.sh <name> db [pg [--db X] | --clear]
[--no-restart]' for agent services (bind/switch/unbind/view), DB column in
list, binding lines in status/info, dbref persisted in svc.env, auto database
creation when the instance runs, and the adjust_args_for_bin fix restoring
deploy --dsn/--auth on current binaries. No agent binary changes.
Refs: task card .task/feature-svc-db-bind.md (same doc as the PR); docs/svc.md
sections 4.5/6.1/6.2/10.1
Why: svc.sh could show a service table (list), per-instance DB names one at a
time (db ls), and per-service status, but had no single view answering "what
is running, which databases exist, and what is configured" -- the questions
asked when inspecting or handing over a machine.
Evidence: exercised in the task worktree runtime -- empty-state report; fake
agent/static/postgres registrations proving masking (exec DSN password,
password=, SVC_TAVILY_KEYS -> ***, non-secret values verbatim; --reveal shows
plaintext); a real postgres instance (db create r-pg --port 18901, start,
extra orders db, one backup) whose info section lists inner databases with
sizes, pgdata size and backup stats; regressions list/history/--help/help
lifecycle/make svc-info; info stdout carries the full report (stderr 0 bytes)
so it can be redirected as a snapshot. Full log in the task card.
Impact: new read-only `scripts/svc.sh info [name] [--tag T] [--reveal]`
command (also `make svc-info`): service table + running summary, postgres
instances incl. inner databases, per-service svc.env content snapshots plus
global .svc.env / --config / exported SVC_* vars, and recent events. Secrets
are masked by default. No deploy/lifecycle/db-ops behavior changes; `info`
becomes a reserved service name; docs/svc.md gains section 6.2 (former
6.2-6.4 shifted to 6.3-6.5).
Refs: task card .task/feature-svc-info.md (same doc as the PR); docs/svc.md
Why: svc.sh update skipped services with a local@<sha> source whenever the
main checkout was dirty, and bare deploy built the current workspace. The
owner requires updates/deploys to be independent of the working tree
state, defaulting to the latest remote commit built outside the checkout.
Evidence: bash -n passes; commits dev lists from the source clone; bare
deploy --dry-run plans dev@<origin/main>; end-to-end "svc.sh update
svc-selftest" with a dirty tree updated a local@d64742c service to
dev@0be23f9 (built in runtime/.worktrees from
~/.cache/agent-system-svc/src, started healthy), then stopped and purged.
Full make test output recorded on the task card.
Impact: deploy now defaults to dev@<origin/main> resolved in the
script-owned clone (SVC_SRC_DIR, default ~/.cache/agent-system-svc/src);
--from local stays the only workspace-dependent source; update no longer
pulls the main checkout - local@/dev@ services redeploy from remote
latest, ahead/diverged/missing-on-remote still decline to act.
docs/svc.md and in-script help updated to match.
Refs: .task/svc-remote-source.md
Why:
After the repository moves forward, updating a running service meant
manually figuring out the new commit, rebuilding and redeploying by hand;
the user asked for the tool to detect and update automatically.
Evidence:
- "update [name...] [--check] [--all] [--no-fetch]": fetches origin,
compares each service's registered source against the latest (Dev repo
origin/main for local@/dev@ sources, newest Releases version for
release@), prints a per-service table (current / latest / state), and
without --check refreshes outdated running services by reusing the full
deploy pipeline (stop → build/verify → start → health check; persisted
exec= config and tags survive; update events appended to history).
- local@ services: auto git pull --ff-only origin main + make sync before
rebuilding, guarded three ways (current branch == main, clean worktree,
ff-only) — dirty trees or non-main branches are skipped with a warning,
never touching uncommitted work.
- dev@ sources go straight to the remote main commit via an isolated
worktree; release@ sources deploy the newest Releases version with
sha256 verification; postgres and static --dir services are reported as
not applicable; sources that diverged from or lead the remote are never
force-updated.
- Verified end to end with five test services: dev@73b2802 → dev@ffda6d3
(real isolated build, HTTP 200, tag/port preserved, worktree recycled),
non-main-branch skip, stopped-service warning vs --all, release
sha256-verified update, --check read-only (svc.env checksums unchanged),
unregistered name exits 2.
- Fixed en route: a latent bug from the v2 refactor — materialize_dev_commit
leaked submodule/make stdout into the captured worktree path, breaking
every real dev@sha deploy since (cp: File name too long); build output
now goes to stderr. Also fixed an unbound-variable crash in the update
loop (local statement self-reference under set -u).
Impact:
New read-mostly operational command; no behavior change to existing
commands except dev@sha deploys now actually working end to end.
Makefile gains svc-update; --help and docs/svc.md document the command.
Refs: .task/feature-svc-auto-update.md（任务卡=PR 描述）
Why:
svc.sh grew into a three-kind service manager with database operations,
but its only documentation was a flat --help wall of text; the user asked
for a complete usage document and a better help experience.
Evidence:
- docs/svc.md: 14-section manual (prerequisites, quick start, concepts
and directory layout, per-command reference for service/global/db
commands, deploy sources, database operations handbook, configuration
layering, registry fields and event types, safety boundaries, exit
codes, troubleshooting table, recipe index) — every claim cross-checked
against the implementation from the previous two rounds.
- Help layering: no-args and -h print a one-screen overview; --help
renders the header comment reorganized into 7 labeled sections; the new
"help [topic]" command deep-dives eight topics (model, deploy,
lifecycle, db, dbops, config, examples, safety); usage errors now show
the short overview plus a pointer to --help / help / docs/svc.md.
All topics verified to render; unknown topic exits 2.
- No runtime behavior changed: end-to-end db lifecycle regression
(create → start → backup → status → stop → rm --purge) passes after the
refactor.
- Makefile help and README's documentation section point to docs/svc.md.
Impact:
Documentation-only plus display-layer changes; command semantics,
exit codes and file formats are untouched. Maintenance note: behavior
changes must now update both --help and docs/svc.md.
Refs: .task/feature-svc-docs-help.md（任务卡=PR 描述）
weichen