dsh 0.2.0-rc.2: in-container update (experimental channel), path-agnostic compose, upstream patches adapted to 0.1.x/0.2.x
This commit is contained in:
hermes committed
commit
e6dcef9bf5
302 files changed
+75178
No files matched your search
@@ -0,0 +1,31 @@
|
||||
---
|
||||
name: dsh-docker-operations
|
||||
description: Use for operating inside the official DSH Docker Environment, including files, development tools, plugins, skills, lifecycle, logs, updates, recovery, networking, permissions, and container-specific diagnostics.
|
||||
user-invocable: true
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# DSH Docker Operations
|
||||
|
||||
Use the platform's supported interfaces before inspecting implementation details. Match the user's language in every response; these instructions being English does not change the response language.
|
||||
|
||||
## Operating rules
|
||||
|
||||
1. Preserve the user's requested scope and authorization. Read-only diagnosis does not authorize updates, restarts, plugin mutations, or destructive file operations.
|
||||
2. Start with `dsh`, `dsh-platform`, their help output, and the DSH Management Console. Do not rediscover public behavior by reading Stage-0, Bootstrap, sockets, process environments, or runtime source.
|
||||
3. In routine work, never override `HOME`, `USER`, `LOGNAME`, XDG variables, npm configuration, pnpm configuration, or package-manager cache paths. The container already provides the correct `node` environment.
|
||||
4. Do not read credentials from process environments, files, command histories, or service internals. Never print secrets.
|
||||
5. Do not mutate platform state, Store assets, runtime views, keyrings, receipts, or Unix sockets. Use only the documented recovery commands for exceptional operations.
|
||||
6. Inspect `/opt/dsh-platform` or `/run/dsh-platform` internals only when the user explicitly asks to develop or debug the platform implementation itself. Ordinary DSH, plugin, update, and container troubleshooting does not meet that condition.
|
||||
|
||||
## Load the relevant guide
|
||||
|
||||
- Environment identity, paths, persistence, Root, and sudo: [references/environment-and-permissions.md](references/environment-and-permissions.md)
|
||||
- Workspaces, files, development tools, and package managers: [references/files-and-development.md](references/files-and-development.md)
|
||||
- DSH CLI, profiles, user plugins, System Plugins, and skills: [references/dsh-and-extensions.md](references/dsh-and-extensions.md)
|
||||
- Status, health, logs, restart, and Management Console: [references/lifecycle-and-logs.md](references/lifecycle-and-logs.md)
|
||||
- Stable/experimental updates, rollback, reset, and recovery: [references/updates-and-recovery.md](references/updates-and-recovery.md)
|
||||
- Gateway, ports, reverse proxies, authentication, and remote access: [references/networking-and-auth.md](references/networking-and-auth.md)
|
||||
- Ordered troubleshooting and protected implementation boundaries: [references/diagnostics-and-boundaries.md](references/diagnostics-and-boundaries.md)
|
||||
|
||||
Read only the references needed for the current task. When a referenced command differs from the installed version, prefer that command's current `--help` output and report the difference.
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
# Diagnostics and protected boundaries
|
||||
|
||||
## Ordered diagnosis
|
||||
|
||||
Use the least invasive source of truth that can answer the question:
|
||||
|
||||
1. Run the relevant public command's `--help` when syntax is uncertain.
|
||||
2. Inspect `dsh-platform status` and the current operation/task state.
|
||||
3. Read focused structured logs through `dsh-platform logs` or a management UI.
|
||||
4. Check DSH/Profile state with the public `dsh` CLI.
|
||||
5. Use the standalone Management Console for recovery actions, Root file inspection, or a terminal explicitly requested by the user.
|
||||
6. Inspect platform implementation files only when the user explicitly asks to debug or develop dsh-docker itself.
|
||||
|
||||
For a restart failure immediately after plugin removal, first look for `cannot resolve profile bundle` in the structured DSH Runtime logs. A current managed startup repairs legacy orphaned Bundle references automatically; verify the subsequent lifecycle terminal state before escalating. Do not bypass that repair by editing the Web Profile manifest or lockfile directly.
|
||||
|
||||
For a browser plugin-load failure around a restart, correlate the current `dshLifecycle` task with `browser.plugin-load.failed` and the matching recovery event. Apply this diagnosis equally to official DSH plugins, bundled System Plugins, and User Plugins. `browser.plugin-load.recovery.completed` identifies a recovered transition race. Recovery attempt three opens Gateway's terminal plugin-failure page and records `browser.plugin-load.recovery.failed`; a failure without recovery eligibility is also persistent. Diagnose either case from the named plugin and DSH Runtime logs. Do not create a reload loop, match visible page text, or assume every plugin-load failure is transient.
|
||||
|
||||
For an update check failure, distinguish the remote request from the cached target: a later failed check must retain the last verified Stable or upstream result and report `remote check failed`; only a first failed check has no verified result to show. Check the public update status and the structured `update.check.failed` event before changing proxy settings. When an external proxy is configured, use the Proxy tab's asynchronous test and its task result; never read `/data/platform/state/proxy`, inspect the Outbound Proxy environment, or call its control socket directly. A proxy test failure must not replace the active configuration.
|
||||
|
||||
Stop once the cause is established. Do not enumerate Seed trees, runtime packages, sockets, process environments, or supervisor source as a substitute for trying the public operation.
|
||||
|
||||
## Protected trust boundary
|
||||
|
||||
Stage-0 is the only writer and verifier for Recovery-signed keyrings, Release signatures, monotonic ledgers, trusted objects, and receipts. Bootstrap, Updater, DSH, plugins, and agents consume its verified results.
|
||||
|
||||
Never:
|
||||
|
||||
- edit or replace the Recovery Root public key;
|
||||
- add a Release key or modify keyring state;
|
||||
- call the Stage-0 Trust socket directly;
|
||||
- import an object by supplying an arbitrary expected hash;
|
||||
- forge, copy, reactivate, or rewrite a receipt;
|
||||
- lower keyring generation or target sequence;
|
||||
- mutate current/previous deployment or Bootstrap slots by hand.
|
||||
|
||||
Use `dsh-platform trust status` for read-only trust diagnostics. Trust reset is a last-resort Root TTY operation, not a Web/API repair method.
|
||||
|
||||
## Failure reporting
|
||||
|
||||
Distinguish among DSH startup, update/restart, automatic rollback, startup failure, prolonged unavailability, Gateway authorization, and an unclassified proxy error. Capture the public status plus complete relevant structured error. Do not label a warning or ordinary stderr line as a failure without its structured level/result, and do not report an operation as successful until its terminal state and postcondition are verified.
|
||||
|
||||
Repeated authentication, 2FA, Management-origin probe, and upstream failures are rate-limited by failure class. Treat `suppressedCount` on the next retained event as part of the incident total; do not infer the attempt count from the number of visible warning rows alone.
|
||||
|
||||
Browser-session activity is reported at most once per session every five minutes. Use `access.session.expired` and `access.session.invalidated` reason codes to distinguish absolute or idle expiry, credential or Management-entry changes, and source DSH-session loss. Root authentication recovery is duplicated to the audit stream with only the operation, result, and session-revocation counts; credential values, reset keys, one-time codes, Cookies, and CSRF tokens must never appear.
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
# DSH, profiles, plugins, and skills
|
||||
|
||||
## DSH CLI
|
||||
|
||||
Use the `dsh` shim. It dynamically executes the current verified Runtime and remains correct across updates and rollbacks. Consult `dsh --help` and the relevant subcommand help instead of calling files below `/run/dsh-platform/views/runtime`.
|
||||
|
||||
The Web Profile is stored below `$DSH_HOME/profiles/web`. Treat its package manifest, lockfile, and bundle declarations as a coordinated profile owned by the DSH CLI; do not hand-edit them for ordinary plugin operations.
|
||||
|
||||
## User plugins
|
||||
|
||||
Install a published user plugin with:
|
||||
|
||||
```sh
|
||||
dsh plugin --profile web add <package-or-supported-spec>
|
||||
```
|
||||
|
||||
Remove it with:
|
||||
|
||||
```sh
|
||||
dsh plugin --profile web remove <package-name>
|
||||
```
|
||||
|
||||
Run these commands with the inherited `node` environment. The public container `dsh` shim also drops a Root caller to the managed `node` identity, but that protection is not a reason to invoke profile-internal pnpm commands as Root. Do not redirect pnpm configuration or caches. Prefer the package declared by the plugin project; clone/build source only when the user explicitly requests source installation or no published package exists.
|
||||
|
||||
The platform pins the Web Profile store below `$DSH_HOME/.pnpm-store` and transactionally migrates a legacy Profile whose pnpm metadata points at an older workspace or home. If a package operation reports `ERR_PNPM_UNEXPECTED_STORE`, restart DSH once through the public lifecycle command and inspect the DSH Runtime log for the migration result. Do not delete `$DSH_HOME`, edit `node_modules/.modules.yaml`, or create/chmod the old store path to suppress the check.
|
||||
|
||||
Some plugin changes require DSH to restart. Use:
|
||||
|
||||
```sh
|
||||
dsh-platform restart
|
||||
```
|
||||
|
||||
When this command is run by an Agent inside a DSH session, submit the asynchronous task and report its task ID. Do not add `--wait`: stopping the current DSH process interrupts the tool transport before a durable result can be returned. Use `--wait` only from an external operator terminal, the standalone Management Console terminal, or external automation.
|
||||
|
||||
The standalone Management Console can disable or uninstall a faulty Web Profile Bundle while DSH is down. It deliberately manages only DSH bundle plugins, not arbitrary dependencies or hand-written Cordis patch entries. After Apply reports that the Profile change was saved, treat that mutation as committed even if DSH remains unavailable or its restart fails; inspect lifecycle logs and correct another faulty plugin or retry startup instead of repeating the saved action.
|
||||
|
||||
If a plugin tool reports a successful removal but DSH then fails with `cannot resolve profile bundle`, inspect public DSH Runtime logs and restart once through `dsh-platform restart`. An authorized Web startup atomically removes only an orphaned Bundle which is no longer a declared dependency and cannot be resolved from the Profile or DSH installation. Do not hand-edit `package.json`, the lockfile, or `dsh.profile.bundles`; if the managed repair does not restore readiness, use User Plugin recovery in the standalone Management Console.
|
||||
|
||||
## System Plugins
|
||||
|
||||
System Plugins are signed resources supplied by the current DSH Docker Environment. Manage them through **System Plugins** in Platform Management or the standalone Management Console. The standalone console remains usable while DSH is down. Its selections are drafts until Apply; once Apply saves a selection, the change remains committed for the next DSH start even if DSH is already unavailable or the activation restart fails. Diagnose that lifecycle failure separately instead of treating the saved plugin action as unapplied. Do not install, delete, or impersonate `@dsh-docker/*` packages through the normal user-plugin CLI.
|
||||
|
||||
## Skills
|
||||
|
||||
User and project skills belong to the official DSH roots such as `$DSH_HOME/skills`, `.dsh/skills`, or `.agents/skills`. System Skills are signed platform resources and are managed through **System Skills** in the two management interfaces.
|
||||
|
||||
Installing, uninstalling, enabling, or disabling a System Skill hot-refreshes the DSH skill catalog. It does not require a DSH restart, and the standalone Management Console can still apply the selection while DSH is unavailable. User Skill changes in that console are likewise independent of DSH lifecycle state. A project or user skill with the same name may override the bundled System Skill according to DSH's native precedence; platform management does not alter or remove that override.
|
||||
+35
@@ -0,0 +1,35 @@
|
||||
# Environment and permissions
|
||||
|
||||
## Process identity
|
||||
|
||||
DSH and its Agent normally run as `node` with:
|
||||
|
||||
- `HOME=/home/node`
|
||||
- `USER=node`
|
||||
- `LOGNAME=node`
|
||||
- XDG configuration, data, and cache below `/home/node`
|
||||
- `DSH_HOME`, normally `/data/dsh`
|
||||
- the configured default workspace, normally `/workspace`
|
||||
|
||||
Do not replace these values to work around a package-manager error. First inspect ownership of the target profile or workspace and use the existing environment. A reference to `/root/.config`, `/root/.cache`, or `/root/.local` from a normal DSH/plugin operation is a defect or inherited override, not a directory to create or chmod around.
|
||||
|
||||
The standalone Management Console terminal and file manager run through the platform's Root maintenance broker. Its terminal intentionally uses UID 0 and `HOME=/root`. Do not generalize that identity to DSH or Agent commands.
|
||||
|
||||
## Persistent and ephemeral paths
|
||||
|
||||
- `$DSH_HOME` (`/data/dsh` by default): user configuration, profiles, sessions, user plugins, and DSH data.
|
||||
- `$DSH_PLATFORM_DATA` (`/data/platform` by default): platform state, trusted/managed assets, cache, snapshots, and logs.
|
||||
- `$DSH_DEFAULT_WORKSPACE` (`/workspace` by default): initial user workspace; it is not a sandbox.
|
||||
- `/run/dsh-platform`: ephemeral runtime views and local sockets rebuilt at container start.
|
||||
- `/opt/dsh-platform`: immutable image implementation and Seed.
|
||||
- `/home/node`: normal user home and package-manager/XDG state.
|
||||
|
||||
Use the configured environment variables instead of hard-coding their default paths when writing scripts intended to survive custom deployments.
|
||||
|
||||
## Root and sudo
|
||||
|
||||
When `DSH_SUDO_ENABLED=true`, the DSH/Agent process can use passwordless `sudo` for commands that genuinely need operating-system authority. Use it narrowly for system package installation or protected host-mounted files. Keep ordinary workspace, DSH profile, npm, and pnpm operations as `node` so new files remain usable by DSH.
|
||||
|
||||
When sudo is disabled, do not assume a failing command may be rerun as Root. Explain the required permission or use the authenticated Management Console when the user explicitly asks for container maintenance.
|
||||
|
||||
Never combine broad Root operations with guessed paths, unresolved variables, recursive deletion, the Docker socket, or unrelated host mounts.
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
# Files and development tools
|
||||
|
||||
## Work in the selected workspace
|
||||
|
||||
Start from `$DSH_DEFAULT_WORKSPACE` when the user has not named a directory. Confirm the current directory before installing dependencies, initializing a repository, or running destructive commands. Preserve existing files and unrelated changes.
|
||||
|
||||
Use ordinary shell and editor tools for accessible workspace and DSH user data. Use the standalone Management Console file manager for browser-based upload/download, archive operations, ownership/mode changes, or Root-only repair. It is available independently of the DSH Runtime.
|
||||
|
||||
Do not edit these managed paths during routine work:
|
||||
|
||||
- `$DSH_PLATFORM_DATA/state`
|
||||
- `$DSH_PLATFORM_DATA/store`
|
||||
- `/run/dsh-platform/views`
|
||||
- `/opt/dsh-platform`
|
||||
|
||||
Cache directories may be cleared only when the user requests it and the exact cache target is known. Never delete `$DSH_HOME` to solve a platform or image upgrade problem.
|
||||
|
||||
## Package managers and toolchains
|
||||
|
||||
Run language package managers from the intended project or DSH profile directory under the inherited environment. Do not set XDG/npm/pnpm variables to the workspace, `/root`, or a temporary directory merely to make one command pass.
|
||||
|
||||
For Node development:
|
||||
|
||||
- use the installed Node/npm/pnpm commands and their project lockfile;
|
||||
- do not use global installs when a project-local dependency or `npx`/`pnpm exec` is appropriate;
|
||||
- keep user caches and configuration under `/home/node` through the inherited environment;
|
||||
- use `sudo` only for explicit operating-system or global-tool installation requested by the user.
|
||||
|
||||
For other development environments, use the same rule: normal user tooling belongs to `/home/node` and the workspace, while system packages may require narrowly scoped sudo. Do not make a tool inherit Root's home just because its installer was invoked through sudo.
|
||||
|
||||
Before downloading or executing a third-party installer, verify the requested source and explain any material external side effect. Prefer the project's documented package manager over cloning and building source unless the user explicitly wants a source installation.
|
||||
+59
@@ -0,0 +1,59 @@
|
||||
# Lifecycle, health, and logs
|
||||
|
||||
## Public status and lifecycle
|
||||
|
||||
Start diagnosis with:
|
||||
|
||||
```sh
|
||||
dsh-platform status
|
||||
```
|
||||
|
||||
Restart only DSH, while keeping Gateway and Management available, with:
|
||||
|
||||
```sh
|
||||
dsh-platform restart
|
||||
```
|
||||
|
||||
For an Agent running inside the current DSH session, `restart` must remain asynchronous: report the returned task ID and let the browser enter the lifecycle holding page. Never run `restart --wait` or `stop --wait` from that session because DSH shutdown interrupts the tool transport. `--wait` is reserved for an external operator terminal, the standalone Management Console terminal, and external automation.
|
||||
|
||||
The standalone Management Console and CLI also expose explicit lifecycle operations:
|
||||
|
||||
```sh
|
||||
dsh-platform start
|
||||
dsh-platform stop
|
||||
dsh-platform restart
|
||||
```
|
||||
|
||||
An explicit stop lasts only for the current container lifetime. An unexpected DSH exit is recovered at most three times; check `dshLifecycle` and `recoveryMode` rather than repeatedly sending restart commands.
|
||||
|
||||
The container admits only the Bootstrap-supervised Web Profile. Do not launch a replacement with `dsh web`: when DSH is stopped that command delegates to the public start operation, and otherwise it reports the managed state without creating a second instance. An unregistered first `SIGTERM` is converted into a public asynchronous restart, but this compatibility behavior is not a reason to signal the process directly.
|
||||
|
||||
Do not send signals to DSH, kill its PID, invoke Bootstrap sockets, or restart the whole container unless the user specifically requested that broader action. During a registered lifecycle operation, browser navigation enters the localized holding page and returns to the original same-origin path only after the DSH HTTP upstream responds and the platform lifecycle has finished starting, restarting, recovering, or switching. This prevents a listening but not yet plugin-ready DSH instance from being shown early. API and WebSocket requests receive `503` until that combined readiness succeeds.
|
||||
|
||||
Do not diagnose these classified holding responses as Gateway outages. An explicit start, stop, restart, switch, or recovery does not emit `gateway.upstream.failed` or `gateway.upstream.recovered`; those records are reserved for an unclassified upstream outage and its recovery.
|
||||
|
||||
Plugin bundle requests are held while a registered lifecycle transition makes DSH temporarily unavailable. The same guard covers official DSH plugins, bundled System Plugins, and User Plugins. A failed bundle request or structured dynamic-import error may enter the holding page twice for the same running Deployment. A third structured failure opens Gateway's terminal plugin-failure page and links to the standalone Management Console; it never starts an unbounded reload loop. Detection uses the plugin request or module error URL, not visible page text. Do not advise repeated manual refreshes before checking lifecycle state, recovery-attempt fields, and browser recovery events in platform logs.
|
||||
|
||||
Docker health probes Gateway control-plane health at `127.0.0.1:3080/_dsh_gateway/health`. It is independent of DSH readiness, so an intentional DSH stop does not make Docker report the container as unhealthy while the standalone Management Console remains available.
|
||||
|
||||
## Logs
|
||||
|
||||
Inside the container, query structured platform logs with:
|
||||
|
||||
```sh
|
||||
dsh-platform logs --limit 500
|
||||
dsh-platform logs --source dsh-runtime --limit 500
|
||||
dsh-platform logs --since <ISO-8601-time> --limit 500
|
||||
```
|
||||
|
||||
The standalone Management Console and Platform Management plugin provide filtering, expansion of complete structured entries, refresh, live following, and JSONL export. From the Docker host, `docker logs <container>` includes platform and DSH output.
|
||||
|
||||
When reporting a failure, include the operation/task ID, source, timestamp, complete error, and the smallest relevant surrounding entries. Do not include credentials, terminal contents, or unrelated user data.
|
||||
|
||||
For a browser plugin-load failure, correlate `browser.plugin-load.failed` with `browser.plugin-load.recovery.started`, `browser.plugin-load.recovery.completed`, or `browser.plugin-load.recovery.failed`. A completed recovery confirms a transient lifecycle race. Attempt three and the terminal Gateway page identify a persistent failure; a failure without recovery eligibility also requires investigation of the named plugin bundle and DSH Runtime logs.
|
||||
|
||||
Logs rotate automatically according to the platform size and retention settings. Clearing the UI display is a local display cutoff and does not delete the persisted platform log files.
|
||||
|
||||
## Management surfaces
|
||||
|
||||
The standalone DSH Management Console is served at `/_dsh_platform/console/` and stays available when DSH is starting, restarting, recovering, or down. Platform Management inside DSH exposes the routine subset appropriate while DSH is available. Prefer the standalone console for recovery, Root terminal/file access, user-plugin recovery, and System Skill reinstallation.
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
# Networking and authentication
|
||||
|
||||
## Ports and proxying
|
||||
|
||||
- Port `3080` is the Gateway and the only normal published service.
|
||||
- Port `3079` is the loopback-only DSH upstream inside the container; do not publish or access it remotely.
|
||||
- The standalone Management Console is below `/_dsh_platform/console/` on the Gateway in compatibility mode. Separate-origin mode uses the container's dedicated Management entry without a DSH upstream.
|
||||
|
||||
For remote access, configure `DSH_TRUSTED_HOSTS` for accepted external Host values, initialize the local administrator in the browser, and terminate HTTPS at a trusted reverse proxy or equivalent network boundary. Never expose port `3080` or the standalone Management Console before authentication: its terminal and file manager operate with Root authority. The reverse proxy must preserve the original `Host` and normal WebSocket upgrade headers. Optional strong isolation publishes the dedicated Management entry without a DSH upstream; for a public separate origin configure its exact public URL, and for a local separate origin configure the host port mapped to the container entry (default `3081`, but the host port is user-selectable). Do not assume either separate entry is exposed unless the operator configured it.
|
||||
|
||||
Do not weaken Host/Origin checks to work around a reverse-proxy error. Diagnose the forwarded Host, scheme, Origin, WebSocket upgrade, and authentication headers first.
|
||||
|
||||
## Managed outbound proxy
|
||||
|
||||
Configure an existing HTTP or SOCKS5 proxy through the **Proxy** tab in the DSH Management Console or Platform Management. Do not edit `/data/platform/state/proxy`, read the Outbound Proxy process environment, or call `/run/dsh-platform/outbound-proxy.sock` directly. Proxy credentials are write-only and must never be recovered from files or logs.
|
||||
|
||||
The UI can route updates, platform components, DSH core/plugins, Agent network operations, the Management container terminal, and model Providers independently. A remote Provider identified through DSH `llm/stream` uses one switch: off selects direct access and on selects its dedicated proxy route. A future Provider that cannot carry stable identity is marked with a read-only **Follow DSH** label; its switch selects direct access when off and the shared DSH policy when on. Local Providers remain direct. Commands launched outside the container are not classified by the platform.
|
||||
|
||||
For Agent-issued `curl`, Git, npm, pnpm, and similar commands, preserve the injected `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, and optional `ALL_PROXY` environment. Do not replace these with the external proxy URL or expose its credentials. Tool support for `ALL_PROXY` varies; inspect the tool's current documentation or behavior before relying on it.
|
||||
|
||||
Use `.example.com`, not `*.example.com`, for a domain suffix. Platform-required loopback rules cannot be removed. If the proxy runs on the Docker host, obtain the current bridge gateway with `ip route`; container `127.0.0.1` is not the host. The host proxy must listen on the bridge address, with appropriate firewall restrictions.
|
||||
|
||||
Use the built-in asynchronous proxy test before saving uncertain settings. A failed test does not replace the active configuration. When diagnosing update checks, distinguish a later remote failure that retains the last verified result from a first check that has never succeeded.
|
||||
|
||||
## Authentication
|
||||
|
||||
Access Manager owns the single local administrator account. A fresh installation stays in an initialization page until the browser sets a username and main password. DSH login creates a DSH Session; the standalone Management Console consumes a one-time handoff and creates a separate Management Session that remains valid only while its source DSH Session is active. Direct Management access always completes the main DSH login first, including on an isolated Management Origin. An optional Management console password is a second layer. DSH logout or session expiry also invalidates linked Management sessions. During a classified DSH outage, top-level navigation may show a generic Gateway recovery page before login so the Management entry remains reachable; it does not grant a session or expose failure details. Do not look for Gateway Basic Auth, `DSH_PROXY_PASSWORD`, `DSH_PLATFORM_PASSWORD`, or a temporary login key: those legacy login paths are removed.
|
||||
|
||||
Browser authentication forms only transport values; the Access Manager performs authentication and credential decisions. Authentication Settings changes the username without a current password, while main-password and Management-console-password changes require the current main password. Resetting or disabling the Management console password does not require the old Management console password and revokes existing Management Sessions.
|
||||
|
||||
After five consecutive failures from one browser source, Access Manager imposes a 30-second retry wait and doubles later waits up to 15 minutes. Each source has fixed limits of 12 failures per hour and 24 per 24 hours; the whole instance has wider flood limits of 20 per minute, 60 per hour, and 120 per 24 hours. Treat `AUTHENTICATION_RETRY_REQUIRED` and `AUTHENTICATION_RATE_LIMITED` as backend decisions; do not retry around them or implement credential admission in the browser.
|
||||
|
||||
These `access` recovery, credential, session, and retry-clear commands require the user's explicit authorization in addition to Root access. Run them only from an interactive container TTY:
|
||||
|
||||
```sh
|
||||
dsh-platform access status
|
||||
dsh-platform access reset
|
||||
dsh-platform access set-username
|
||||
dsh-platform access reset-password
|
||||
dsh-platform access reset-management-password
|
||||
dsh-platform access disable-management-password
|
||||
dsh-platform access clear-retry
|
||||
dsh-platform access clear-retry --global-only
|
||||
dsh-platform access clear-retry --main-password
|
||||
dsh-platform access clear-retry --management-password
|
||||
dsh-platform access clear-retry --two-factor
|
||||
dsh-platform access disable-two-factor
|
||||
dsh-platform access clear-sessions
|
||||
dsh-platform access clear-sessions --management-only
|
||||
dsh-platform access generate-key
|
||||
```
|
||||
|
||||
`access status` is read-only and reports the current account, initialization state, and retry state. The combined `access reset` command atomically applies selected username and main-password changes. When a Management console password is enabled, `y` resets it, the default `n` preserves it, and `d` disables it. When two-factor authentication is enabled, a separate `y/[n]` prompt can disable it. It submits nothing until all prompts complete. Yes/no recovery prompts accept only `y` or `n`, with the default shown in brackets. Other interactive recovery commands include `access set-username`, `access reset-password`, `access reset-management-password`, and `access disable-management-password`. `access clear-retry` uses the same Root/TTY and `y/[n]` boundary; it clears every browser-source wait, every source rolling window, and the instance-wide failure windows without changing credentials or sessions. Add `--global-only` to clear only the instance-wide windows while leaving browser waits and source windows active. The optional `--main-password`, `--management-password`, or `--two-factor` selector limits clearing to one credential class; `--two-factor` clears only its daily limit and leaves the fixed 10-second code backoff active. Fresh empty volumes register without a key. Persisted pre-account deployments and damaged authentication state use `access generate-key`, which issues a single-use authentication reset key valid for ten minutes from the same Root TTY. Never pass passwords as arguments or pipe them to the CLI.
|
||||
|
||||
`--global-only` limits `access clear-retry` to the instance-wide flood windows; without it, both source/browser waits and instance windows are cleared. `access clear-sessions` clears all sessions, or only Management sessions with `--management-only`.
|
||||
|
||||
`access set-username` changes only the administrator name; `access reset-password` changes the main password and revokes all sessions; `access reset-management-password` sets or changes the Management password and revokes Management sessions; `access disable-management-password` and `access disable-two-factor` disable those optional layers without logging out existing sessions. `access generate-key` issues the one-time key used by migration or damaged-account recovery.
|
||||
|
||||
Do not read configured passwords from environment files, `/proc`, process listings, or service memory. Ask the user to authenticate through the normal browser flow.
|
||||
|
||||
The Platform Management and Settings Document Editor System Plugins use the restricted DSH-side platform API and must not require a separate Management Console login. Access is inherited from the authenticated DSH Session and limited by an exact Gateway route allowlist; do not search for a Management session token or invent a separate plugin credential. The restricted API cannot access files, the Root terminal, User Plugin recovery, or authentication settings.
|
||||
|
||||
When the Gateway is behind another proxy, use the public Gateway URL for checks. A direct request with an untrusted Host can correctly return `403`; that is not evidence that DSH itself failed.
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
# Updates, rollback, and recovery
|
||||
|
||||
## Read-only check and activation
|
||||
|
||||
Checking never downloads or activates an update:
|
||||
|
||||
```sh
|
||||
dsh-platform check
|
||||
```
|
||||
|
||||
Inspect `dsh-platform status` after the check. Activate the latest supported target only after the user confirms:
|
||||
|
||||
```sh
|
||||
dsh-platform update
|
||||
```
|
||||
|
||||
For an Agent running inside the current DSH session, activation must remain asynchronous: report the returned task ID and do not use `update --wait`, because switching DSH can interrupt the tool transport. `--wait` is reserved for an external operator terminal, the standalone Management Console terminal, and external automation.
|
||||
|
||||
After submitting an update, use the public `dsh-platform status` result and task-correlated platform logs to report its current phase or terminal outcome. The Management interfaces reconstruct their stage history from this persistent state and JSONL log stream, so a browser refresh does not imply that the operation restarted. Prefer the phase, measurable byte/item/file/service counters, and structured failure details over an estimated elapsed time. Do not inspect updater journals, Deployment slots, or internal sockets to infer progress.
|
||||
|
||||
Use `dsh-platform channel` to inspect the current channel and `dsh-platform channel stable|experimental` only when the user requests a channel change.
|
||||
|
||||
Stable targets update the signed supported DSH and Environment. Before activating a newer upstream DSH, Experimental mode first converges the complete Deployment to the signed Stable target sequence, even if the displayed DSH and Environment versions already match. Do not download npm/GitHub artifacts yourself, submit an expected hash, or call the Trust API; Stage-0 alone authorizes and imports release objects.
|
||||
|
||||
If npm exposes a selected DSH version before every dependency version is available, Runtime materialization automatically retries transient `E404`, `ETARGET`, and `ENOVERSIONS` failures in fresh install roots with bounded backoff. Do not repeatedly restart the update while these retries are active. If the bounded attempts still end in a version Hold, report its sanitized reason, wait until the Registry dependency graph is complete, and use `dsh-platform retry` only with the user's authorization.
|
||||
|
||||
## Rollback and return to stable
|
||||
|
||||
Use `dsh-platform rollback` only when a complete previous state is available and the user explicitly confirms the target and service interruption. Explain any reported snapshot or data boundary before proceeding, then verify status and health after rollback. Experimental return-to-stable can restore an older data snapshot and discard newer DSH data; use the interactive `dsh-platform return-stable` flow and present the data-loss boundary before proceeding.
|
||||
|
||||
The in-DSH Platform Management interface intentionally does not expose rollback or return-to-stable. Direct users who need these recovery actions to the standalone DSH Management Console, where return-to-stable is shown only for an active Experimental Deployment with a verified Stable recovery point.
|
||||
|
||||
Runtime reset rebuilds DSH from verified Pristine content and the current complete patch/plugin set. Use the standalone Management Console for that operation; it does not erase `$DSH_HOME`, sessions, user plugins, or the workspace.
|
||||
|
||||
## Exceptional recovery
|
||||
|
||||
```sh
|
||||
dsh-platform recover
|
||||
dsh-platform trust reset
|
||||
```
|
||||
|
||||
Both commands are Root-only interactive console operations. `recover` restores the image-baseline Deployment after current and previous Deployments are unusable; `trust reset` clears the accepted trust state.
|
||||
|
||||
Never manually delete `$DSH_PLATFORM_DATA/state`, rewrite slots, copy objects into Store, edit keyrings, forge receipts, or reinterpret an image reference. If a legacy or corrupt platform volume prevents startup, preserve `$DSH_HOME` and follow the exact platform error/recovery guidance.
|
||||
Reference in new issue
Block a user