Skip to content

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

TypeScript

docs(storage): document that root symlinks block a rollback init

Alfredo Lopezc3fb68eaeac6
diff --git a/docs/architecture/host-storage-layout.md b/docs/architecture/host-storage-layout.md
index 3128932a3..71ce0135d 100644
--- a/docs/architecture/host-storage-layout.md
+++ b/docs/architecture/host-storage-layout.md
@@ -116,6 +116,13 @@ forced by a deploy.
- Rolling HCC back is safe for stateful and stateless Hosts. The previous
`workspace-layout-init` re-splits stateless trees, and `workspace-layout-merge`
merges them again on roll-forward.
+- A merged root that holds a symlink (for example one an agent created under
+ `workspace/`, which the merge moved to the root) blocks the previous init:
+ it creates empty `state/` and `workspace/`, then exits 1 with
+ `legacy source is a symlink` and moves nothing, so the Host stays in
+ `Init:Error` with its history intact. Roll forward (the merge exits 0 and
+ keeps the two empty directories), or remove the root symlinks from a
+ helper Pod before the rollback.
- The deploy workflows roll HCC back automatically when its rollout gate fails
(`keyper-labs/evenfire-infra`, `deploy-clerum-dev.yml:715-742`,
`deploy-clerum-prod.yml:643-670`). This is safe for a Host in `Init:Error`,
diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.json
index 837d90a31..4cd0c713f 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.387",
+ "version": "0.1.388",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-host-context-controller",
- "version": "0.1.387",
+ "version": "0.1.388",
"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 756176347..d61f1aee9 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.387",
+ "version": "0.1.388",
"description": "Host Context Controller - provides McpServer CRDs to mcp-host via REST API",
"main": "dist/main.js",
"engines": {
diff --git a/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts b/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts
index 3372ebe00..6e5ba5497 100644
--- a/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts
+++ b/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts
@@ -497,4 +497,28 @@ describe('workspace layout merge', () => {
expect(snapshot(root)).toEqual(merged)
expect(messageCount(join(root, 'state.db'))).toEqual({ rows: ROWS, check: 'ok' })
}, 15_000)
+
+ it('a rollback init refuses a merged root holding a symlink and moves nothing', () => {
+ const root = splitRoot()
+ symlinkSync('/tmp/evenfire', join(root, 'workspace', 'evenfire'))
+ expect(merge(root).status).toBe(0)
+ const merged = snapshot(root)
+ expect(merged.evenfire).toBe('link:/tmp/evenfire')
+
+ const rolledBack = runScript(readFileSync(BASE_INIT, 'utf8'), [root])
+
+ expect(rolledBack.status).toBe(1)
+ expect(rolledBack.stderr).toContain(`legacy source is a symlink: ${root}/evenfire`)
+ // It creates its two empty directories before validating the sources.
+ const refusedTree = { ...merged, state: 'dir', workspace: 'dir' }
+ expect(snapshot(root)).toEqual(refusedTree)
+ // Rolling forward leaves those empty directories and the history intact.
+ expect(merge(root)).toEqual({ status: 0, stderr: '' })
+ expect(snapshot(root)).toEqual(refusedTree)
+ expect(messageCount(join(root, 'state.db'))).toEqual({ rows: ROWS, check: 'ok' })
+ // Witness: without the root symlink the same rollback init splits the tree.
+ rmSync(join(root, 'evenfire'))
+ baseInit(root)
+ expect(readdirSync(join(root, 'state'))).toContain('state.db')
+ }, 15_000)
})