Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(hcc): merge only the exact split-layout signature

Alfredo Lopez639242430ce8
diff --git a/docs/architecture/host-storage-layout.md b/docs/architecture/host-storage-layout.md
index 2a1ec1435..c5aa4c3c6 100644
--- a/docs/architecture/host-storage-layout.md
+++ b/docs/architecture/host-storage-layout.md
@@ -50,22 +50,27 @@ mounted at `/mnt/workspace-root`, and requests of 10m CPU / 32Mi memory
(`host-context-controller/src/statelessDeployment.ts`). It never opens
SQLite.
-**Trigger.** It acts only on the split-layout signature: `state/` is a real
-directory (not a symlink) holding at least one `state.db*` entry. Every other
-tree exits 0 unchanged, including an agent folder named `workspace/` or
-`state/` without a database, and a `state` that is a symlink or not a
-directory. An agent can create those on a stateful Host, so they must not
-stop it from starting. A stateful or desktop tree changes only if it carries
-the signature, which only the earlier init or an agent-created
-`state/state.db*` entry produces.
-
-Two agent-made `state/` folders on a stateful Host do stop it from starting:
-
-- a `state/` holding a `state.db*` entry beside the root database. The
- signature holds and F2 refuses, because the merge cannot tell the agent's
- file from a second database;
-- a `state/` the container uid cannot list and search. F1 refuses before the
- signature check, because the merge cannot tell whether it holds a database.
+**Trigger.** It acts only on the split-layout signature the earlier init
+leaves: `state/` and `workspace/` are both real directories (not symlinks),
+and `state/` holds a file that init writes: `state.db`, `state.db-wal`,
+`state.db-shm` or a `state.db*.pre-<ts>.bak` copy. Every other tree exits 0
+unchanged, including an agent folder named `workspace/` or `state/` alone, a
+`state/` holding other `state.db*` names (`state.db.json`, `state.dbx`), and a
+`state` or `workspace` that is a symlink or not a directory. An agent can
+create those on a stateful Host, so they must not stop it from starting. A
+stateful or desktop tree changes only if it carries the signature, which only
+the earlier init or agent-created `state/` and `workspace/` folders with one
+of those exact names produce.
+
+Two agent-made folder pairs on a stateful Host do stop it from starting:
+
+- a `state/` holding `state.db` or one of its journals beside the root
+ database, next to a `workspace/` folder. The signature holds and F2
+ refuses, because the merge cannot tell the agent's file from a second
+ database;
+- a `state/` the container uid cannot list and search, next to a
+ `workspace/` folder. F1 refuses before the database check, because the
+ merge cannot tell whether it holds a database.
In both cases the operator renames the folder from a helper Pod.
@@ -87,12 +92,12 @@ keep them; the database and its journals are already at the root.
stderr and exits 1 before the first move, leaving the tree unchanged. The Pod
stays in `Init:Error`.
-| Case | Line contains |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| F1: `workspace` or the PVC root is a symlink, not a directory, or escapes the root; a real `state/` or a present `workspace/` cannot be listed and searched; a `state.db*` entry is a symlink or not a regular file; a directory that decides a collision cannot be listed | `directory is a symlink`, `is not a directory`, `escapes the workspace PVC root`, `state directory is not readable and searchable`, `workspace directory is not readable and searchable`, `SQLite file is a symlink`, `SQLite file is not a regular file`, `cannot list directory` |
-| F2: more than one live database family across the root, `state/` and `workspace/` | `more than one live SQLite database` |
-| F3: a name to move already exists at the root, or under both `state/` and `workspace/`; `workspace/lost+found` exists | `destination exists`, `exists under both state/ and workspace/`, `lost+found would remain` |
-| F4: the PVC root, `state/`, `workspace/`, or a directory to be moved out of them is not writable by the container uid | `not writable by uid` |
+| Case | Line contains |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| F1: the PVC root is a symlink, not a directory, or resolves to `/`; `state/` or `workspace/` escapes the root or cannot be listed and searched; a database entry (`state.db`, `-wal`, `-shm`, `.pre-*.bak`) is a symlink or not a regular file; a directory that decides a collision cannot be listed | `directory is a symlink`, `is not a directory`, `escapes the workspace PVC root`, `state directory is not readable and searchable`, `workspace directory is not readable and searchable`, `SQLite file is a symlink`, `SQLite file is not a regular file`, `cannot list directory` |
+| F2: more than one live database family across the root, `state/` and `workspace/` | `more than one live SQLite database` |
+| F3: a name to move already exists at the root, or under both `state/` and `workspace/`; `workspace/lost+found` exists | `destination exists`, `exists under both state/ and workspace/`, `lost+found would remain` |
+| F4: the PVC root, `state/`, `workspace/`, or a directory to be moved out of them is not writable by the container uid | `not writable by uid` |
The PVC root checks of F1 run on every start, before the signature check.
diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.json
index 8aec35dbd..8bfacf3be 100644
--- a/host-context-controller/package-lock.json
+++ b/host-context-controller/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-host-context-controller",
- "version": "0.1.392",
+ "version": "0.1.393",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-host-context-controller",
- "version": "0.1.392",
+ "version": "0.1.393",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",
diff --git a/host-context-controller/package.json b/host-context-controller/package.json
index dc81601d2..2946c2a43 100644
--- a/host-context-controller/package.json
+++ b/host-context-controller/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-host-context-controller",
- "version": "0.1.392",
+ "version": "0.1.393",
"description": "Host Context Controller - provides McpServer CRDs to mcp-host via REST API",
"main": "dist/main.js",
"engines": {
diff --git a/host-context-controller/src/statelessDeployment.ts b/host-context-controller/src/statelessDeployment.ts
index 0dc175ec0..1249378f6 100644
--- a/host-context-controller/src/statelessDeployment.ts
+++ b/host-context-controller/src/statelessDeployment.ts
@@ -29,17 +29,19 @@ function shellSingleQuote(value: string): string {
* split with the earlier `workspace-layout-init` (agent files in
* `workspace/`, the database in `state/`) is merged back to that layout.
*
- * The merge runs only when `state/` is a real directory holding a
- * `state.db*` entry, the signature the earlier init leaves. Any other tree
- * exits 0 untouched: stateful, desktop, empty, a user folder named `state/`
- * or `workspace/`, and a `state` that is a symlink or not a directory (an
- * agent can create those on a stateful Host, so they must not stop it).
+ * The merge runs only on the signature the earlier init leaves: `state/`
+ * and `workspace/` are both real directories and `state/` holds a file the
+ * init writes (`state.db`, `state.db-wal`, `state.db-shm` or a
+ * `state.db*.pre-*.bak` copy). Any other tree exits 0 untouched: stateful,
+ * desktop, empty, a user folder named `state/` or `workspace/`, a `state/`
+ * holding other `state.db*` names, and a `state` or `workspace` that is a
+ * symlink or not a directory (an agent can create those on a stateful Host,
+ * so they must not stop it).
*
* Every refusal prints one line and exits 1 before the first move:
- * F1 `workspace` is a symlink or not a directory, a real `state/` or a
- * present `workspace/` cannot be listed and searched, a `state.db*` entry is a
- * symlink or not a regular file, or a directory that decides a
- * collision cannot be listed;
+ * F1 `state/` or `workspace/` cannot be listed and searched, a database
+ * entry is a symlink or not a regular file, or a directory that
+ * decides a collision cannot be listed;
* F2 more than one live database (a `state.db` main file or its journals)
* across the root, `state/` and `workspace/`, except the root journals
* a stopped merge leaves next to the remaining `state/state.db`;
@@ -94,29 +96,29 @@ has_journal() {
root_real="$(canonical_dir "$root")" || fail_merge "cannot resolve workspace PVC root: $root"
[ "$root_real" != "/" ] || fail_merge "workspace PVC root resolves to /"
-# Split-layout signature: a real state/ directory holding a state.db* entry.
+# Split-layout signature: real state/ and workspace/ directories, and a
+# database entry under state/.
[ ! -L "$root/state" ] && [ -d "$root/state" ] || exit 0
-# The glob below cannot see the entries of a state/ it cannot list or search.
+[ ! -L "$root/workspace" ] && [ -d "$root/workspace" ] || exit 0
+# The globs cannot see the entries of a state/ they cannot list or search.
[ -r "$root/state" ] && [ -x "$root/state" ] ||
fail_merge "state directory is not readable and searchable: $root/state"
+# Only the names the earlier init writes count: the database, its journals
+# and the .pre-<ts>.bak copies it keeps of an older source.
signature=0
-for entry in "$root/state"/state.db*; do
+for entry in "$root/state"/state.db "$root/state"/state.db-wal "$root/state"/state.db-shm "$root/state"/state.db*.pre-*.bak; do
if present "$entry"; then signature=1; fi
done
[ "$signature" -eq 1 ] || exit 0
# F1
assert_managed_dir "$root/state" state
-workspace_present=0
-if present "$root/workspace"; then
- assert_managed_dir "$root/workspace" workspace
- # The move globs cannot see the entries of a workspace/ they cannot list.
- [ -r "$root/workspace" ] && [ -x "$root/workspace" ] ||
- fail_merge "workspace directory is not readable and searchable: $root/workspace"
- workspace_present=1
-fi
+assert_managed_dir "$root/workspace" workspace
+# The move globs cannot see the entries of a workspace/ they cannot list.
+[ -r "$root/workspace" ] && [ -x "$root/workspace" ] ||
+ fail_merge "workspace directory is not readable and searchable: $root/workspace"
for dir in "$root" "$root/state" "$root/workspace"; do
- for entry in "$dir"/state.db*; do
+ for entry in "$dir"/state.db "$dir"/state.db-wal "$dir"/state.db-shm "$dir"/state.db*.pre-*.bak; do
present "$entry" || continue
[ ! -L "$entry" ] || fail_merge "SQLite file is a symlink: $entry"
[ -f "$entry" ] || fail_merge "SQLite file is not a regular file: $entry"
@@ -129,7 +131,7 @@ root_live=0
workspace_live=0
if has_main "$root" || has_journal "$root"; then root_live=1; live=$((live + 1)); fi
if has_main "$root/state" || has_journal "$root/state"; then live=$((live + 1)); fi
-if [ "$workspace_present" -eq 1 ] && { has_main "$root/workspace" || has_journal "$root/workspace"; }; then
+if has_main "$root/workspace" || has_journal "$root/workspace"; then
workspace_live=1
live=$((live + 1))
fi
@@ -142,69 +144,62 @@ if [ "$live" -gt 1 ] && [ "$resume" -eq 0 ]; then
fi
# F3
-if [ "$workspace_present" -eq 1 ]; then
- ! present "$root/workspace/lost+found" || fail_merge "workspace/lost+found would remain: $root/workspace/lost+found"
- for entry in "$root/workspace"/* "$root/workspace"/.[!.]* "$root/workspace"/..?*; do
- present "$entry" || continue
- base="$(basename "$entry")"
- if present "$root/$base"; then
- if is_empty_dir "$entry" && [ -d "$root/$base" ] && [ ! -L "$root/$base" ]; then continue; fi
- fail_merge "destination exists: $root/$base"
- fi
- done
-fi
+! present "$root/workspace/lost+found" || fail_merge "workspace/lost+found would remain: $root/workspace/lost+found"
+for entry in "$root/workspace"/* "$root/workspace"/.[!.]* "$root/workspace"/..?*; do
+ present "$entry" || continue
+ base="\${entry##*/}"
+ if present "$root/$base"; then
+ if is_empty_dir "$entry" && [ -d "$root/$base" ] && [ ! -L "$root/$base" ]; then continue; fi
+ fail_merge "destination exists: $root/$base"
+ fi
+done
for entry in "$root/state"/* "$root/state"/.[!.]* "$root/state"/..?*; do
present "$entry" || continue
- base="$(basename "$entry")"
+ base="\${entry##*/}"
if present "$root/$base"; then
if is_empty_dir "$entry" && [ -d "$root/$base" ] && [ ! -L "$root/$base" ]; then continue; fi
fail_merge "destination exists: $root/$base"
fi
- if [ "$workspace_present" -eq 1 ] && present "$root/workspace/$base"; then
+ if present "$root/workspace/$base"; then
fail_merge "$base exists under both state/ and workspace/"
fi
done
# F4
-for dir in "$root" "$root/state"; do
+for dir in "$root" "$root/state" "$root/workspace"; do
[ -w "$dir" ] || fail_merge "not writable by uid $(id -u): $dir"
done
-if [ "$workspace_present" -eq 1 ]; then
- [ -w "$root/workspace" ] || fail_merge "not writable by uid $(id -u): $root/workspace"
-fi
# Renaming a directory to a new parent rewrites its .. entry, which needs
# write permission on the directory itself.
for entry in "$root/workspace"/* "$root/workspace"/.[!.]* "$root/workspace"/..?* \\
"$root/state"/* "$root/state"/.[!.]* "$root/state"/..?*; do
[ -d "$entry" ] && [ ! -L "$entry" ] || continue
- ! present "$root/$(basename "$entry")" || continue
+ ! present "$root/\${entry##*/}" || continue
[ -w "$entry" ] || fail_merge "not writable by uid $(id -u): $entry"
done
move_to_root() {
entry="$1"
- base="$(basename "$entry")"
+ base="\${entry##*/}"
assert_managed_dir "$root/state" state
- if [ "$workspace_present" -eq 1 ]; then assert_managed_dir "$root/workspace" workspace; fi
+ assert_managed_dir "$root/workspace" workspace
if present "$root/$base"; then
rmdir "$entry"
else
mv "$entry" "$root/$base"
fi
}
-if [ "$workspace_present" -eq 1 ]; then
- for entry in "$root/workspace"/* "$root/workspace"/.[!.]* "$root/workspace"/..?*; do
- present "$entry" || continue
- move_to_root "$entry"
- done
-fi
+for entry in "$root/workspace"/* "$root/workspace"/.[!.]* "$root/workspace"/..?*; do
+ present "$entry" || continue
+ move_to_root "$entry"
+done
for entry in "$root/state"/* "$root/state"/.[!.]* "$root/state"/..?*; do
present "$entry" || continue
- [ "$(basename "$entry")" != state.db ] || continue
+ [ "\${entry##*/}" != state.db ] || continue
move_to_root "$entry"
done
if present "$root/state/state.db"; then move_to_root "$root/state/state.db"; fi
-if [ "$workspace_present" -eq 1 ]; then rmdir "$root/workspace"; fi
+rmdir "$root/workspace"
rmdir "$root/state"
sync
`
diff --git a/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts b/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts
index 97372642f..cc62502e8 100644
--- a/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts
+++ b/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts
@@ -219,30 +219,6 @@ describe('workspace layout merge', () => {
}, 15_000)
it.each([
- {
- name: 'workspace is a symlink',
- prepare: (root: string) => {
- renameSync(join(root, 'workspace'), join(root, 'workspace-real'))
- symlinkSync(join(root, 'workspace-real'), join(root, 'workspace'))
- },
- undo: (root: string) => {
- rmSync(join(root, 'workspace'))
- renameSync(join(root, 'workspace-real'), join(root, 'workspace'))
- },
- message: 'workspace directory is a symlink',
- },
- {
- name: 'workspace is a regular file',
- prepare: (root: string) => {
- renameSync(join(root, 'workspace'), join(root, 'workspace-real'))
- writeFileSync(join(root, 'workspace'), 'not a directory')
- },
- undo: (root: string) => {
- rmSync(join(root, 'workspace'))
- renameSync(join(root, 'workspace-real'), join(root, 'workspace'))
- },
- message: 'workspace path is not a directory',
- },
{
name: 'a state.db file is a symlink',
prepare: (root: string) => {
@@ -518,6 +494,22 @@ describe('workspace layout merge', () => {
expect(messageCount(join(root, 'state.db'))).toEqual({ rows: ROWS, check: 'ok' })
}, 15_000)
+ // $(basename ...) drops trailing newlines, which would rename the entry or
+ // report a collision with a different name.
+ it('moves an entry whose name ends in a newline under its exact name', () => {
+ const root = splitRoot()
+ writeFileSync(join(root, 'workspace', 'notes\n'), 'workspace file')
+ writeFileSync(join(root, 'state', 'SOUL.md\n'), 'state file')
+
+ expect(merge(root)).toEqual({ status: 0, stderr: '' })
+
+ expect(readFileSync(join(root, 'notes\n'), 'utf8')).toBe('workspace file')
+ expect(readFileSync(join(root, 'SOUL.md\n'), 'utf8')).toBe('state file')
+ expect(readdirSync(root)).not.toContain('notes')
+ expect(readFileSync(join(root, 'SOUL.md'), 'utf8')).toBe('SOUL.md content')
+ expect(messageCount(join(root, 'state.db'))).toEqual({ rows: ROWS, check: 'ok' })
+ }, 15_000)
+
it('removes an empty source directory whose name exists at the root', () => {
const root = splitRoot()
mkdirSync(join(root, 'workspace', 'state'))
@@ -603,6 +595,37 @@ describe('workspace layout merge', () => {
writeFileSync(join(root, 'elsewhere', 'SOUL.md'), 'user file')
symlinkSync(join(root, 'elsewhere'), join(root, 'workspace'))
},
+ // The base init writes only state.db, its journals and their .bak copies.
+ 'user state/ folder with other state.db* names': root => {
+ mkdirSync(join(root, 'state'))
+ for (const name of ['state.db.json', 'state.dbx', 'state.db.notes', 'config.yaml']) {
+ writeFileSync(join(root, 'state', name), 'user file')
+ }
+ mkdirSync(join(root, 'workspace'))
+ writeFileSync(join(root, 'workspace', 'README.md'), 'user file')
+ },
+ // A desktop PVC never held the database before v1; a user project in
+ // state/ must not be adopted as the conversation store.
+ 'desktop project state/{state.db,app.yml} without workspace/': root => {
+ for (const name of readdirSync(root).filter(n => n.startsWith('state.db'))) {
+ rmSync(join(root, name))
+ }
+ mkdirSync(join(root, 'state'))
+ writeFileSync(join(root, 'state', 'state.db'), 'user database')
+ writeFileSync(join(root, 'state', 'app.yml'), 'user file')
+ mkdirSync(join(root, 'Desktop'))
+ },
+ 'state/state.db with workspace a symlink': root => {
+ mkdirSync(join(root, 'state'))
+ writeFileSync(join(root, 'state', 'state.db'), 'user database')
+ mkdirSync(join(root, 'elsewhere'))
+ symlinkSync(join(root, 'elsewhere'), join(root, 'workspace'))
+ },
+ 'state/state.db with workspace a regular file': root => {
+ mkdirSync(join(root, 'state'))
+ writeFileSync(join(root, 'state', 'state.db'), 'user database')
+ writeFileSync(join(root, 'workspace'), 'user file')
+ },
}
for (const [name, prepare] of Object.entries(cases)) {
const root = statefulRoot()
diff --git a/scripts/e2e/e2e-hcc-storage-layout-switch.sh b/scripts/e2e/e2e-hcc-storage-layout-switch.sh
index ba2725f08..60b97ead8 100755
--- a/scripts/e2e/e2e-hcc-storage-layout-switch.sh
+++ b/scripts/e2e/e2e-hcc-storage-layout-switch.sh
@@ -501,9 +501,12 @@ done
cp state/state.db state/state.db.pre-20261014.bak
ln -s /tmp/e2e-825-link-target workspace/e2e-825-link
ls -la state workspace'
-# Two live database families: the root one and a copy under state/ (F2).
+# Two live database families: the root one and a copy under state/ (F2),
+# with workspace/ present so the tree carries the split-layout signature and
+# a file under each directory the merge would move.
# shellcheck disable=SC2016
-SEED_TWO_DB_SCRIPT='set -eu; cd "$1"; mkdir state; cp state.db state/state.db; ls -la . state'
+SEED_TWO_DB_SCRIPT='set -eu; cd "$1"; mkdir state workspace; cp state.db state/state.db
+printf "notes\n" > state/notes.txt; printf "x\n" > workspace/x; ls -la . state workspace'
read_seed_file() { # HOST NAME EXPECTED
local got
@@ -748,12 +751,17 @@ scenario_S5() {
# S6: two live database families: the merge refuses, the Pod stays in
# Init:Error and the tree is unchanged.
scenario_S6() {
- local name before after elapsed=0 pod logs
+ local name before after list_before list_after elapsed=0 pod logs
name="$(truncate_rfc1123 "e2e-825-s6-${RUN}")"
suspended_host_with_history "$name" || return 1
pvc_fixture "$name" rw seed-two-db "$SEED_TWO_DB_SCRIPT" >/dev/null || return 1
before="$(pvc_fixture "$name" ro hash-before "$HASH_SCRIPT")" || return 1
+ list_before="$(pvc_fixture "$name" ro list-before "$LIST_SCRIPT")" || return 1
grep -q ' ./state/state.db$' <<<"$before" || { fail "S6 witness: state/state.db not seeded: ${before}"; return 1; }
+ if ! grep -qx 'f ./state/notes.txt' <<<"$list_before" || ! grep -qx 'f ./workspace/x' <<<"$list_before"; then
+ fail "S6 witness: state/notes.txt or workspace/x not seeded: ${list_before}"
+ return 1
+ fi
post_wake "$name" || return 1
while [ "$elapsed" -lt "$POD_READY_TIMEOUT" ]; do
pod="$(host_pods "$name" | jq -r '[.items[] | select(any(.status.initContainerStatuses[]?;
@@ -773,6 +781,9 @@ scenario_S6() {
fi
after="$(pvc_fixture "$name" ro hash-after "$HASH_SCRIPT")" || return 1
[ "$before" = "$after" ] || { fail "S6: tree changed after the refusal"; diff <(echo "$before") <(echo "$after") >&2 || true; return 1; }
+ list_after="$(pvc_fixture "$name" ro list-after "$LIST_SCRIPT")" || return 1
+ [ "$list_before" = "$list_after" ] ||
+ { fail "S6: tree layout changed after the refusal"; diff <(echo "$list_before") <(echo "$list_after") >&2 || true; return 1; }
ok 'S6: two live families → Init:Error with the F2 line, tree unchanged'
}