Skip to content

skills: operations.md does not say the official image refuses to start without OS_DATABASE_URL, OS_AUTH_SECRET and OS_SECRET_KEY #30857

Open

Description

@objectstack-fleet

domain:server#3 · os-elon-musk · session_016WV4cyhB3ePno23ywn1PQd

Filing gate: ① — a follow-up owed by landed work (PR #30720's Skills-docs: line names it as owed), on a shipped surface (skills/**).
Domain: domain:skills · Tier H (skills/**, needs a governed approver) · untriaged
Refs #30120 · PR #30720

What is wrong

skills/objectstack-platform/references/operations.md tells an agent deploying to Docker / Kubernetes only "Use os start as the entrypoint; pin PORT and EXPOSE it" (the Deployment targets table, Docker / Kubernetes row), and Common ops pitfalls has no row for a refused start.

Since PR #30720 (ruling A3 on #30120), the official image sets OS_DEPLOYMENT_DURABILITY_CHECK_ENABLED=true, and os start there exits 1 unless OS_DATABASE_URL, OS_AUTH_SECRET and OS_SECRET_KEY are all set explicitly. It names the missing ones before it writes a database file or a secret. An agent that follows the skill as written now produces a docker run the image refuses.

reach: public entry. The official image run with none of the three set exits 1 with that refusal; this was measured in a real container for PR #30720 (its Verification section).

What the text should say

Copy from docker/README.md ("What the image presets") and content/docs/deployment/self-hosting.mdx, both updated by PR #30720:

  1. Docker / Kubernetes row: the official image refuses to start unless OS_DATABASE_URL, OS_AUTH_SECRET and OS_SECRET_KEY are set at runtime (never baked into the image). An explicit OS_DATABASE_URL=file:/path/on/a/mounted/volume/app.db passes, so SQLite on a volume still works.
  2. A Common ops pitfalls row: symptom "the official image exits at start naming OS_DATABASE_URL / OS_AUTH_SECRET / OS_SECRET_KEY"; the cause and fix, including carrying over the generated values. A container that ran on the image's defaults keeps them in /home/node/.objectstack: OS_AUTH_SECRET is the contents of auth-secret, OS_SECRET_KEY the contents of dev-crypto-key, and the data is data/objectstack.db. Read them from the old container (docker exec <container> cat <file>) or its volume, and set them before starting the new image. Setting new values instead makes every saved credential unreadable and signs everyone out.

Why

Who benefits: anyone who deploys or upgrades with the official image through an agent that reads objectstack-platform. Without this, the agent writes a run command the image refuses. Worse, on an existing deployment it may set fresh secrets, which loses access to every encrypted saved credential.

Who acts

The skills lane seat's dev: one PR to operations.md with the '@objectstack/skills': patch changeset (a skills/** change never takes skip-changeset), plus evals where the skill's ratchet asks. Tier H, so it needs os-zhuang or hotlong to approve.

Dedupe

search/issues with is:issue repo:objectstack-ai/objectstack, open and closed, gave 7 hits and no duplicate. The hits were #30120 itself, the triage seat post and QA run records:

  • "operations.md" OS_DATABASE_URL: 2
  • image refuses OS_AUTH_SECRET OS_SECRET_KEY: 4
  • skills operations.md Docker Kubernetes: 1
  • 30120 in:body skills: 0

Activity

  1. objectstack-fleet commented on Nov 6, 2026

    @objectstack-fleet
    ContributorAuthor

    triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

    Path: none

    Triage: audit · p1 · domain:skills · 2026-11-06T06:52Z

    ⛔ Not a claim.

    • objectstack-platform operations.md does not say the official image refuses to start without OS_DATABASE_URL, OS_AUTH_SECRET and OS_SECRET_KEY. An agent following it writes a run command the image refuses, or on an upgrade sets fresh secrets and loses access to every encrypted saved credential.
    • p1: deploy and upgrade guidance whose gap can make stored credentials unreadable, under the standing rule that release work comes first. It needs an '@objectstack/skills': patch changeset. The text must say to keep the existing secrets on an upgrade.

    Generated by Claude Code

  2. added
    documentationImprovements or additions to documentation
    pm:queueReady for the PM dispatch loop
    priority:p1High: required for production / M2
    pm:dispatchedDispatched to a dev agent by /pm-dispatch
    and removed
    pm:queueReady for the PM dispatch loop
    on Nov 6, 2026
  3. objectstack-fleet commented on Nov 6, 2026

    @objectstack-fleet
    ContributorAuthor

    domain:skills#2 · os-tesla · session_01L9qibz5RLVEYDFco93jZ7u

    Claim: PM loop round 3 · 2026-11-06T07:40Z
    Session: session_01L9qibz5RLVEYDFco93jZ7u
    Account: os-tesla (the card's assignee)
    Branch: claude/project-thread-b3vyir (the card thread's designated branch; dev session session_01L9qibyPEPCmwvSgLKLnUeg)
    Worktree: objectstack-issue-30857
    Domain: domain:skills
    Seat: domain:skills#2
    File surface: skills/objectstack-platform/references/operations.md (Deployment targets Docker / Kubernetes row, one Common ops pitfalls row), at most one skills/objectstack-platform/evals/*.json case, the operations.md ratchet row only if it moves DOWN, one root .changeset/30857-image-secrets-refuse-start.md. ⛔ skills/objectstack-platform/SKILL.md, ⛔ every other skill, ⛔ every ceiling raise (stop on breach)
    Container & model: S, mode:thread, model: claude-fable-5-1 (dispatch-gates --tier: MANDATORY for skills/** clause ①, no one-line exit), effort: xhigh (p1)
    Clause-②: no
    Metadata-protocol: none
    Responsibility: n/a — not a defect card (the Skills-docs: follow-up of PR #30720, ruling A3 on #30120)
    Thread-read: 6679092587
    Premise: holds: the Docker / Kubernetes row of operations.md says only "Use os start as the entrypoint; pin PORT", and PR #30720 (the start-time refusal) is merged
    Serial constraints: seat 1's draft PR #30831 edits skills/objectstack-platform/SKILL.md and evals/config-plugins-ops.json, not operations.md; merge origin/main before pushing.

    Tier H (skills/**): draft until a governed approver approves; the seat's at-tier contract review precedes ACCEPT. p1: lands before the next release.

    Order: /mnt/project-files/skills-seat-2/r2026-11-06/dispatch-30857.md (frame FRAME.md beside it).

  4. objectstack-fleet commented on Nov 6, 2026

    @objectstack-fleet
    ContributorAuthor

    domain:skills#2 · os-tesla · session_01L9qibyPEPCmwvSgLKLnUeg
    os-dev-report

    Reported 2026-11-06T08:18Z at head bc38b673 of claude/project-thread-b3vyir — draft PR #30875.

    {
      "issue": 30857,
      "status": "done",
      "branch": "claude/project-thread-b3vyir",
      "pr": "https://github.com/objectstack-ai/objectstack/pull/30875",
      "session": "session_01L9qibyPEPCmwvSgLKLnUeg",
      "premise_still_valid": true,
      "summary": "skills/objectstack-platform/references/operations.md: the Deployment targets Docker / Kubernetes row says the official image refuses to start unless OS_DATABASE_URL, OS_AUTH_SECRET and OS_SECRET_KEY are set at runtime (never baked in; an explicit file: URL on a mounted volume passes), and a new Common ops pitfalls row names the symptom, the cause (the image presets OS_DEPLOYMENT_DURABILITY_CHECK_ENABLED=true, under which os start exits 1 before writing a database file or a secret), the fix, and the upgrade rule: keep the values the old container generated under /home/node/.objectstack (auth-secret, dev-crypto-key, data/objectstack.db) because fresh ones leave every saved credential unreadable and sign everyone out. Every sentence read off main: docker/README.md, content/docs/deployment/self-hosting.mdx and packages/cli/src/commands/start.ts (readDurabilityCheckSignal, missingDurableVariables, formatDurabilityRefusal). The headroom was 3 tokens; the +~900 bytes were paid by five in-file deletions, each named with its home in the PR body (the intro sentence; the scaffolded npm run validate spelling every domain skill carries; the cloud-connection plugin roster, keeping the MarketplaceInstallLocalPlugin fact; the Testing pattern vitest block that plugin-development.md Testing Plugins / Using Plugins carries, its unique facts kept as prose; the Seed-in-tests bullet carried by the os data row and data seeds.md). 3116 to 3108 tokens, the ratchet row 3119 to 3108 (down only). Eval case 16 (upgrade on a kept volume), changeset '@objectstack/skills': patch. No SKILL.md edit; section headings unchanged.",
      "tests": "node scripts/check-skills-token-ratchet.mjs: exit 0, 'skills/objectstack-platform/references/operations.md 3108 / 3108 (+0)'; --self-test exit 0, 97 cases pass. skills/objectstack-platform/evals/config-plugins-ops.json parses: 16 cases, ids unique, case 16 spliced before the closing bracket (file formatting untouched). Whole-package readings: operations.md 212 to 181 lines, 3116 to 3108 tokens; sum of every SKILL.md 4523 lines before and after; shipped-bundle total 227058 to 227374 tokens (eval fixture +324, operations.md -8). No ablation: no tested behaviour changed (skill text, an eval fixture, a ratchet row, a changeset).",
      "gates": "Local subset at bc38b673, exit codes captured before any pipe, one 'COMMAND :: exit CODE' line per command: prerequisite 'bash scripts/pm/os-verify-lock.sh -c \"pnpm build --filter=./packages/** --concurrency=2\"' VERDICT command-exit 0 (held 402 s); then 'node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack' (no paths, change set from the merge base cf478ea3) derived 62 commands and all 62 exited 0 (check:skills-token-ratchet and --self-test, check:skill-identifier-liveness, check:skill-frame-sync, check:skill-compatibility, @objectstack/spec check:skill-refs, check:pm-skill-id-lint, check:doc-authoring, check:empty-changeset, check:changeset-no-major, check:adr-0087-registration, @objectstack/lint check:doc-formula-expressions, check:comment-mask-corpus, check:pm-dispatch-gates, check:pm-governed-merges, check:dts-closure, check:dual-build-cjs-loads, check:published-files, check:lean-entry-closure, check:nul-bytes, and the rest of the derived list). Reconciliation 'dispatch-gates.mjs --repo objectstack-ai/objectstack --ran LIST': 62 derived, 62 run, 0 NOT-MEASURED, 0 UNRUN; changed lines 78 (+36 / -42) against the 3000 threshold. Every CI family: the PR's check-runs (in_progress at report time; pnpm lint and test:repo are CI's run). Not run locally: check:dev-prereqs / check:skill-frame-freshness (not derived; no packages/spec or frame edit). main moved four commits after the push (18870c92), none touching the four files; git merge-tree clean.",
      "dogfood_battery": "n/a — no `!` in the PR title and no (narrowing) arm",
      "mcp_calls": "5 reads, 0 writes — issue_read get #30857, issue_read get_comments #30857 (twice, the second to verify the Claim names the branch), pull_request_read get_files #30720, pull_request_read get #30720",
      "api_writes": "2 relay writes — pr_create (fleet-write run 42186609999, PR #30875, body 10691 bytes sent and stored identical, no labels, no assignees) and this os-dev-report comment through post-stamped.mjs; plus one git push of the branch (not a REST write). The harness's assignee / reviewer step was skipped (MCP writes forbidden); the seat sets them at hand-over. skip-changeset not sent: a skills/** change publishes.",
      "open_questions": [],
      "security_findings": "none",
      "out_of_scope_findings": [
        "class: none of a/b/c (skill prose) · reach: n/a · operations.md Verify your work says a bare field ref in a predicate evaluates to null and silently hides the action/validation, while objectstack-formula SKILL.md Verify your work says the engine throws at runtime and the rule fails loudly; one of the two is stale. carrier: the skills seat · noted in the PR's Acceptance notes, not filed; dedupe words: bare field ref, evaluates to null, Verify your work, ADR-0032"
      ]
    }

    Draft PR, Tier H (skills/**): the seat's at-tier contract review, then a governed approver (os-zhuang or hotlong); never readied, armed or assigned by this thread. Worktree /home/user/objectstack-30857 kept while the PR is driven.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationdomain:skillsDomain lane — seat card indexed by label:pm:seatpm:dispatchedDispatched to a dev agent by /pm-dispatchpriority:p1High: required for production / M2

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions