Why: batch update leaked AGENT_SYSTEM_INSTANCE_ID/DBREF from one service
to the next, and RDM artifacts without the identity CLI were stopped and
overwritten before their startup identity refusal surfaced, leaving
rdm1/rdmcand in a mixed registration-vs-artifact state (2026-10-12).
Evidence: make test-governance 217 OK; tests.test_svc_identity and
tests.test_svc_precheck green; rows recorded in the task card.
Impact: env_config resets identity env per service; capability probe is
timeout-guarded and rejects serve-shaped output; identity ensure moves
to adoption/init (bare start is verify-only); deploy builds and gates
candidates before stopping the old service (refuses identityless
candidates, completes missing identity rows via the candidate); update
runs svc_manifest_migrate like every other lifecycle entry.
Refs: .task/feature-svc-identity-u1.md; user root-cause report 2026-10-12.
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: include the current integration baseline before verification.
Evidence: fetched origin/main=c6fefa3435dc5d9524fc35483f1d34fa1a6e0d59.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
# Conflicts:
# tests/test_svc.py
Why: Batch update --all left SVC_PIDCHECK from the prior service in
memory, so pid_alive/reclaim_own_port misclassified the next service's
process as dead/foreign, deleted svc.pid, and failed start on a still-
occupied port (genui/rdm1/rdmcand after successful dev).
Evidence: make test-governance (SELF; receipt /tmp/svc-pidcheck-gov.json);
new test_batch_update_stops_second_service_despite_prior_pidcheck +
SVC_PIDCHECK ratchet in test_svc_precheck.
Impact: env_config clears SVC_PIDCHECK/EXEC/VERSION/SOURCE per service;
batch update correctly stops and restarts each agent. After merge:
restore genui/rdm1/rdmcand and move rdmcand to its own data dir.
Refs: .task/feature-svc-pidcheck-leak.md; complements #456 reclaim_own_port
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: genui update cleared svc.pid without killing the process, then
overwrote the binary and failed start with a false "non-ours" port error.
Evidence: make test-governance (receipt /tmp/svc-reclaim-governance.json)
Impact: reclaim_own_port walks ss listener ancestry; stop/check_port/install
wire it; orphans matching pidcheck are stopped, foreign occupants still refused
Refs: fix/svc-reclaim-own-port
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: include the current integration baseline before verification.
Evidence: fetched origin/main=673e687c5c85b9af3ce13ca30845d5e68de5dfa0.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
Why: include the current integration baseline before verification.
Evidence: fetched origin/main=b431777c9fa9c74f096d7f14fce40d1beba53fe2.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
Why: Dev #429 conflicted on scripts/svc.sh (U1 user vs main backup) and Backend gitlink.
Evidence: conflict hunks resolved; actions include init|user|backup|backups
Impact: PR #429 should become mergeable after push; both U1 binding and agent backup entrypoints preserved.
Refs: Dev pulls/429; main backup #417; Backend #171
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: include the current integration baseline before verification.
Evidence: fetched origin/main=af9c2de663be5ff102dcab7698464a645832f569.
Impact: integrate upstream changes without rewriting task history.
Refs: task-sync
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: systemd's default KillMode=control-group kills every process in
the unit's cgroup when the oneshot finishes -- the daemon recover just
started died seconds after the recover ok event (observed live on the
host: revived at 22:13:40, gone by 22:13:42).
Evidence: unit text now carries KillMode=process (asserted in
test_watchdog_print_plan); suite 10/10 and make test-governance rerun
recorded on the card; live re-demo on the host after merge.
Impact: scripts/svc.sh wd_service_text only.
Refs: .task/feature-svc-autorecover.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: check_port_free consulted port_owner (ss -ltnp) only, so the
/dev/tcp fallback added to port_listening never ran on the start path;
CI (no iproute2) still started onto a thief-held port.
Evidence: no-ss simulation refuses a bound port and passes a free one;
full suite 10/10 and make test-governance rerun recorded on the card;
CI on the new head is authoritative.
Impact: scripts/svc.sh check_port_free only.
Refs: .task/feature-svc-autorecover.md
Why: the CI runner container has no iproute2, so port_listening went
blind: recover started a service onto a thief-held port and the health
probe hit the thief (HTTP 200), reporting a bogus start success.
Evidence: no-ss PATH simulation shows the fallback detects a bound port
and passes free ports; make test-governance rerun recorded on the task
card; CI on the new head is authoritative.
Impact: scripts/svc.sh port_listening only (ss stays primary when
present).
Refs: .task/feature-svc-autorecover.md
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: seed_settings PUTs /api/settings/user without credentials, so under the PG tier's always-on auth the seed always 401s and model config silently never lands (reproduced on the dev instance 2026-10-11; settings had to be written by hand).
Evidence: make test-governance && make test exit=0 (receipt 8ffc3a89); tests/test_svc.py adds three stub-based cases - auth-on seeds with a Bearer header and create/revoke around the PUT, --seed-owner skips account lookup, auth-off stays credential-free; 14/14 svc tests green.
Impact: deployments that pass SVC_MODEL_*/SVC_TAVILY_KEYS now seed reliably regardless of auth mode; a temporary apikey (name=svc-seed) is minted for the first admin (or --seed-owner/SVC_SEED_OWNER) and revoked right after; auth-off path unchanged.
Refs: task card feature-svc-seed-auth.
Why: main landed fix-svc-dsn-reuse-dbref (reuse-path dbref restore, env-DSN
aware precheck, DSN_ENV scoping) for the same restart-DSN incident; the
approved recovery plan is its superset and replaces those mechanisms with
resolve_db_config + recoverable svc.env keys + refuse-on-invalid semantics.
Evidence: tests/test_svc_precheck.py ported to the new units (18 cases green,
same scenario matrix; broken-dbref expectation updated to refusal per the
approved plan); tests/test_svc.py 11 cases green; bash -n OK.
Impact: conflict hunks resolved toward the unified resolver; main's source
guard at the script tail restored; agent_listen_rejected kept as a pure
predicate (used by the start precheck and the governance tests).
Refs: main 7acf318 (PR #317); task card .task/feature-svc-db-config-recover.md.
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: G1-7 moved the DSN into AGENT_SYSTEM_DSN, but the precheck only read
the arg string, so a non-loopback restart with auth auto was wrongly
rejected (2026-10-10 dev incident); the reuse path no longer restored the
dbref-bound DSN and would silently fall back to SQLite; and DSN_ENV leaked
across same-process starts (update --all) into other services' env.
Evidence: tests/test_svc_precheck.py 19 cases green (auth matrix vs
config.go AuthEnabled, reuse migration/dbref restore, scope isolation);
full governance suite 123 green; incident-scenario replay allowed + DSN
carried. Recorded via make evidence.
Impact: scripts/svc.sh precheck and reuse-start DSN handling only; no
binary change, no persistence-format change.
Refs: .task/fix-svc-dsn-reuse-dbref.md; config.go AuthEnabled (on || (not
off && DSN non-empty), env DSN counts).
Why: the plan section 3.4 observed the local dev service carrying the
credential-bearing DSN as a serve --dsn argument, visible to any
process on the host (ps / /proc/<pid>/cmdline) — including scripts
generated by agents. The base config layer already supports
AGENT_SYSTEM_DSN, so the launcher can move the secret out of the
argument vector without touching the binary.
Evidence: bash -n clean; make test-governance 104/104 green; an
end-to-end probe with a stub binary and a legacy exec= carrying
--dsn ...secret... shows the migration stripping the flag
(MIGRATED:yes), the process args free of the secret
(NO-LEAK-IN-CMDLINE), and AGENT_SYSTEM_DSN present in the process
environment (DSN_IN_ENV:yes). New/rebuilt launches never put the DSN
in argv; legacy persisted configs are migrated on first reuse.
Impact: scripts/svc.sh only — rebuild path sets DSN_ENV instead of
--dsn, reuse path strips --dsn from stored exec= once and logs the
migration, launch injects AGENT_SYSTEM_DSN alongside the existing
guard vars. CLI --dsn still wins inside the binary (config
precedence), so manual invocations are unchanged.
Refs: plan G1-7 (line 356) and section 3.4 (2026-10-09 ps
observation); backend config AGENT_SYSTEM_DSN.
Why: adjust_args_for_bin strips the leading space of its return while the
rebuilt args keep it, so every rebuild carrying --dsn/--auth compared
unequal and warned that the legacy binary had the flags dropped even when
nothing was dropped — misleading during incident triage.
Evidence: bash -n clean; against the real dev binary the normalized
comparison reports no drop and the flags survive intact; make test green.
Impact: warning now fires only when flags are actually filtered; no
behavioral change to start/deploy.
Refs: PR #188
Why: the 2026-10-05 dev outage — a restart with an explicit --addr rebuilt
the start args, and the rebuild branch dropped the persisted --dsn for the
dev env, so the binary resolved auth=auto to off on 0.0.0.0 and the new
listen guard refused to spawn; record_state then persisted the broken exec=
before the health probe, so bare starts kept failing.
Evidence: bash -n clean; sandbox registry with stub binaries — dbref DSN is
re-derived on rebuild (priority CLI > env > dbref), the pre-flight blocks
non-loopback without auth with actionable remedies, immediate-death starts
leave the previous exec= intact, and DSN masking covers all start-path log
lines; make test green.
Impact: dev/prod agent starts keep their DB binding across explicit-arg
rebuilds; failed starts no longer corrupt the registry; static/pg paths get
the same persist-after-probe ordering (pg already had it); no change to
deploy materialization or the binary guard semantics.
Refs: backend 8eda35f (listen guard), runtime/dev history.jsonl 01:23 fail
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 描述）
Why:
The service manager could create and run postgres instances but had no
way to retarget a port explicitly, back data up, clone an instance to
another port, or move a database between instances — the user asked for
exactly these operations.
Evidence:
- "set <name> [--port N] [--host H] [--apply] [--tag T...]": explicit
registration change; running postgres requires --apply (stop → rewrite
registration → start); port availability checked against both
registrations and live listeners. Verified: 8890→8895 with data intact
and DSN updated, old port freed; refusal without --apply.
- "db backup <name> [--db X] [--out F]": pg_dump -Fc into
runtime/<name>/backups/ (0600) with pg_restore --list self-check;
"db backups" lists them.
- "db restore <name> --file F [--db X] [--force]": restores into a new db
or refuses on a non-empty target unless --force (drop with FORCE +
recreate + restore), reporting table counts afterwards. Verified all
three paths.
- "db clone <src> <dst> [--port P] [--password PW] [--tag] [--online]":
default physical clone (brief source stop, cp -a of pgdata minus
postmaster files, new registration, source restarted on its own port);
--online copies via dump/restore without stopping the source (verified
source pid unchanged). Clone lands on the requested or derived port.
- "db copy <src> <dst> [--db X] [--force]": single-database logical move
between two running instances with the same non-empty-target guard.
"db ls <name>" lists databases.
- Fixed during verification: clone/copy leaked the CLI --port into the
source restart path (source briefly came up on the clone's port); the
address overrides are now cleared inside those commands.
Impact:
All operations stay inside runtime/<name>/, append to history.jsonl, and
reuse the existing safety constraints (own-process stop, port conflicts
reported not seized, secrets in 0600 files). Overwriting a non-empty
database requires an explicit --force everywhere. Makefile help line
mentions the new db subcommands.
Refs: .task/feature-svc-db-ops.md（任务卡=PR 描述）
Why:
svc.sh only managed agent-system environments; databases, standalone
frontend serving, per-service tags and reusable start configs were out of
scope, and the user asked for a unified service lifecycle on this host.
Evidence:
- Service model v2: kind=agent|static|postgres registered in
runtime/<name>/svc.env (dotenv, mode 600); legacy entries without kind=
are adopted as agent.
- postgres: "db create <name> --port/--user/--password/--db/--auth-mode/
--tag" runs initdb (scram-sha-256, pwfile 0600), start/stop/restart use
pg_ctl (-m fast, never SIGKILL on postmaster) with pg_isready checks and
first-start database creation; "db dsn <name> [--reveal]" prints a
composable DSN (password masked by default). Verified end to end against
a real postgresql@18 instance: data survives restart, wrong passwords
rejected, stop/restart clean.
- static: "deploy --kind static --from dev[@sha]|local" builds frontend
dist into htdocs/ in an isolated worktree, or "--dir PATH" serves an
existing directory; verified serving HTTP 200, restart, stop, dry-run
plan, and explicit rejection of release sources.
- agent: unchanged three deploy sources plus --tag; bare start/restart now
reuses the persisted exec= from svc.env (verified: same custom port and
args across restart); old binaries lacking --dsn/--auth get those flags
auto-omitted with a warning.
- "list|status [--tag]" shows NAME/KIND/STATE/PID/ADDR/SOURCE/TAGS for all
registered services; "<name> status" gives per-kind detail; "rm <name>
[--purge]" unregisters (and optionally deletes) only runtime/<name>/.
- Fixed during verification: psql arg mangling (-c -c), tags lost because
record_state read svc.env inside its own redirect block, postgres
--version field parsing, unbound vars for unregistered names.
Impact:
Same invariants as before: writes stay under runtime/<name>/ and
runtime/.worktrees/ (only --from local also writes main-checkout build
outputs, all gitignored), stops only own pidfile+cmdline-verified
processes, port conflicts reported not seized. Prompt output moved to
stderr so stdout (tables, DSNs) stays pipeable. Makefile gains svc-list.
Refs: .task/feature-svc-services-registry.md（任务卡=PR 描述）
Why:
svc.sh only knew two hardcoded environments (dev/prod) and always built
the current workspace, so there was no way to deploy a specific Dev- repo
commit or a Releases artifact, and no record of what was actually started.
Evidence:
- scripts/svc.sh commits dev|release lists deployable commits (release
entries annotated with version + devCommit; both mark HEAD and the
environments already running them).
- deploy --from local|dev@<sha>|release@<version|sha> materializes the
chosen source: dev commits build in an isolated worktree
(runtime/.worktrees/<sha>, submodule pins verified to land exactly),
release artifacts are sha256-verified against versions/<v>/manifest.json
(a forged manifest is refused); --pick offers an interactive numbered
choice and --dry-run prints the plan.
- Environment names are generalized (^[a-z][a-z0-9-]{0,15}$, derived port
8800-9099 on collision-free scan); each env is self-contained under
runtime/<env>/{bin,plugins,data} with svc.env (current state) and
history.jsonl (append-only deploy/start/stop events). status scans all
registered envs and history [env] [N] merges the event stream.
- Old artifacts that predate --dsn/--auth have those flags auto-omitted
(probed via serve usage); legacy svc.env files still render in status.
- Verified end to end in the task worktree: stub-binary lifecycle, a real
release@0.1.0 deploy (HTTP 200, source shown in status, commits marked),
failure paths (sha mismatch, immediate exit, non-TTY --pick).
Impact:
scripts/svc.sh users gain multi-version side-by-side environments and
rollback by redeploying an older source; existing dev/prod defaults and
safety constraints (own-pidfile-only stop, port-occupancy check) are
unchanged. Environments deployed by the previous script need one fresh
deploy before start/restart works again. Makefile gains svc-commits and
svc-history targets.
Refs: .task/feature-svc-deploy-source-registry.md（任务卡=PR 描述）
Why: per-environment bring-up needs a persistent file for the SVC_*
knobs (model keys, addresses, tavily pool) instead of relying on shell
history or the single global .svc.env; CLI flags must still win for
one-off overrides like a different port.
Evidence: live matrix - .env.dev parsed (comments, paired quotes,
export prefix) with its address and model values applied and seeded;
--port 8831 overrode the file's port while keeping its 0.0.0.0 host;
missing file fails fast; .svc.env and --env layer correctly (overlap
keys resolve to --env, disjoint keys merge).
Impact: --env FILE / --env=FILE anywhere on the command line; dotenv
parsed safely line-by-line (valid identifiers only, never sourced);
precedence CLI > --env file > .svc.env > OS env > defaults; help and
make svc ARGS examples updated.
Refs: feature/svc-envfile task card.
Why: a freshly deployed environment boots with an empty settings store,
so the first run dies with "main model unconfigured" and the user has
to open the settings UI before anything works - the opposite of
one-command bring-up.
Evidence: live matrix - full seed (chat+lightweight+tavily) lands in
the settings store (API view shows baseUrl/model with the key masked),
restart without flags does not re-seed and the settings persist,
.svc.env sourcing seeds a fresh environment from the one-time config
file, and a no-flag start stays silent. Also wrapped a /proc read race
in pid_alive that printed tr noise during stop.
Impact: --model-base/--model-key/--model-name, --light-base/-key/
-name, --tavily-keys on start/deploy (idempotent, only provided
fields); SVC_MODEL_*/SVC_LIGHT_*/SVC_TAVILY_KEYS env vars; <repo>/
.svc.env one-time config file (gitignored) makes every future deploy
self-configuring; auth-protected instances fall back to a clear hint.
Refs: feature/svc-auto-seed task card.
Why: the manager only took configuration from SVC_* environment
variables; binding a public interface or pointing at a database meant
exporting vars first, which is awkward for one-off deploys and
invisible in shell history review.
Evidence: live matrix on the worktree - --port (8801), --host 0.0.0.0
(bind verified via ss, health probe auto-maps to 127.0.0.1), --addr
whole-form, CLI-over-env precedence (--port beats SVC_DEV_ADDR),
--mock reaching the server cmdline, --dsn passthrough proven by the
postgres connect attempt in the log, -- passthrough (--artifacts), and
make svc ARGS passthrough. A set -e silent-exit trap in env_config was
caught by the first run and fixed (condition-as-last-statement).
Impact: scripts/svc.sh <env> [action] [--addr|--host|--port|--data|
--dsn|--auth|--mock|--plugins| -- <extra>]; precedence CLI > env vars >
defaults; help rewritten with examples; make svc gains ARGS; logs keeps
the positional line-count form. The real-world port guard held: a dev
instance started from the main checkout was refused with owner info,
untouched.
Refs: feature/svc-cli-args task card.
Why: deploying a new build meant manually finding and killing the old
process, rebuilding and re-launching with the right flags; dev and prod
instances could collide on ports, data dirs or kill each other.
Evidence: live matrix on the worktree - dev deploy (stop -> make build
-> start with health check), redeploy swaps the pid and keeps seeded
data, prod deploys alongside dev on separate port/data with fully
isolated /api/projects, port takeover is refused with the owning
process named while the running env stays up, stop clears pidfile and
frees the port. A pid-capture bug (compound-background subshell wrote
the wrapper pid instead of the server) was caught and fixed during the
first live run.
Impact: scripts/svc.sh <dev|prod> [deploy|stop|start|restart|status|
logs]; runtime/<env>/{data,svc.pid,svc.log,svc.env} isolation; defaults
dev 127.0.0.1:8788 / prod 127.0.0.1:8787 overridable via SVC_* env
vars (incl. SVC_PROD_DSN for the PG tier); make svc ENV=... shortcut;
runtime/ gitignored. Safety: only processes started by the script are
stopped (pidfile + /proc cmdline double check).
Refs: feature/svc-env-script task card.
weichen
